CLI reference

pond is Pond's command line tool. It talks to the running Pond app over a local socket, so Pond must be running.

Install

In Settings › General, click Install pond command. It links the bundled binary into ~/.local/bin, so it needs no admin password. Make sure ~/.local/bin is on your PATH. Run pond --help to list the commands.

Commands

Command	Example
Start a task in the current repo	pond new "fix the login bug" (--here uses the current worktree; --from <branch> starts on an existing branch and --from-pr <number> on an open pull request's branch; --project <dir>, --model and --effort also work)
List agents	pond list (--all includes ended ones, --json for scripts)
Install the command	pond install
Add a project	pond project add . --test-command "npm test"
Set up new worktrees	pond project add . --setup "npm ci" --copy apps/web/.env
Set the Run command	pond project add . --run "npm run dev -- --port $PORT"
Set a project's priority	pond project add . --priority high (high, normal or low; pond project list --json shows it)
List projects	pond project list
Start a task with options	pond task new --project . --computer Safari < task.txt (--no-browser turns the browser off for it)
Stop a task	pond task stop <id> (--close also closes it)
List agents with details	pond agents --json
Send text to an agent	pond term send <id or title> < message.txt
Interrupt an agent	pond term stop <id or title>
Merge a worktree	pond merge <worktree> --dry-run (--remove-worktree removes it afterwards)
Preview a push and draft PR	pond pr <worktree> --dry-run
Run the project's tests	pond tests run <worktree>
Open a worktree in your editor	pond open <worktree> (--editor vscode|cursor|zed|xcode|sublime)
Remove a worktree	pond worktree remove <name or path>
Open the browser preview	pond open-preview (or pond open-preview http://localhost:5173/)

Notes

• <id or title> accepts an agent id, a terminal id, or a title: the terminal name, branch or worktree folder, in any case. If two live agents match, pond says so and asks for the id.
• pond worktree remove refuses when there are uncommitted changes, commits not merged into the default branch, a lock, or an agent still open there. --force drops changes but keeps a branch with unmerged commits. It is for you, not for agents: an agent that passes --force is refused. A worktree Pond did not make (not under <repo>-pond/, for example Orca's) needs --outside, keeps its branch, and is refused from an agent. --force and --outside need Pond's terminal helper running (it tells Pond who is asking; open Pond and a terminal in it); without it they are refused. The helper stops by itself after 10 minutes with no terminal. pond merge --outside goes only with --remove-worktree.
• pond open starts an editor on your screen, so agents cannot run it. Without --editor it uses the editor chosen in Settings › General › Open worktrees in, or the first one it finds (VS Code, Cursor, Zed, Xcode, Sublime Text).
• pond pr --dry-run prints the remote, branch, title and the exact git and gh commands. It never pushes. The push itself is Push and open draft PR… in the worktree's menu, after its confirm sheet.
• An agent can reach only its own terminal and its workers' terminals.
• pond mcp, pond computer-mcp and pond browser-mcp are started by Claude Code for its sessions. You do not run them yourself.

New worktrees

When Pond makes a worktree for a new task, it copies .env and .env.local from the project's own folder, if they exist and git ignores them. Anything that git does not ignore is skipped, so a copied file is never committed.

• --copy <path> adds a file to that list. The path is inside the repo. Repeat the flag for more files, up to 20.
• --no-copy empties the list first.
• Files are cloned with their mode kept, never linked, and never copied over a file the worktree already has.
• --setup "<cmd>" runs that one line with /bin/sh in the agent's terminal, where you can watch it, before Claude Code starts. --setup "" removes it.
• If the setup command fails, the terminal says so and the task is not typed. Return in that terminal starts Claude Code anyway.

Both settings live in Pond's own folder, not in the repo. Only you can set them: an agent that passes them is refused.

The Run command

--run "<cmd>" sets the line that a worktree row's Run starts. Set run command… on the project row does the same, and --run "" removes it.

Run starts the command with /bin/sh in its own terminal in that worktree, with PORT set to a free port on 127.0.0.1 (from 4200 to 4899). The port stays with the worktree until you remove it, so several worktrees can run their dev servers at the same time. If you click Run again while it still runs, you get the same terminal, not a second server.

Pond only sets the variable. Next and Express read PORT. Vite does not, so write npm run dev -- --port $PORT --strictPort. Only you can set the Run command: an agent that passes --run is refused.