Command Reference

Every Sophon CLI command and subcommand, grouped by area, with options and examples.

Every Sophon command follows the same shape:

sophon <group> <command> [arguments] [options]

Add --help to any group or command to see its subcommands, arguments, and options inline — e.g. sophon workflows --help or sophon nodes command --help. Global options (--gateway-url/-g, --format/-f, --json, --no-color, --verbose/-v) work on every command. See Configuration & Auth for those, and Scripting & Automation for piping --json output.

Running sophon with no arguments (or sophon chat) opens the interactive chat REPL. Everything below is the non-interactive command surface that talks to the Gateway's REST API.

Chat & sessions

Command	Description	Example
`sophon chat`	Open the interactive chat REPL (`--session/-s`, `--agent/-a`)	`sophon chat -a researcher`
`sophon sessions list`	List chat sessions	`sophon sessions list`
`sophon sessions get <id>`	Show session details	`sophon sessions get abc123`
`sophon sessions rename <id> <title>`	Rename a session	`sophon sessions rename abc123 "Q3 planning"`
`sophon sessions archive <id>`	Archive a session	`sophon sessions archive abc123`
`sophon sessions delete <id>`	Delete a session (and its messages)	`sophon sessions delete abc123`
`sophon sessions events <id>`	List events for a session	`sophon sessions events abc123`
`sophon runs active`	List active session runs	`sophon runs active`
`sophon runs get <id>`	Show run details	`sophon runs get run_42`
`sophon runs cancel <id>`	Cancel a run	`sophon runs cancel run_42`
`sophon runs wait <id>`	Long-poll until a run completes (`--timeout`)	`sophon runs wait run_42 --timeout 600`
`sophon tasks active`	List active background tasks	`sophon tasks active`
`sophon tasks recent`	List recently finished tasks (`--limit`)	`sophon tasks recent --limit 20`
`sophon tasks cancel <id>`	Cancel a running task	`sophon tasks cancel task_7`
`sophon tasks watch`	Stream task lifecycle events live	`sophon tasks watch`
`sophon plans cancel <id>`	Cancel an active plan via the chat hub	`sophon plans cancel plan_3`

Agents & models

Command	Description	Example
`sophon agents list`	List agents	`sophon agents list`
`sophon agents get <id>`	Show agent details	`sophon agents get default`
`sophon agents create`	Create an agent (`--id`, `--name`, `--description`, `--system-prompt`)	`sophon agents create --id researcher --name Researcher`
`sophon agents delete <id>`	Delete an agent	`sophon agents delete researcher`
`sophon agents soul <id>`	View or edit an agent's SOUL.md (`--edit` opens `$EDITOR`)	`sophon agents soul researcher --edit`
`sophon models list`	List configured model providers	`sophon models list`
`sophon models add`	Add a provider (interactive)	`sophon models add`
`sophon models test <id>`	Test a provider connection	`sophon models test anthropic-1`
`sophon models remove <id>`	Remove a provider	`sophon models remove anthropic-1`
`sophon models gpu`	Detect GPU hardware and estimate model fit (`--model`, `--quantization`)	`sophon models gpu --model llama-3-70b`
`sophon models github-copilot login`	GitHub Copilot device-flow login (`--name`)	`sophon models github-copilot login`
`sophon usage [providerId]`	View LLM usage and cost tracking	`sophon usage anthropic-1`
`sophon tools`	List registered tools	`sophon tools --json`

Channels & connections

Command	Description	Example
`sophon channels list`	List configured channels	`sophon channels list`
`sophon channels add`	Add a channel (interactive: telegram, slack, discord, email, …)	`sophon channels add`
`sophon channels test <id>`	Test a channel connection	`sophon channels test slack-1`
`sophon channels enable <id>`	Enable a channel	`sophon channels enable slack-1`
`sophon channels disable <id>`	Disable a channel	`sophon channels disable slack-1`
`sophon channels remove <id>`	Remove a channel	`sophon channels remove slack-1`
`sophon channels routing <channel-id>`	Configure per-channel routing (`--agent AGENT_ID`, `--dm-behavior B`, `--group-behavior B`, `--allow GROUP_ID …`) — see Group Chats	`sophon channels routing slack-1 --agent support`
`sophon connect list`	List connected services and available connectors	`sophon connect list`
`sophon connect service <service>`	Connect via OAuth or token (`--remote`, `--stdin`)	`sophon connect service github`
`sophon connect test <service>`	Test a service connection	`sophon connect test github`
`sophon connect revoke <service>`	Disconnect and revoke a service	`sophon connect revoke github`

