Command Line
Command ReferenceNEW
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 marketplace | Browse the marketplace (--search, --category) | sophon skills marketplace --search pdf |
sophon skills install <skillId> | Install a marketplace skill | sophon skills install pdf-tools |
sophon skills uninstall <skillId> | Uninstall a marketplace skill | 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
| Command | Description | Example |
|---|---|---|
sophon voice providers list | List configured TTS 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 TTS provider (--name, --type, --api-key) | sophon voice providers add --name El --type elevenlabs |
sophon voice providers remove <providerId> | Remove a TTS 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 | sophon voice runtime list |
sophon voice runtime start/stop/interrupt <nodeId> | Control the voice runtime on a node | sophon voice runtime start 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 shell screenshot |
sophon nodes rotate-token <id> | Issue a fresh node token | sophon nodes rotate-token my-mac |
sophon nodes command <id> <kind> | Enqueue a command — screenshot, shell, file (--payload) | sophon nodes command my-mac screenshot |
sophon nodes wait <commandId> | Long-poll for a command result | sophon nodes wait cmd_5 |
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 | sophon dev validate |
sophon dev build [path] | Build a distributable package (--output) | sophon dev build |
sophon dev install [path] | Install a project locally for testing | sophon dev install |
sophon dev test [path] | Run a project's tests (--integration, --gateway) | sophon dev test |
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.