Configuration

You can customize Toporic in three ways, from easiest to most advanced:

Method	Best for	Changes persist?
TUI	Quick changes while working	Yes (saved automatically)
CLI flags	One-off overrides for a single session	No (session only)
Config files	Fine-tuning, permissions, advanced settings	Yes

Most settings can be changed from within the terminal UI without touching any files. CLI flags are great for temporary overrides. Config files give you full control when you need it.

Changing your AI provider

Toporic works with 20+ AI providers. Switch between them at any time.

From the TUI: Press Ctrl+, to open the config overlay, select Provider, pick from the list. If the provider needs an API key, you’ll be prompted to enter it.

From the CLI:

toporic --provider openai
toporic --provider ollama

In config: set defaults.provider in ~/.toporic/config.json.

Setting up API keys

Most cloud providers need an API key. There are three ways to provide one:

From the TUI: Press Ctrl+, → select a provider → enter the key when prompted. The key is saved securely in ~/.toporic/providers.json.

From the CLI:

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

Via environment variable:

export ANTHROPIC_API_KEY="sk-ant-..."
toporic

Environment variables take highest priority. No restart needed — Toporic picks up the key the next time it calls the provider.

Ollama runs locally and doesn’t need a key. Just make sure the Ollama service is running:

ollama serve &
toporic --provider ollama --model llama3.2

Choosing a model

From the TUI: Press Ctrl+, → select Model → pick from the provider’s available models. The list is fetched automatically for each provider.

From the CLI:

toporic --model gpt-4o-mini
toporic --provider ollama --model llama3.2

Changing the theme

Three TUI color themes are available: Amber (warm orange), Purple (cool violet), and Green (emerald).

From the TUI: Press Ctrl+, → select Theme → pick Amber, Purple, or Green. Changes take effect instantly.

From the CLI:

toporic --theme purple
toporic --theme green

Changing the display language

The TUI supports 9 languages: English, Simplified Chinese, Traditional Chinese, Japanese, Korean, Spanish, French, German, and Portuguese.

From the TUI: Press Ctrl+, → select Language → pick from the list.

In config: set defaults.language (e.g. "zh-CN", "ja", "de"). There is no CLI flag — language is TUI-only.

Switching agent mode

Choose between Coding (full tools), Assistant (conversation only), and Research (web search only).

From the TUI: Type /mode assistant or /mode research in the input box. Or press Ctrl+, → select Mode.

From the CLI:

toporic --mode coding      # default
toporic --mode assistant   # chat only, no tools
toporic --mode research    # web research, no file editing

Configuring permissions

Permissions control which actions the agent can take without asking you. Configure them in ~/.toporic/config.json:

{
  "permissions": {
    "auto_approve_reads": true,
    "safe_commands": [
      "cargo test",
      "npm test",
      "git status",
      "ls"
    ]
  }
}

What each permission does

auto_approve_reads — When true (default), the agent can freely read files and search your project without asking. When false, even reading a file requires approval. Most users keep this on.
safe_commands — A list of shell commands you trust. The agent auto-runs any command starting with one of these prefixes. For example, adding "npm test" means the agent can run npm test --watch without asking. Add your project’s build, test, and lint commands here to reduce interruption.
enable_llm_classifier — When true, Toporic uses a secondary AI check to decide if a command is safe before running it. More accurate than safe_commands alone, but adds a small delay and API cost per command. Keep false unless you hit limits with safe_commands.
allowed_outside_paths — The agent normally stays within your project folder. Add paths here if it needs to access files elsewhere (e.g. /tmp, ~/Downloads).

See Tools & Permissions for the full guide with examples.

Config file reference

Toporic stores settings in two files inside ~/.toporic/. Both are created automatically on first launch.

File	What it holds
`~/.toporic/config.json`	Defaults, permissions, context tuning, embedding, MCP
`~/.toporic/providers.json`	Provider definitions, API keys, available models

You can also place overrides in <your-project>/.toporic/ for project-specific settings. Your user-level settings always win if there’s a conflict.

config.json

{
  "defaults": {
    "mode": "coding",
    "provider": "deepseek",
    "model": "deepseek-v4-flash",
    "theme": "amber",
    "language": "English"
  },
  "permissions": {
    "auto_approve_reads": true,
    "enable_llm_classifier": false,
    "safe_commands": [],
    "allowed_outside_paths": []
  },
  "context": {
    "compact_fraction": 0.87,
    "warn_fraction": 0.90,
    "prune_keep_recent": 8
  },
  "embedding": {
    "enabled": false,
    "provider": "voyage"
  },
  "mcp": {
    "servers": []
  }
}

The context section controls how the agent manages long conversations (rarely needs tuning). The embedding section enables AI-powered codebase search (off by default). The mcp section connects external tools via MCP servers (advanced).

providers.json

Each provider entry stores its connection details, available models, and optionally an API key:

{
  "anthropic": {
    "display_name": "Anthropic",
    "api_pattern": "anthropic",
    "base_url": "https://api.anthropic.com",
    "default_model": "claude-opus-4-7",
    "models": ["claude-opus-4-7", "claude-sonnet-4-20250514"],
    "api_key": "sk-ant-..."
  }
}

Use toporic set-key to add keys safely. You rarely need to edit this file by hand.