CLI Reference¶

SuperQode provides a CLI for your portable coding agent harness: coding sessions, runtime management, provider setup, agents, and configuration. This reference documents the available commands, options, and usage patterns.

Command Structure¶

superqode [OPTIONS] COMMAND [ARGS]...

Global Options¶

Option	CLI	Description
`--version`	superqode	Show version and exit
`--help`	superqode	Show help message and exit
`--tui`	superqode	Force the Textual TUI (default)
`-p`, `--print`	superqode	Run one headless coding task and print the response
`--mode json`	superqode	Run one headless task and emit structured JSON
`--profile`	superqode	Select harness profile: `build`, `plan`, or `review`
`--provider`	superqode	Override provider for headless mode
`--model`	superqode	Override model for headless mode
`--changes`	superqode	Control post-run change output: `summary`, `files`, `diff`, or `none`

Headless SuperQode¶

Use superqode directly for one-shot coding harness tasks:

superqode doctor
superqode -p "summarize this repository"
superqode -p --changes files "make the small docs fix"
superqode -p --changes none "answer without a change footer"
superqode --mode json --profile plan "plan the auth refactor"
superqode -p --resume abc123 "continue from the last turn"
superqode -p --fork abc123 "try a safer implementation"

Profiles:

Profile	Purpose
`build`	Full-access implementation work
`plan`	Read-only planning; shell requires approval and is denied in headless mode
`review`	Read-only code review

Inspect the tools and permissions for a profile:

superqode profiles list
superqode tools list --profile build
superqode tools list --profile plan --json

repo_search is available in coding profiles for broad codebase exploration. It combines ranked file matches, literal content matches, and symbol matches into one compact tool result.

Headless runs keep output clean by default. SuperQode prints the model response and then a compact change footer like Changes: 2 files (+18 -3) when the agent modified the workspace. Use --changes files to show the file list, --changes diff to show the patch, or --changes none to hide the footer.

Session commands:

superqode sessions list
superqode sessions tree
superqode sessions show abc123
superqode sessions export abc123 --format markdown --output session.md

Portable session handoff:

superqode share create abc123
superqode share export abc123 --format markdown --output session.md
superqode share import .superqode/shares/share-abc123.superqode-share.json --session-id imported
superqode share list --json
superqode share revoke share-abc123.superqode-share.json

Project trust:

superqode trust status
superqode trust status --json
superqode trust doctor
superqode trust yes
superqode trust no

Plugin manifests and local plugin packages:

superqode plugins list
superqode plugins list --all --json
superqode plugins show my-plugin
superqode plugins validate .superqode/plugins/my-plugin/plugin.json
superqode plugins doctor
superqode trust yes
superqode plugins add ./my-plugin
superqode plugins disable my-plugin
superqode plugins enable my-plugin

Agent memory:

superqode memory status
superqode memory providers
superqode memory doctor
superqode memory remember "Use pnpm in this repo; do not use npm" --kind preference --tag tooling
superqode memory search "package manager"
superqode memory search "auth requirements" --provider specmem
superqode memory search "release checklist" --provider mem0
superqode memory search "release checklist" --provider cognee
superqode memory search "release checklist" --provider supermemory
superqode memory forget <id>
superqode memory export --provider local --output memory.json

local is the default provider. specmem, mem0, cognee, and supermemory are opt-in providers configured under memory.providers in superqode.yaml.

Provider and model guidance:

superqode providers doctor openai --json
superqode providers guide openai
superqode providers guide ds4
superqode providers recommend coding
superqode providers recommend local
superqode providers recommend large-context --json
superqode providers scan-free --live --source openrouter
superqode -p --provider ds4 --model deepseek-v4-flash "summarize this repo"

For DS4, start ds4-server separately and point SuperQode at its OpenAI-compatible endpoint with DS4_HOST if it is not running on http://127.0.0.1:8000/v1.

In the TUI, use Ctrl+K for the command palette or type :status, :harness, :providers, :providers free --live openrouter, :recommend coding, :sandbox, :tree, :share, :trust, :plugins, and :benchmark. Use Ctrl+1 to open the persistent Harness sidebar tab.

Benchmark harness:

superqode benchmark run tasks.json --target superqode --target opencode --target pi --target deepagents

Build and understand a harness (no hand-written YAML):

superqode harness wizard                              # interactive builder
superqode harness explain --spec harness.yaml         # plain-English summary
superqode harness list-templates                      # model-family starters

Harness event graph:

superqode harness doctor --spec harness.yaml
superqode harness events <run-id>
superqode harness graph <run-id>
superqode harness graph <run-id> --json

Sandbox capability profiles:

superqode -p --sandbox read-only "review this repository"
superqode -p --sandbox no-shell "make a small docs edit"
superqode -p --sandbox git-worktree "try an isolated implementation"
superqode -p --sandbox docker "run tests in a container-isolated profile"
superqode -p --sandbox e2b "validate this patch in a remote sandbox profile"
superqode -p --sandbox daytona "prototype this change remotely"
superqode -p --sandbox modal "run a cloud sandbox validation"
superqode -p --sandbox vercel "run in a Vercel Sandbox profile"
superqode -p --sandbox runloop "validate in a Runloop devbox profile"
superqode -p --sandbox agentcore "validate in an AgentCore Code Interpreter profile"
superqode -p --sandbox langsmith "validate in a LangSmith sandbox profile"

Sandbox execution providers:

superqode sandbox doctor
superqode sandbox doctor e2b --json
superqode sandbox run docker --image python:3.12 -- pytest -q
superqode sandbox run e2b -- "pytest -q"

