Skip to Content
Sophon Docs
API Reference

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-cli

Common 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 whoami

Workflows

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
CommandWhat 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

RemovedUse instead
sophon discuss (every subcommand)Nothing: Discussions were removed
sophon push preferences set --discussionsNothing
sophon exec --thinking-e / --effort (the old flag exits 1 naming --effort)
cli.json defaultThinkingsophon config set defaultEffort <level> (an old defaultThinking is still read until then)
/thinking/effort
/provider/model
/quit/exit
/selectF2 on the full-screen surface
/tokens, /info/context
/taskssophon tasks active
/approvalssophon 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

OptionDescription
--gateway-url, -gGateway URL (default http://localhost:8080)
--format, -fOutput format: table, json, csv
--jsonShorthand for --format json
--no-colorDisable colored output (honors NO_COLOR)
--verbose, -vVerbose output
--versionShow 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

CommandWhat it does
/modelShow or change this conversation's model (list, auto [profile], role, fallback, reset, save)
/effortShow or set this conversation's effort (auto, low, medium, high, xhigh, max, reset, save); replaces /thinking
/agent, /resumeSwitch agent or resume a session; bare, each opens a picker
/themeSwitch the color theme
/permissionsPermission mode (default, accept-edits, plan), standing rules, plan approval
Shift+TabCycle the permission mode (full screen and classic)
/trustWorkspace trust for this folder
/diff, /rewind [n]Review and undo the session's edits
/initAsk the agent to write AGENTS.md
/todos, /subagentsThe agent's checklist and its child agents
/contextContext 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.