CLI

Scripted access to every major Sophon feature — agents, tasks, memory, workflows, cron, webhooks, skills, voice, and more.

sophon is the command-line interface. It's the primary way to automate Sophon from a terminal, a CI pipeline, or a scheduled script. Everything the Dashboard can do, the CLI can do — usually with less ceremony.

Installation

The CLI ships with the Gateway install. If you installed via Docker, get a local copy:

# macOS / Linux
curl -L https://releases.sophon.dev/cli/sophon-linux-x64 -o /usr/local/bin/sophon
chmod +x /usr/local/bin/sophon

# Windows (PowerShell)
iwr https://releases.sophon.dev/cli/sophon-win-x64.exe -OutFile $env:LOCALAPPDATA\Sophon\sophon.exe

Or use dotnet tool:

dotnet tool install -g Sophon.CLI

Configuration

sophon login
# → prompts for Gateway URL and credentials, stores at ~/.sophon/cli-config.json

Subsequent commands use that config automatically. Change Gateway: sophon config set gateway https://...

Top-level commands

sophon <group> <command> [options]

Groups:

Group	What it covers
`agents`	Create, list, delete, edit agents; edit SOUL.md
`chat`	Send messages from the terminal
`tasks`	Active tasks, history, cancel
`sessions`	Session list, describe, fork, delete
`memory`	Search, list, write, forget, traverse
`workflows`	List, create, edit, trigger, pause, history, import/export
`cron`	List, add, delete, pause, resume, trigger, history
`webhooks`	List, create, test, deliveries, retry
`skills`	Install, uninstall, list, describe, author
`documents`	Upload, list, summarize, delete
`connections`	Add, list, test, remove, rotate credentials
`channels`	List, configure, test
`voice`	Configure TTS, list voices, test
`node`	List, exec, describe, remove Sophon Nodes
`mcp`	MCP client + server management
`canvas`	List, show, export canvas artifacts
`claude-code`	Claude Code sessions — new, list, stream, exec, delete
`discussion`	Start, list, describe, cancel discussions
`insights`	Metrics, summary, cards, query
`approvals`	List, approve, reject
`admin`	Users, roles, audit (Admin role)
`tenant`	Tenants (Enterprise)
`backup`	Export / import data
`config`	Local CLI config
`version`	CLI version

Each group responds to sophon <group> --help for command lists.

Common usage

Chat from the terminal

sophon chat send "What's on my calendar today?"
sophon chat session new --agent ada
sophon chat session list
sophon chat describe <session-id>

Memory

sophon memory search "project deadline"
sophon memory list --scope user --limit 20
sophon memory write "User prefers dark mode" --scope user --category preference
sophon memory traverse "Atlas launch" --depth 2
sophon memory forget mem_abc123

Workflows

sophon workflows list
sophon workflows describe <id>
sophon workflows trigger <id>
sophon workflows pause <id>
sophon workflows resume <id>
sophon workflows history <id> --limit 10
sophon workflows export <id> > backup.json
sophon workflows import < backup.json
sophon workflows clone <id> --name "my-fork"

Cron

sophon cron list
sophon cron add --name morning-briefing \
  --schedule "0 9 * * MON-FRI" \
  --action agent --agent sophon --message "summarize my day"
sophon cron trigger morning-briefing
sophon cron pause morning-briefing
sophon cron history morning-briefing

Skills

sophon skills list
sophon skills install notion
sophon skills uninstall notion
sophon skills describe notion
sophon skills author "a skill that converts Markdown to PDF"

Documents

sophon documents upload report.pdf
sophon documents upload *.pdf --tag q3-review
sophon documents list
sophon documents summarize report.pdf
sophon documents delete <id>

Connections

sophon connect list
sophon connect add gmail
sophon connect add github
sophon connect test gmail
sophon connect status
sophon connect remove gmail
sophon connect rotate-credential gmail

Tasks

sophon tasks active
sophon tasks recent --limit 20
sophon tasks watch            # tails TaskStarted/Completed/Failed events live
sophon tasks cancel <id>
sophon tasks describe <id>