docker uses the local Docker CLI. e2b, daytona, modal, runloop, agentcore, and langsmith use optional Python SDKs when installed and authenticated. vercel uses the Vercel Sandbox CLI and token/OIDC authentication.

Command Groups¶

Config Commands (superqode config)

Configuration management commands for viewing, validating, and modifying settings.

Config Commands
Provider Commands (superqode providers)

Commands for managing BYOK providers, testing connections, and listing available models.

Provider Commands
Agents Commands (superqode agents)

Commands for listing, showing, and managing ACP coding agents.

Agents Commands
Auth Commands (superqode auth)

Show authentication and security information for providers and agents.

Auth Commands
Init Commands

Initialize SuperQode configuration for a project.

Init Commands
Connect Commands (superqode connect)

Connect to ACP agents, BYOK providers, local models, or self-contained runtimes.

Connect Commands
Model Commands (superqode models)

Browse 5000+ models from 130+ providers; search, download, and convert models.

Model Commands
Plugin Commands (superqode plugins)

Install, enable, disable, and validate plugin manifests.

Plugin Commands
Memory Commands (superqode memory)

Store and search agent memory across local and hosted providers.

Memory Commands
Session Commands (superqode sessions)

List, inspect, export, and delete stored sessions.

Session Commands
Share Commands (superqode share)

Create, import, and manage portable session artifacts.

Share Commands
Trust Commands (superqode trust)

Manage per-project trust for plugins and MCP operations.

Trust Commands
Sandbox Commands (superqode sandbox)

Inspect sandbox providers and run commands in isolation.

Sandbox Commands
Runtime Commands (superqode runtime)

List runtime backends and probe dependency readiness.

Runtime Commands

Quick Command Reference¶

Session And Memory Commands¶

Command	Description
`superqode sessions list`	List saved sessions
`superqode sessions tree`	Show session branches and forks
`superqode share create <session-id>`	Create a portable local session artifact
`superqode memory status`	Show memory provider status
`superqode memory remember "..."`	Store an explicit project fact or preference

Config Commands¶

Command	Description
`superqode config init`	Create `superqode.yaml` in the current directory (recommended)
`superqode config init --force`	Initialize config (overwrite if present)
`superqode harness wizard`	Build a harness spec interactively (no hand-written YAML)
`superqode harness init qwen-coding`	Create a harness spec from a model-family template
`superqode harness explain --spec <file>`	Explain in plain English what a harness lets the model do
`superqode harness validate --spec <file>`	Validate a harness spec

The full harness command group (wizard, init, explain, compile, diff, run, runs, events, replay, inbox, worker, and more) is documented in Harness Commands.

The full local command group (init, doctor, search, serve, servers, stop, models, warm, smoke, bench, labs, packs, optimize, guardrails) is documented in Local Commands.

Provider Commands¶

Command	Description
`superqode providers list`	List available providers
`superqode providers show PROVIDER`	Show provider details
`superqode providers test PROVIDER`	Test provider connection
`superqode providers mlx ACTION`	Manage MLX models

Harness Commands¶

Command	Description
`superqode harness list-templates`	List built-in harness templates
`superqode harness list-backends`	List harness runtime backends
`superqode harness import-omnigent <agent.yaml>`	Convert an Omnigent agent spec to a SuperQode harness
`superqode harness inspect --spec <file>`	Show resolved harness policy
`superqode harness compile --spec <file>`	Compile effective harness settings
`superqode harness diff old.yaml new.yaml`	Compare two harness specs
`superqode harness runs`	List persisted harness runs
`superqode harness events <run-id>`	Show normalized run events
`superqode harness graph <run-id>`	Show event graph
`superqode harness evidence <run-id>`	Show run evidence receipt
`superqode harness replay <run-id>`	Replay or inspect a prior run
`superqode harness fork <run-id>`	Fork persisted run context

TUI Commands¶

When running the interactive TUI (superqode), prefix commands with ::

TUI Command	Description
`:connect` or `:c`	Interactive connection picker (recommended)
`:connect acp opencode`	Connect directly to ACP agent
`:connect byok <provider> <model>`	Connect directly to BYOK provider
`:connect local <provider> <model>`	Connect directly to local model
`:plan <task>`	Ask for a plan only without native tool execution
`:plan approve`	Execute the last planned request with tools enabled
`:plan edit [task]`	Edit the pending planned request before execution
`:plan reject`	Clear the pending planned request
`:disconnect`	Disconnect current session
`:status`	Show session status
`:help`	Show help
`:quit`	Exit SuperQode

Exit Codes¶

Code	Meaning
`0`	Success
`1`	Error or findings detected
`130`	Interrupted (Ctrl+C)

Environment Variables¶

Variable	Description
`ANTHROPIC_API_KEY`	Anthropic API key
`OPENAI_API_KEY`	OpenAI API key
`GOOGLE_API_KEY`	Google AI API key
`DEEPSEEK_API_KEY`	Deepseek API key
`GROQ_API_KEY`	Groq API key
`OPENROUTER_API_KEY`	OpenRouter API key

Detailed Command Reference¶

For detailed documentation of each command group:

Config Commands - Configuration management
Provider Commands - Provider management
Agents Commands - ACP agent management
Auth Commands - Authentication and security
Init Commands - Project initialization
Connect Commands - Connection profiles and direct connect
Model Commands - Model catalog browsing and management
Plugin Commands - Plugin lifecycle management
Memory Commands - Agent memory operations
Session Commands - Session listing and inspection
Share Commands - Portable session artifact management
Trust Commands - Project trust management
Sandbox Commands - Sandbox provider diagnostics
Runtime Commands - Runtime backend inspection