Per-channel debounce overrides (enable/disable, quiet-window duration) are configured through the Dashboard or server config; explicit channels routing debounce flags are on the roadmap.

Skills, workflows & automation

Command	Description	Example
`sophon skills list`	List installed skills	`sophon skills list`
`sophon skills get <id>`	Show skill details	`sophon skills get pdf-tools`
`sophon skills delete <id>`	Delete a skill	`sophon skills delete pdf-tools`
`sophon skills search <query>`	Search the marketplace	`sophon skills search pdf`
`sophon skills marketplace`	Browse the marketplace (alias for `search`)	`sophon skills marketplace`
`sophon skills install <skillId>`	Install a marketplace package	`sophon skills install pdf-tools`
`sophon skills update [skillId]`	Check for and apply marketplace package updates	`sophon skills update pdf-tools`
`sophon skills uninstall <skillId>`	Uninstall a marketplace package	`sophon skills uninstall pdf-tools`
`sophon skills generate`	Generate a skill from a markdown doc (`--from-doc`, `--name`, `--output`)	`sophon skills generate --from-doc spec.md`
`sophon workflows list`	List workflows	`sophon workflows list`
`sophon workflows get <id>`	Show a workflow (with recent runs)	`sophon workflows get wf_1`
`sophon workflows create`	Create from a JSON file (`--file`)	`sophon workflows create --file flow.json`
`sophon workflows delete <id>`	Delete a workflow	`sophon workflows delete wf_1`
`sophon workflows execute <id>`	Run a workflow manually	`sophon workflows execute wf_1`
`sophon workflows history <id>`	View execution history	`sophon workflows history wf_1`
`sophon workflows versions <id>`	View version history	`sophon workflows versions wf_1`
`sophon workflows rollback <id> <version>`	Roll back to a version	`sophon workflows rollback wf_1 3`
`sophon workflows draw <id>`	Draw the workflow graph in the terminal (`--json`)	`sophon workflows draw wf_1`
`sophon workflows test-node <json>`	Dry-run a single node with a JSON payload	`sophon workflows test-node '{...}'`
`sophon workflows check-credentials <json>`	Verify required service credentials	`sophon workflows check-credentials '{...}'`
`sophon cron list`	List scheduled jobs	`sophon cron list`
`sophon cron add`	Add a job (`--name`, `--cron`, `--message`, `--agent`)	`sophon cron add --name daily --cron "0 7 * * *" --message "Brief me"`
`sophon cron delete <id>`	Delete a job	`sophon cron delete daily`
`sophon cron pause <id>` / `resume <id>`	Pause or resume a job	`sophon cron pause daily`
`sophon cron trigger <id>`	Trigger a job immediately	`sophon cron trigger daily`
`sophon cron history <id>`	Show a job's run history (`--limit`)	`sophon cron history daily`
`sophon discuss list`	List discussion definitions	`sophon discuss list`
`sophon discuss show <id>`	Show a discussion definition	`sophon discuss show disc_1`
`sophon discuss create`	Create from a JSON file (`--file`)	`sophon discuss create --file panel.json`
`sophon discuss delete <id>`	Delete a definition	`sophon discuss delete disc_1`
`sophon discuss run <definitionId>`	Run with a seed prompt (`--seed`, `--rounds`, `--detach`)	`sophon discuss run disc_1 --seed "Ship or wait?"`
`sophon discuss cancel <runId>`	Cancel a running discussion	`sophon discuss cancel run_9`
`sophon discuss runs`	List recent runs (`--definition`, `--limit`)	`sophon discuss runs --limit 5`
`sophon discuss show-run <runId>`	Show a run transcript and verdict	`sophon discuss show-run run_9`

