CLI Reference

Basic commands

# Start interactive TUI session (coding mode with DeepSeek default)
toporic

# One-shot autonomous execution (non-interactive, exits when done)
toporic --goal "Add unit tests for the auth module"

# Plan a goal without executing anything
toporic --goal "Refactor the router" --plan

# Execute a goal with per-change confirmation prompts
toporic --goal "Migrate to async/await" --build

# Get JSON output (for scripts / CI)
toporic --goal "Fix clippy warnings" --json

# Choose a provider and model
toporic --provider openai --model gpt-4o-mini
toporic --provider ollama --model llama3.2

# Choose an agent mode
toporic --mode assistant     # conversational, no tools
toporic --mode research      # web research, no file editing

# Resume the most recent session
toporic --resume

# Resume a specific session by ID
toporic --resume 550e8400-e29b-41d4-a716-446655440000

# Run without persisting session to disk
toporic --no-persist

Goal-based execution (one-shot mode)

When you pass --goal (shorthand -g), Toporic runs autonomously and exits after completion — no TUI is started. The agent automatically decomposes the goal into tasks and executes them.

toporic --goal "Add integration tests for the payment endpoint"

Combine with mode flags to control confirmation behavior:

Flag	Behavior
(default)	Auto mode — skip all confirmation prompts, run fully autonomously
--auto	Same as default (skip prompts)
--build	Prompt before each mutating tool (run_command, write_file, etc.)
--plan	Show the execution plan and exit without running any tools
--json	Output structured JSON to stdout for programmatic consumption

# Plan-only: see what the agent would do
toporic --goal "Set up CI pipeline" --plan

# Build mode: review each change before it is made
toporic --goal "Refactor error handling" --build

# CI-friendly JSON output
toporic --goal "Run all tests" --auto --json

All CLI flags

Flag	Short	Type	Default	Description
--version	-V	Flag	—	Show version and check for updates
--mode	-m	coding / assistant / research	config → coding	Agent preset mode
--provider	-p	Provider name	config → deepseek	LLM backend
--model		String	Provider’s default	Model override
--theme		amber / purple / green	config → amber	TUI color theme
--no-persist		Flag	false	Run without writing session to disk
--resume		Optional UUID	latest if bare	Resume session. Bare --resume = latest
--goal	-g	String	—	One-shot autonomous execution goal
--auto		Flag	false (but is default for --goal)	Skip permission prompts
--build		Flag	false	Prompt before each change
--plan		Flag	false	Show plan without executing
--json		Flag	false	Output structured JSON

Subcommands

set-key

Save an API key to ~/.toporic/providers.json:

toporic set-key --provider anthropic --key sk-ant-...
toporic set-key --provider openai --key sk-...

Ollama is silently ignored (no key needed). If the provider does not exist in the file, a stub entry is created.

init

Scaffold a Toporic workspace in the current directory:

toporic init
toporic init --workspace /path/to/project

Creates .toporic/ directory, AGENTS.md stub, and runs git init if needed. All operations are idempotent.

serve

Start an HTTP server with SSE streaming API:

toporic serve
toporic serve --addr 127.0.0.1:3000 --workspace /path/to/project

Exposes POST /v1/chat with streaming responses. Pre-builds a RAG index on startup.

update-models

Fetch the latest model pricing and context window data:

toporic update-models

Downloads from toporic.com and stores in ~/.toporic/models/models.json. This file overrides built-in model tables when present.

Provider list

Toporic supports 21 providers out of the box. Use the lowercase ID with --provider:

ID	Provider	Env var	API protocol
anthropic	Anthropic	ANTHROPIC_API_KEY	Native SDK
openai	OpenAI	OPENAI_API_KEY	OpenAI-compat
deepseek	DeepSeek	DEEPSEEK_API_KEY	OpenAI-compat
openrouter	OpenRouter	OPENROUTER_API_KEY	OpenAI-compat
google	Google	GOOGLE_API_KEY	Gemini native
ollama	Ollama (local)	(none)	Native SDK
groq	Groq	GROQ_API_KEY	OpenAI-compat
together	Together AI	TOGETHER_API_KEY	OpenAI-compat
perplexity	Perplexity	PERPLEXITY_API_KEY	OpenAI-compat
mistral	Mistral	MISTRAL_API_KEY	OpenAI-compat
cerebras	Cerebras	CEREBRAS_API_KEY	OpenAI-compat
fireworks	Fireworks	FIREWORKS_API_KEY	OpenAI-compat
alibaba	Alibaba	DASHSCOPE_API_KEY	OpenAI-compat
cohere	Cohere	COHERE_API_KEY	OpenAI-compat
nvidia	Nvidia	NVIDIA_API_KEY	OpenAI-compat
xai	xAI	XAI_API_KEY	OpenAI-compat
zhipuai	Zhipu AI	ZHIPU_API_KEY	OpenAI-compat
minimax	MiniMax	MINIMAX_API_KEY	OpenAI-compat
kimi	Kimi (Moonshot)	KIMI_API_KEY	OpenAI-compat
tencent-coding-plan	Tencent Coding Plan	TENCENT_CODING_PLAN_API_KEY	OpenAI-compat
tencent-tokenhub	Tencent TokenHub	TENCENT_TOKENHUB_API_KEY	OpenAI-compat

Custom providers can also be defined in ~/.toporic/providers.json.

Config integration

CLI flags override the config file for the current session. The resolution order is:

Setting	CLI flag	Config key	Hard default
Provider	--provider	defaults.provider	deepseek
Mode	--mode	defaults.mode	coding
Model	--model	defaults.model	Provider’s default
Theme	--theme	defaults.theme	amber
Language	(TUI only)	defaults.language	English

API key resolution (highest priority first):

1. Provider-specific environment variable (ANTHROPIC_API_KEY, etc.)
2. AGENT_API_KEY environment variable
3. api_key field in ~/.toporic/providers.json