Voice

sophon voice list-voices --provider elevenlabs
sophon voice speak "Hello, world." --provider openai --voice nova
sophon voice config --provider google --voice en-US-Neural2-F

Sophon Node

sophon node list
sophon node describe <id>
sophon node exec <id> screen.capture --quality 80
sophon node exec <id> input.mouse.click --x 100 --y 200
sophon node remove <id>

MCP

sophon mcp servers
sophon mcp add <name> --stdio --cmd "npx -y @mcp/github"
sophon mcp add <name> --sse --url https://example.com/mcp
sophon mcp test <name>
sophon mcp tools <name>
sophon mcp serve --stdio     # run Sophon's own MCP server via stdio
sophon mcp tokens list
sophon mcp tokens create --label cursor

Canvas

sophon canvas list --session <id>
sophon canvas show <canvas-id>
sophon canvas export <canvas-id> --out ./artifact/

Claude Code

sophon claude-code new --name refactor-api --base node
sophon claude-code list
sophon claude-code stream <session-id>
sophon claude-code exec <session-id> "npm test"
sophon claude-code export <session-id> --out ./archive/
sophon claude-code delete <session-id>

Discussions

sophon discussion list
sophon discussion start --topic "Microservices now?" \
  --panelists ada,nora,cto-agent \
  --judge chairman --rounds 2
sophon discussion describe <run-id>
sophon discussion cancel <run-id>
sophon discussion verdict <run-id>

Insights

sophon insights metrics                 # current week
sophon insights metrics --window month
sophon insights summary                 # AI narrative
sophon insights cards
sophon insights query --category tokens --window day

Approvals

sophon approvals list
sophon approvals approve <id>
sophon approvals reject <id>
sophon approvals list --mine         # only mine
sophon approvals watch               # tail approval events

Admin (Admin role only)

sophon admin users list
sophon admin users create --email a@b.c --role Operator
sophon admin users delete <user-id>
sophon admin roles list
sophon admin roles create --name custom --permissions ManageSkills,ApproveActions
sophon admin audit --user <id> --since 2026-04-01

Tenants (Enterprise)

sophon tenant list
sophon tenant create --name acme
sophon tenant users <tenant-id>
sophon tenant assign --tenant <id> --user <id>

Backup

sophon backup create --out backup.zip
sophon backup restore --in backup.zip
sophon backup list                    # previous backups

Output formats

Most commands support --format:

table — human-readable columns (default)
json — structured JSON, pipe to jq
yaml — structured YAML
csv — spreadsheet-friendly

sophon tasks recent --limit 5 --format json | jq '.[] | .duration'

Scripting patterns

Watch for a specific event:

sophon tasks watch | jq 'select(.event == "task.failed")'

Trigger a workflow and poll until complete:

run_id=$(sophon workflows trigger my-workflow --format json | jq -r .runId)
while [ "$(sophon workflows run-status $run_id --format json | jq -r .status)" = "running" ]; do
  sleep 2
done

Export all workflows for backup:

for id in $(sophon workflows list --format json | jq -r '.[].id'); do
  sophon workflows export $id > "backup-$id.json"
done

Authentication

The CLI stores a bearer token at ~/.sophon/cli-config.json. Tokens expire after 30 days by default.

For CI, use a long-lived API token instead of sophon login:

export SOPHON_GATEWAY=https://gw.example.com
export SOPHON_API_TOKEN=sk_ci_...
sophon workflows trigger deploy-prod

Generate API tokens in Dashboard → Settings → Security → API tokens.

Shell completion

sophon completion bash > /etc/bash_completion.d/sophon
sophon completion zsh > "${fpath[1]}/_sophon"
sophon completion fish > ~/.config/fish/completions/sophon.fish

Where to go next

REST API — underlying HTTP endpoints the CLI uses
Dashboard — same features in a GUI
Workflows — CLI + cron + workflows is a very powerful combo

On this page