Approvals & tasks

Command	Description	Example
`sophon approvals pending`	List pending approval requests	`sophon approvals pending`
`sophon approvals decide <id>`	Approve or reject (`--approve`, `--reject`)	`sophon approvals decide ap_1 --approve`
`sophon approvals edit <id>`	Open the preview in `$EDITOR`, then approve with edits (`--content`)	`sophon approvals edit ap_1`
`sophon approvals history`	View approval history	`sophon approvals history`
`sophon approvals watch`	Watch for new approval requests in real time	`sophon approvals watch`

Task and run commands are listed under Chat & sessions above.

Memory & documents

Command	Description	Example
`sophon memory list`	List memory entries (`--agent`, `--scope`)	`sophon memory list --scope shared`
`sophon memory add`	Add an entry (`--key`, `--content`, `--scope`, `--agent`)	`sophon memory add --key tz --content "UTC+1"`
`sophon memory forget <id>`	Delete a memory entry	`sophon memory forget mem_5`
`sophon memory search <query>`	Search memory	`sophon memory search "billing address"`
`sophon memory reindex`	Rebuild the memory graph (`--llm` for LLM extraction)	`sophon memory reindex --llm`
`sophon memory daily-logs`	Show recent daily logs (`--agent`, `--days`)	`sophon memory daily-logs --days 14`
`sophon docs list`	List uploaded documents	`sophon docs list`
`sophon docs upload <file>`	Upload and index a document	`sophon docs upload report.pdf`
`sophon docs summarize <id>`	Summarize a document	`sophon docs summarize doc_1`
`sophon docs ask <id> <question>`	Ask a question about a document	`sophon docs ask doc_1 "What is the deadline?"`
`sophon docs search <query>`	Search documents	`sophon docs search "auth flow"`
`sophon docs delete <id>`	Delete a document	`sophon docs delete doc_1`

Voice & nodes

sophon nodes … is the Gateway CLI, for managing paired machines from wherever you are. It is a different program from sophon-node …, the binary that runs on the machine itself and has five verbs of its own.

Command	Description	Example
`sophon voice status`	Show every configured speech provider with its health, plus separate rows for server hands-free and browser hands-free	`sophon voice status`
`sophon voice settings show`	Show your voice preferences and the listening (speech-to-text) settings together	`sophon voice settings show`
`sophon voice settings set`	Update personal voice preferences — `--language`, `--speed`, `--input-mode`, `--output-mode`, `--default-tts-provider`, `--fallback-native`, `--fallback-server-stt`, `--conversation-mode`, `--silence-timeout`, `--inactivity-limit`. Every field you don't pass is kept	`sophon voice settings set --speed 1.2 --language en-US`
`sophon voice settings listening`	Update your personal listening overrides — `--default-provider`, `--interim-results`, `--endpointing-ms`, `--max-utterance`. Add `--host-defaults` to write the host-wide defaults instead (Admin/Owner), which is also the only place `--language` applies	`sophon voice settings listening --endpointing-ms 500`
`sophon voice stt-providers list`	List configured speech-to-text providers	`sophon voice stt-providers list`
`sophon voice stt-providers add`	Add a speech-to-text provider (`--name`, `--type`, `--api-key`, `--endpoint`)	`sophon voice stt-providers add --name DG --type deepgram`
`sophon voice stt-providers remove <providerId>`	Remove a speech-to-text provider	`sophon voice stt-providers remove dg-1`
`sophon voice stt-providers test <providerId>`	Test a speech-to-text provider's health	`sophon voice stt-providers test dg-1`
`sophon voice providers list`	List configured text-to-speech providers	`sophon voice providers list`
`sophon voice providers voices <providerId>`	List voices for a provider (`--language`)	`sophon voice providers voices eleven-1`
`sophon voice providers add`	Add a text-to-speech provider (`--name`, `--type`, `--api-key`, `--endpoint`)	`sophon voice providers add --name El --type elevenlabs`
`sophon voice providers remove <providerId>`	Remove a text-to-speech provider	`sophon voice providers remove eleven-1`
`sophon voice providers test <providerId>`	Test a provider's health	`sophon voice providers test eleven-1`
`sophon voice transcribe <file>`	Transcribe an audio file to text	`sophon voice transcribe call.mp3`
`sophon voice runtime list`	List voice runtimes on nodes (Admin)	`sophon voice runtime list`
`sophon voice runtime start <nodeId>`	Start the voice runtime on a node (`--agent`, `--session`)	`sophon voice runtime start my-mac --agent default`
`sophon voice runtime stop/interrupt <nodeId>`	Stop or interrupt a node's voice runtime	`sophon voice runtime interrupt my-mac`
`sophon nodes list`	List paired desktop nodes	`sophon nodes list`
`sophon nodes pending`	List nodes awaiting pairing approval	`sophon nodes pending`
`sophon nodes pair`	Request pairing (`--name`)	`sophon nodes pair --name my-mac`
`sophon nodes approve <id>` / `revoke <id>`	Approve or revoke a node	`sophon nodes approve my-mac`
`sophon nodes permissions <id>`	Set permission scopes (`--scopes`)	`sophon nodes permissions my-mac --scopes system.execute screen.capture`
`sophon nodes rotate-token <id>`	Issue a fresh node token	`sophon nodes rotate-token my-mac`
`sophon nodes command <id> <type>`	Enqueue one command type (`--payload`)	`sophon nodes command my-mac screen.capture`
`sophon nodes wait <commandId>`	Long-poll for a command result	`sophon nodes wait cmd_5`

