Troubleshooting

”toporic: command not found”

The binary isn’t in your PATH. On macOS and Linux, move it to /usr/local/bin/:

sudo cp toporic /usr/local/bin/

Or add your download folder to PATH:

export PATH="$PATH:/path/to/download-folder"

On Windows, use Windows Terminal and add the folder containing toporic.exe to your system PATH.

Nothing happens when I type

The TUI uses keyboard shortcuts that may conflict with your terminal. Check these first:

Enter to submit (not Return in some terminals)
Shift+Enter or Alt+Enter to insert a newline
If your terminal doesn’t send Shift+Enter, use Alt+Enter instead
Ctrl+C to quit

If the screen looks garbled or keys don’t respond, make sure you’re using a modern terminal: Windows Terminal, iTerm2, Kitty, Alacritty, or the built-in terminal on macOS/Linux.

Terminal too small

Toporic needs at least 20 columns wide by 6 rows tall. If you see a “Terminal too small” message, resize your terminal window — the TUI redraws automatically.

API key issues

“No API key found”

Toporic looks for API keys in this order:

Provider-specific environment variable (e.g. ANTHROPIC_API_KEY)
The generic AGENT_API_KEY environment variable
Keys saved via toporic set-key

The quickest fix:

toporic set-key --provider deepseek --key your-key-here

Or set it as an environment variable:

export DEEPSEEK_API_KEY="your-key-here"
toporic

“Invalid API key”

Double-check you copied the full key. Provider keys often start with a prefix like sk-ant- (Anthropic), sk- (OpenAI), or sk- (DeepSeek). If you’re sure the key is correct, verify the key is still active in your provider’s dashboard.

“Provider not ready”

The TUI opens with a welcome screen even without a valid key. From there, press Ctrl+, to open settings and configure a provider and key. Or use toporic set-key from the terminal.

Agent stops responding

If the agent seems stuck:

Check your internet connection — most providers need network access
Press Ctrl+C to cancel the current request and try again
The agent may be waiting for a tool to complete — look for a spinner in the title bar

Rate limits from your provider clear automatically. Toporic retries up to 3 times with increasing wait times. If it keeps failing, wait a minute and try again.

My messages aren’t saved

By default, Toporic saves every session. If you used --no-persist, sessions run in memory and are discarded when you quit. Remove --no-persist to save your conversations.

To resume a saved session:

toporic --resume

From the TUI, type /session list to browse past sessions and pick one to resume.

Ollama not working

If you’re using a local model via Ollama:

Make sure the Ollama service is running in another terminal: ollama serve
Pull the model first: ollama pull llama3.2
Start Toporic with: toporic --provider ollama --model llama3.2

If Ollama is running on a different machine or port, configure the base URL in ~/.toporic/providers.json.

Context limit warning

When the conversation gets very long, you’ll see a message like:

⚠ Context at 91% — consider starting a new session

This means the conversation is approaching the model’s memory limit. You have two options:

Let the agent handle it — it automatically summarizes older messages when needed
Start fresh with Ctrl+N or /session --new — your old session is still saved

How to quit

Ctrl+C quits immediately (while not streaming)
If the agent is streaming, first Ctrl+C cancels the stream, second Ctrl+C quits
Closing the terminal window also works — sessions are saved automatically

Enabling debug logs

If you need to investigate an issue, enable detailed logs:

RUST_LOG=debug toporic

From within the TUI, press Ctrl+L to open the diagnostics panel — it shows real-time log output. Logs are also written to ~/.toporic/logs/toporic.log on disk.