CLI Reference
Quick reference for the Sophon command-line interface.
The sophon CLI is documented in full under Command Line. This page is a quick cheat sheet.
Install
dotnet tool install -g sophon-cliCommon commands
sophon onboard # first-run setup (provider + profile)
sophon # interactive chat REPL
sophon -c # continue this repository's last session
sophon -m auto:balanced # chat with an Auto model choice for this conversation
sophon -e high # chat at a set effort (auto, low, medium, high, xhigh, max, inherit)
sophon doctor # diagnose configuration issues
sophon status # quick system snapshot
# Headless runs (scripts and CI)
sophon -p "<prompt>" # same as: sophon exec "<prompt>"
sophon -p "<prompt>" --output-format stream-json
sophon exec - --output-format json < prompt.txt
sophon -p "<prompt>" --trust-workspace --allow "os.execute:dotnet test"
sophon -p "<prompt>" -e low # the run's effort
# Models & providers
sophon models list --details
sophon models add # interactive
sophon models test <id>
sophon models remove <id>
sophon models set-default <id> [model]
sophon models enable <id>
sophon models disable <id>
sophon models discover <id> --add <model>,<model>
sophon models context <id> <model> <tokens>
sophon models roles --profile local-first # host routing defaults (admin)
sophon models resolve --session <session-id>
sophon models embeddings status
sophon agents models <agent-id> --auto economy
sophon agents models <agent-id> --effort high
# Plans
sophon plans list --status Interrupted
sophon plans show <runId>
sophon plans resume <runId>
sophon plans retry <runId>
sophon plans cancel <runId>
# Channels & connections
sophon channels list
sophon channels add
sophon channels test <id>
sophon connect list
sophon connect test <id>
# Skills & agent packages
sophon skills list
sophon skills install <id>
sophon skills search <query> --type agent # skill, plugin or agent
sophon agents search <query> # marketplace agent packages
sophon agents install <name> --with-skills # or --file ./helper.sophon-agent
sophon agents updates --check
sophon agents update <agent-id>
sophon agents export <agent-id> --output ./dist
sophon agents publish <agent-id>
sophon dev publish --key smk_… # build and publish a package project
# Workflows & automation
sophon workflows list
sophon workflows validate <file>
sophon workflows execute <id>
sophon cron list
sophon cron add --name <name> --cron "<expr>" --message "<text>"
# Memory & documents
sophon memory search "<query>"
sophon docs upload <file>
sophon docs ask <id> "<question>"
# Sessions, tasks & approvals
sophon sessions list
sophon tasks active
sophon approvals pending
sophon approvals decide <id> --approve
# Config & auth
sophon config list
sophon config set <key> <value>
sophon login
sophon whoamiWorkflows
New in 2.2. execute starts the run in the background and follows it, printing each step as it changes; it exits 0 when the run succeeded, 1 when it failed, was cancelled or was interrupted, and 130 on Ctrl+C (which stops following, not the run).
sophon workflows validate digest.json # the issues a save would report; nothing is saved
sophon workflows create --file digest.json
sophon workflows execute <id> # start and follow; exit by the run's outcome
sophon workflows execute <id> --async # print the run id and return
sophon workflows runs [<id>] --status failed --trigger cron --limit 20
sophon workflows runs <id> --before <cursor> # the next page, from the More: line
sophon workflows run wfr_… --details # one run: steps, attempts, errors, tokens, cost
sophon workflows run wfr_… --follow # follow a run still going
sophon workflows cancel-run wfr_…
sophon workflows history <id> --limit 5| Command | What it does |
|---|---|
validate <file> | Posts the file to POST /api/workflows/validate and prints one line per issue; exits 1 when an issue is an error |
execute <id> [--async] | Starts a run with POST /api/workflows/{id}/runs and follows it, or with --async prints the run id |
runs [<workflowId>] | Runs newest first; --status, --trigger, --limit (1-100), --before |
run <runId> [--details] [--follow] | One run with every step attempt; --details adds inputs (redacted) and outputs |
cancel-run <runId> | Asks the Gateway to stop the run |
history <id> [--limit] | The history route, on every Gateway |
Run ids are the full wfr_… id. Against a Gateway older than v2.2.0, execute runs synchronously and run, cancel-run and execute --async say the Gateway needs v2.2.0. The CLI has no re-run or sample-input command. See Workflows.
Removed in v2.2.0
| Removed | Use instead |
|---|---|
sophon discuss (every subcommand) | Nothing: Discussions were removed |
sophon push preferences set --discussions | Nothing |
sophon exec --thinking | -e / --effort (the old flag exits 1 naming --effort) |
cli.json defaultThinking | sophon config set defaultEffort <level> (an old defaultThinking is still read until then) |
/thinking | /effort |
/provider | /model |
/quit | /exit |
/select | F2 on the full-screen surface |
/tokens, /info | /context |
/tasks | sophon tasks active |
/approvals | sophon approvals pending |
/agents | /agent |
/sessions | /resume |
/auto-approve | /permissions auto-approve |
For one release, typing a removed slash command prints what replaced it.
Global options
| Option | Description |
|---|---|
--gateway-url, -g | Gateway URL (default http://localhost:8080) |
--format, -f | Output format: table, json, csv |
--json | Shorthand for --format json |
--no-color | Disable colored output (honors NO_COLOR) |
--verbose, -v | Verbose output |
--version | Show version |
Headless exit codes
sophon exec and sophon -p exit with 0 on success, 1 on a failure, timeout, lost connection or usage error, 2 when the run needed something and was denied, and 130 when it was interrupted. A headless run never approves a card. See Headless runs.
In the chat
| Command | What it does |
|---|---|
/model | Show or change this conversation's model (list, auto [profile], role, fallback, reset, save) |
/effort | Show or set this conversation's effort (auto, low, medium, high, xhigh, max, reset, save); replaces /thinking |
/agent, /resume | Switch agent or resume a session; bare, each opens a picker |
/theme | Switch the color theme |
/permissions | Permission mode (default, accept-edits, plan), standing rules, plan approval |
Shift+Tab | Cycle the permission mode (full screen and classic) |
/trust | Workspace trust for this folder |
/diff, /rewind [n] | Review and undo the session's edits |
/init | Ask the agent to write AGENTS.md |
/todos, /subagents | The agent's checklist and its child agents |
/context | Context window, tokens, cost, model and mode |
/plan, /retry [runId] | Show the latest plan; resume, retry or continue a stopped one |
The full list is on Interactive Chat.
See the full Command Reference for every command and option, and Scripting & Automation for CI/JSON usage.