Notes on the voice commands:

Adding a provider is not the whole setup. voice providers add and voice stt-providers add register a provider at the default priority and don't set the voice it speaks with. Choose the voice, and the provider order, in Voice settings on the Dashboard.
settings set is additive. It reads your current preferences, applies only the flags you passed and writes the rest back unchanged, so setting the speed no longer clears your listening overrides. The conversation inactivity flag is --inactivity-limit.
voice runtime … is Admin-only on the Gateway, and the node must also hold the voice.runtime scope. runtime start sends --agent and --session in its request body; if the node's owner doesn't own the session you asked for, the Gateway starts a fresh one and the CLI says so.
There is no voice conversation inside the CLI. These commands configure and control voice; talking to Sophon happens on the Dashboard, Mobile or a paired node.

MCP & webhooks

Command	Description	Example
`sophon mcp list`	List configured MCP servers	`sophon mcp list`
`sophon mcp get <name>`	Show one server's details	`sophon mcp get github`
`sophon mcp add`	Register a server (`--name`, `--transport`, `--endpoint`, `--risk`, `--arg`)	`sophon mcp add --name fs --transport stdio --endpoint mcp-fs`
`sophon mcp remove <name>`	Remove a server	`sophon mcp remove fs`
`sophon mcp reconnect <name>`	Reconnect a server	`sophon mcp reconnect fs`
`sophon mcp tools <name>`	List tools exposed by a server	`sophon mcp tools fs`
`sophon mcp bundles`	List discoverable MCP bundles	`sophon mcp bundles`
`sophon mcp serve`	Run Sophon as an MCP server over stdio (`--name`, `--no-resources`)	`sophon mcp serve`
`sophon webhooks list`	List webhooks	`sophon webhooks list`
`sophon webhooks create`	Create a webhook (`--name`, `--url`, `--secret`)	`sophon webhooks create --name ci --url https://…`
`sophon webhooks get <id>`	Show a webhook	`sophon webhooks get wh_1`
`sophon webhooks update <id> <json>`	Update via a JSON body	`sophon webhooks update wh_1 '{"enabled":false}'`
`sophon webhooks delete <id>`	Delete a webhook	`sophon webhooks delete wh_1`
`sophon webhooks test <id>`	Send a test payload	`sophon webhooks test wh_1`
`sophon webhooks toggle <id>`	Enable or disable a webhook	`sophon webhooks toggle wh_1`
`sophon webhooks history <id>`	Show delivery history	`sophon webhooks history wh_1`
`sophon push register`	Register an Expo push token (`--token`, `--platform`, `--device-id`)	`sophon push register --token … --platform ios`
`sophon push unregister`	Remove this device	`sophon push unregister`
`sophon push status`	Show registration status	`sophon push status`
`sophon push preferences get/set`	Get or set notification preferences	`sophon push preferences get`
`sophon push test`	Send a test notification	`sophon push test`

