Command-Line Tool

The runlet command opens folders, PHP and SQL files, and workspaces in Runlet from a terminal:

cd ~/Code/my-app
runlet .

It only opens them: nothing runs until you press Run, and the command itself never runs PHP. runlet mcp is different: it serves AI clients, which can ask Runlet to run code, and every such run waits for your approval in Runlet.

Installing the Tool

Choose Runlet ▸ Install Command-Line Tool… (also in Settings ▸ General ▸ Command-Line Tool, and in the command palette). Pick a folder and press Install. Runlet creates one symbolic link, <folder>/runlet, to the tool inside the app, and nothing else.

Folder	Notes
/usr/local/bin	On every shell's PATH. When you can't write to it (usual on Intel Macs without Homebrew), macOS asks for an administrator's password, used only to create the folder and the link.
~/.local/bin	No password. The window says whether it's on your shell's PATH and, if not, which line to add to ~/.zprofile.
Another folder…	Any folder you choose, with the same checks.

The window shows exactly which link it creates.

• It never replaces a file that isn't Runlet's link. A link to another copy of Runlet is replaced only when you press Replace.
• Remove Link deletes the link (only if it is one).
• The link points into the app, so the command follows updates. If you move Runlet.app, install it again.

NOTE

Open Runlet from the Applications folder before you install the tool. macOS runs a freshly downloaded app from a temporary location, and Runlet won't link to that.

To install it by hand instead:

ln -s /Applications/Runlet.app/Contents/Helpers/runlet ~/.local/bin/runlet

Opening Folders and Files

runlet                       open the current folder as a project (same as `runlet .`)
runlet <folder>              open a folder as a local project
runlet <file.php>            open a file in a tab; saving writes back to it
runlet <query.sql>           open an SQL file in an SQL tab
runlet <name.runlet>         open a workspace in its own window
runlet -t <target> <file>    open files on a target
runlet -t <target>           open a new tab on a target
runlet -n …                  open in a new window
runlet mcp                   serve AI clients over MCP
runlet --help | --version

• Folders open as local projects, the same as File ▸ Open Project…. A project you already have for that folder is reused. It opens in the current tab when that tab is blank, and in a new tab otherwise. Your home folder and / are refused: indexing all of it for completion would take too long.
• Files open as from Finder: a file that's already open gets its tab selected. The tab follows the file on disk, and saving writes back to it. .sql files open in SQL tabs.
• Workspaces (.runlet files) open in their own window, with their tabs' targets.
• Several paths open in order. Paths are relative to the current folder, with symbolic links kept as you typed them.

Choosing a Target

-t (or --target) opens files, or a new tab, on a target other than the current one:

runlet -t staging scripts/fix-orders.php
runlet -t docker:shop

It takes sandbox, a local project's name or folder, or a Docker or SSH profile's name, ignoring case:

• An exact name wins, then a unique prefix (-t acme).
• When several targets share a name, write local:<name>, docker:<name>, or ssh:<name>.
• Opening a file on an SSH target never connects to the server.

--target can't be combined with folders or workspaces.

Exit Status

Status	Means
0	Everything opened.
1	Runlet reported a problem (printed as runlet: …), or didn't answer within 60 seconds.
64	The command was used wrongly.
69	Runlet.app couldn't be found.

NOTE

Reading code from standard input (runlet -) isn't supported yet.

AI Clients

runlet mcp is an MCP server for AI clients such as Claude Code and Cursor. Add it to your AI client rather than running it yourself: Settings ▸ AI Clients shows the exact setup, and AI Clients explains it. Started by hand in a terminal, it explains this and exits.

To open a folder named mcp, write runlet ./mcp.