Docs

CLI.

The agent, scriptable, interactive, and shared with the Mac app runtime.

picasso / docs / cliindexed

Docs

CLI

The agent, scriptable, interactive, and shared with the Mac app runtime.

picassoStart the interactive agent in the current workspace.

picasso runRun a prompt non-interactively for scripts, CI, or one-off checks.

picasso goalCreate, validate, run, inspect, pause, resume, stop, and read events or logs for long-horizon goals.

FlagUse--mode safe.Read and approved writes. Default for most workspaces.--mode auto.Allow safe operation classes to proceed without repeated prompts.--mode paranoid.Hide terminal sponsor surfaces and tighten permissions.

picasso run "summarize the auth module" --jsonpicasso plan "replace bcrypt with argon2id" --cwd apps/apipicasso goal create "ship the billing migration" --max-wall-time 4h --max-cost-usd 5

Commands.

picasso.

Start the interactive agent in the current workspace.

picasso run.

Run a prompt non-interactively for scripts, CI, or one-off checks.

picasso goal.

Create, validate, run, inspect, pause, resume, stop, and read events or logs for long-horizon goals.

Give it the outcome.

picasso plan.

Enter read-only architecture mode, draft a plan without executing it, or validate a saved plan document.

First, the plan.

picasso memory.

Initialize, list, inspect, edit, delete, pin, unpin, export, import, sync, clear, and dedupe runtime memory.

It remembers.

picasso replay.

Inspect a recorded session journal by session id, optionally limited to an event or thread.

picasso subagent.

List roles, run a bounded local subagent task, inspect status, or cancel a run.

Many minds. One outcome.

picasso auth.

Choose the model.

picasso mcp.

Search, install, enable, disable, serve, and inspect MCP servers.

Connect the tools.

picasso sponsors.

Inspect disclosures, block sponsors, and configure terminal sponsor surfaces.

Sponsored model unlocks.

Flags you will use.

Flag	Use
--mode safe.	Read and approved writes. Default for most workspaces.
--mode auto.	Allow safe operation classes to proceed without repeated prompts.
--mode paranoid.	Hide terminal sponsor surfaces and tighten permissions.
--memory-enabled.	Enable runtime memory for `picasso run`.
--memory-mode <mode>.	Set runtime memory mode: off, read, or read-write.
--memory-sync.	Request memory sync when a sync backend is configured.
--provider <name>.	Select a provider for this session or command.
--model <model>.	Override the configured model route.
--json.	Emit structured output for scripts.
--cwd <path>.	Run against a specific workspace.

Examples.

picasso run "summarize the auth module" --json

picasso plan "replace bcrypt with argon2id" --cwd apps/api

picasso goal create "ship the billing migration" --max-wall-time 4h --max-cost-usd 5

picasso goal run <goal-id> --confirm-contract --approved-by ada@example.com

picasso replay <session-id> --to-event 48

picasso subagent run reviewer "review auth changes"

picasso memory export > picasso-memory.jsonl

picasso mcp install github && picasso mcp enable github

Exit codes.

Code	Meaning
0.	Completed successfully.
1.	Command failed or verification failed.
2.	Invalid flags, config, or command syntax.
3.	Permission denied by mode, sandbox, or approval policy.
4.	Provider, network, or MCP dependency unavailable.