Diagnostics & system

Command	Description	Example
`sophon status`	Show overall system status	`sophon status`
`sophon health`	Show detailed component health	`sophon health`
`sophon doctor`	Diagnose configuration — gateway, auth, providers, Docker, data dir, config (`--verbose` for detailed per-check output)	`sophon doctor --verbose`
`sophon home`	Show the home feed (sessions, tasks, insights, channel health)	`sophon home`
`sophon insights show`	Full insights payload	`sophon insights show`
`sophon insights metrics`	Raw metrics only	`sophon insights metrics`
`sophon canvas follow <sessionId>`	Subscribe to canvas frames for a session	`sophon canvas follow sess_1`
`sophon canvas list <sessionId>`	List persisted canvas frames	`sophon canvas list sess_1`
`sophon canvas action <sessionId> <frameId> <action>`	Submit a canvas action (`--context`)	`sophon canvas action sess_1 fr_1 submit`
`sophon claude-code sessions`	List ClaudeCode IDE sessions	`sophon claude-code sessions`
`sophon claude-code send <sessionId> <message>`	Send a message to a session	`sophon claude-code send cc_1 "run tests"`
`sophon claude-code end <sessionId>`	End a session	`sophon claude-code end cc_1`
`sophon claude-code stream`	Follow a ClaudeCode event stream	`sophon claude-code stream`
`sophon completions <shell>`	Generate completion scripts (bash, zsh, fish, powershell)	`sophon completions zsh`
`sophon upgrade`	Check for Sophon updates	`sophon upgrade`

Admin & accounts

Command	Description	Example
`sophon onboard`	First-run setup wizard (`--non-interactive`, `--skip-profile`)	`sophon onboard`
`sophon login` / `register` / `logout`	Sign in, create an account, or sign out	`sophon login`
`sophon whoami`	Show the current user	`sophon whoami`
`sophon profile show`	Show your personalization profile	`sophon profile show`
`sophon profile status`	Whether the personalization wizard is needed	`sophon profile status`
`sophon profile wizard`	Run the personalization wizard (`--from-file`, `--non-interactive`)	`sophon profile wizard`
`sophon profile set`	Set a single field (`--field name=value`)	`sophon profile set --field preferredName=Alex`
`sophon profile skip` / `reset`	Skip or reset the profile (`reset --yes`)	`sophon profile reset --yes`
`sophon config list / get / set / path / validate / reset`	Manage `~/.sophon/config/cli.json`	`sophon config set defaultAgent researcher`
`sophon license`	View license info (`license validate` to validate)	`sophon license`
`sophon admin users` / `roles`	List users or roles (Admin role)	`sophon admin users`
`sophon admin audit`	View the audit log (`--limit`, `--action`)	`sophon admin audit --limit 50`
`sophon tenant list`	List tenants (Enterprise)	`sophon tenant list`
`sophon tenant show <id>`	Show tenant details	`sophon tenant show acme`
`sophon tenant create`	Create a tenant (interactive)	`sophon tenant create`
`sophon tenant update <id>`	Update (`--name`, `--max-users`, `--description`)	`sophon tenant update acme --max-users 100`
`sophon tenant enable/disable <id>`	Enable or disable a tenant	`sophon tenant disable acme`
`sophon tenant delete <id> --confirm`	Soft-delete a tenant	`sophon tenant delete acme --confirm`
`sophon tenant add-member <id> --email --role`	Add a member	`sophon tenant add-member acme --email a@b.com --role Viewer`
`sophon tenant remove-member <id> <userId>`	Remove a member	`sophon tenant remove-member acme u_1`
`sophon tenant list-members <id>`	List tenant members	`sophon tenant list-members acme`

