CLI

cusp [options] [prompt]

cusp starts an interactive session in the current folder. With a prompt, the session starts with that message. With -p, it runs the prompt without the UI, prints the result and exits.

ExamplesCopy Anchor Link

cusp                                     # interactive session in this folder
cusp "explain the build pipeline"        # start with a prompt
cusp -c                                  # continue the most recent session here
cusp -r                                  # pick a session to resume
cusp -m openai:gpt-6.1-sol --effort high # choose model and effort
cusp -p "list TODO comments in src/"     # headless: print the answer and exit
cat error.log | cusp -p "what failed?"   # headless with piped input

OptionsCopy Anchor Link

SessionCopy Anchor Link

--continue and --resume can't be combined. --fork-session requires one of them.

Model and permissionsCopy Anchor Link

--allowedTools and --disallowedTools also accept the kebab-case spellings --allowed-tools and --disallowed-tools. Lists can be comma- or space-separated; Cusp never splits inside parentheses, so "Bash(git log *),Edit" is two rules. The manual mode name is accepted as an alias for default.

HeadlessCopy Anchor Link

--output-format and --input-format require -p. -p can't open the session picker, so --resume needs an explicit id in headless mode.

DaemonCopy Anchor Link

OtherCopy Anchor Link

Exit codesCopy Anchor Link

Headless modeCopy Anchor Link

cusp -p runs one prompt and exits. The prompt comes from the arguments, from stdin, or both: piped input is read when stdin isn't a terminal.

Nobody can answer prompts in headless mode, so:

• Permission requests are decided by --allowedTools and --disallowedTools. Anything not pre-approved is denied, and the agent is told how to proceed. Every denial is listed in permission_denials in the JSON result.
• Questions from the agent (AskUserQuestion) are answered with "No answer: running non-interactively. Use your best judgment and state the assumption."
• Workspace trust prompts don't appear.

# Allow tests and edits, nothing else
cusp -p "make the failing test in auth.test.ts pass" \
  --allowedTools "Bash(bun test *)" Edit Write \
  --max-turns 25 \
  --output-format json

text outputCopy Anchor Link

The final assistant message, as plain text. Errors go to stderr.

json outputCopy Anchor Link

A single JSON object when the run ends. Field names follow the widely used headless result format (type, subtype, result, session_id, total_cost_usd, …), so existing scripts that parse it keep working.

{
  "type": "result",
  "subtype": "success",
  "is_error": false,
  "result": "Fixed the token expiry check in src/auth/session.ts. All 48 tests pass.",
  "session_id": "ses_01JCQ8Z4X9T5V2M3N7K1P6R0WA",
  "num_turns": 7,
  "duration_ms": 41873,
  "total_cost_usd": 0.0871,
  "usage": {
    "input_tokens": 182340,
    "output_tokens": 2911,
    "reasoning_tokens": 1404,
    "cache_read_input_tokens": 151200,
    "cache_creation_input_tokens": 18420
  },
  "permission_denials": []
}

stream-json outputCopy Anchor Link

One JSON object per line while the run is in progress, then the same result object as json on the last line.

The first line describes the run:

{"type":"system","subtype":"init","session_id":"ses_01JC…","cwd":"/Users/me/code/app","model":{"providerId":"anthropic","modelId":"claude-opus-5-5"},"permission_mode":"default","cusp_version":"0.1.0","daemon":"spawned"}

Each following line wraps one session event:

{"type":"event","session_id":"ses_01JC…","event":{"seq":12,"body":{"type":"tool.start", …}}}

Streaming deltas (assistant.delta, tool.progress) are included only with --include-partial-messages.

stream-json inputCopy Anchor Link

With --input-format stream-json, each line on stdin is a user message:

{"type":"user","message":{"role":"user","content":"Now add tests for it."}}

content can be a string or an array of content blocks ({"type":"text","text":"…"}, images and so on). This lets another program hold a multi-turn conversation with Cusp over a pipe.

Interactive modeCopy Anchor Link

Slash commandsCopy Anchor Link

Skills you can invoke appear in the same / menu.

Prompt prefixesCopy Anchor Link

Keyboard shortcuts are listed in Keyboard shortcuts.

Environment variablesCopy Anchor Link