Scape CLI & URL Scheme

Scape is a first-class dispatch target. Point anything at a path — your shell, a script, a link, Finder — and Scape focuses the project that owns it, or adds it as a new project if it doesn't know it yet.

Install the scape command

Help → Install 'scape' Command in PATH (also in Settings → Developer Tools). On most Macs /usr/local/bin is owned by root, so macOS will ask for your password once.

The installed command survives app updates and even moving Scape.app — it's a symlink to a stable copy that the app refreshes on launch.

Open from the terminal

scape .                      # open the current directory
scape ~/dev/my-app           # focus the project that owns this repo
scape src/server.ts          # open the owning project and reveal the file

• A path Scape already knows focuses that project (and its window).
• An unknown repo or folder is added as a new project and opened.
• A file path opens the owning repo and reveals the file in the editor.
• If Scape isn't running, the CLI launches it and waits for the open to land.

Opens are idempotent — running the same command twice just focuses.

Start an agent

scape open ~/dev/my-app --agent claude-code --prompt "run the tests and fix failures"

--agent starts a session in that directory with any installed harness (claude-code, codex, opencode, pi). Add --prompt to seed the first message and --model to pick a model. Agent start is CLI-only — it never works from a URL (see below).

Scripting with --json

scape open ~/dev/my-app --json

Prints one JSON object describing what happened:

{
  "ok": true,
  "action": "focused",
  "project": { "id": "…", "name": "my-app", "repoPath": "/Users/you/dev/my-app" }
}

action is focused or added; with --agent a session object is included. Exit codes make shell scripting predictable:

scape:// URLs

Any link or app can deep-link into a project:

scape://open?path=/Users/you/dev/my-app

Because a web page can trigger this with a plain anchor tag, the URL surface is deliberately less trusted than the CLI:

• A known path focuses the project, same as the CLI.
• An unknown path shows a consent sheet first — a link can never silently add a folder to Scape. You see the path and approve or decline.
• Agent parameters are refused on URLs. Starting an agent requires the CLI.

Finder, Dock, and open

Scape registers as a handler for folders, so the standard macOS gestures work too:

• Right-click a folder → Open With → Scape
• Drag a folder onto the Dock icon
• open -a Scape ~/dev/my-app

These count as deliberate user gestures, so unknown folders are added without a consent sheet — same as the CLI.