See Configuration & Auth for config, env overrides, and remote-gateway setup.

Advanced

Self-hosting, service management, backups, ops, and the local developer toolkit.

Command	Description	Example
`sophon start`	Start the Sophon Gateway (`--port`, `--open-browser`)	`sophon start --port 9000`
`sophon stop`	Signal the Gateway to shut down	`sophon stop`
`sophon service install / uninstall / status`	Manage Sophon as a system service (systemd, launchd, Windows Service)	`sophon service install`
`sophon backup`	Back up `~/.sophon` (`--output`)	`sophon backup`
`sophon restore <file>`	Restore `~/.sophon` from a backup	`sophon restore backup.zip`
`sophon snapshot`	Create a verified snapshot (`--description`)	`sophon snapshot --description "pre-upgrade"`
`sophon snapshot-restore <archive> <manifest>`	Restore from a snapshot	`sophon snapshot-restore snap.zip snap.json`
`sophon snapshot-list`	List available snapshots	`sophon snapshot-list`
`sophon ops status`	Full system diagnostics (admin/SRE)	`sophon ops status`
`sophon ops doctor`	Run server self-diagnostics	`sophon ops doctor`
`sophon ops logs`	Tail server logs (`--level`, `--tail`)	`sophon ops logs --tail 200 --level error`
`sophon ops config`	Inspect server runtime config	`sophon ops config`
`sophon ops action <action>`	Run a named ops action (reload-config, reload-runtime, restart-process)	`sophon ops action reload-config`
`sophon dev new <type> <name>`	Scaffold a skill, agent, plugin, or app	`sophon dev new skill my-skill`
`sophon dev validate [path]`	Validate a project's structure and manifest; `--json` prints one machine-readable document	`sophon dev validate --json`
`sophon dev build [path]`	Build a distributable package (`--output`, `--json`) — skills pack to `.sophon-skill`, agents to `.sophon-agent`, plugins to `.sophon-plugin`, apps to `.sophon-app`	`sophon dev build`
`sophon dev install [path]`	Install a project (skill or plugin) locally for testing	`sophon dev install`
`sophon dev test [path]`	Run a project's tests (`--integration`, `--gateway`)	`sophon dev test`

What validate and build do beyond printing:

Failures reach the shell. dev validate and dev build exit non-zero when validation fails, when the project type can't be detected, or when a build can't be produced — so a CI step or an editor integration can act on the result instead of scraping output. dev test propagates the test runner's own exit code.
--json answers in the shape you asked for, including on failure: stdout carries exactly one JSON document, with the messages that explain why. It exists for tools that drive the CLI rather than read it.
dev validate also warns about what the Marketplace would reject before you upload a skill: a name that doesn't match the required pattern or the folder it lives in, a missing author or license, an over-long description, an unknown runtime, a missing or unrecognised category, and too many or over-long tags. These are warnings, not errors — a package can be perfectly valid locally and still be refused on publish.
dev build leaves local clutter out of the package: .env files (including .env.*), virtualenv and build directories (.venv, node_modules, __pycache__, bin, obj, dist), and editor state (.vscode, .idea, .vs). A plain venv or env directory is not excluded — rename it if you keep one.

The plugin template scaffolded by sophon dev new still generates a project that does not build as-is — expect manual fixes before sophon dev build succeeds. The Python and C# skill scaffolds did not run either before 2.0; they are fixed and now run under the sandbox unchanged. The scaffolded agent's agent.json is not yet in the shape the Gateway's agent loader reads, so a scaffolded agent won't load until you adjust it.

sophon start, sophon stop, sophon service, the backup/snapshot family, and sophon dev are intended for self-hosted installs and local development. On the personal tier the Gateway is managed for you. See Configuration & Auth.

Command Reference

On this page