What it is for
The CLI is not a cut-down companion to the editor. It runs the same agent against the same models with the same tool access, which makes three things possible that the desktop app cannot do.
- Remote work. A session over SSH on a build box or a GPU host behaves like a local one. No display, no port forwarding, no remote-development extension.
- Scripted work. With
--printthe agent becomes a normal Unix process: stdin, stdout, exit code. You can call it from a Makefile, a Git hook or a CI job. - Parallel work. Combined with
--worktree, you can run several agents on the same repository at once without any of them stepping on each other's files.
Interactive mode
Typing agent in a repository opens a session scoped to that directory. From there the interface is driven by slash commands rather than menus, and the ones worth learning first are /model, /plan and /summarize.
An initial prompt can be passed as an argument, which saves a round trip:
agent "work out why the auth tests are flaky"Sessions persist. agent ls lists recent chats and lets you pick one, and agent resume jumps straight back into the latest. That matters more on the CLI than in the editor, because a terminal tab is much easier to close by accident than a window.
Non-interactive mode
--print is the flag that turns the CLI into a component of some larger pipeline. It writes the response to stdout and exits.
agent -p "summarise the changes in the last commit" \
--output-format jsonTwo details are easy to miss. First, the format flag only does anything alongside --print. Second, and more importantly, print mode is not read-only. Cursor's own reference states that it has access to all tools, including write and shell. Running it against a prompt you did not write, in a directory you care about, is a real risk.
The mitigation is the sandbox. --sandbox enabled confines shell execution, and agent sandbox run can wrap a single command with explicit read and write paths and network access off by default.
Running several agents at once
The worktree flags exist because the obvious approach, opening three terminals in the same folder, does not work. Three agents editing one working tree produce conflicts that none of them can see.
agent -w fix-auth "make the auth tests deterministic"
agent -w add-cache "add a redis cache to the session store"Each run gets a directory under ~/.cursor/worktrees/<repo>/<name> with its own checkout. Setup scripts defined in .cursor/worktrees.json run automatically unless you pass --skip-worktree-setup, which is how dependency installation gets handled for the new directory.
Modes from the terminal
Plan, Ask and Debug are all reachable. --plan starts a session in Plan mode so the agent drafts an approach before editing anything; /ask flips to read-only questions; /debug switches to the mode that reproduces a failure before attempting a fix. There is also /goal, which hands the agent a long-lived objective to work towards across multiple turns rather than a single task.
Command tables transcribed from the parameters reference and the slash command reference on 25 September 2026.