Skip to main content

Getting Started

Installation

Toporic installs with a single command. Pick your platform:

# macOS or Linux
curl -fsSL https://toporic.com/code/tui/install.sh | sh

# Windows (PowerShell, in Windows Terminal)
irm https://toporic.com/code/tui/install.ps1 | iex

The install script downloads the latest version and places the toporic binary in your PATH. After installing, verify it worked:

toporic --version

Requirements

  • Windows users must use Windows Terminal or WSL. Command Prompt and PowerShell ISE don’t support the terminal UI.
  • The code search tool uses rg (ripgrep). If it’s not installed, run apt install ripgrep, brew install ripgrep, or choco install ripgrep — or skip it, the agent works without it.

Setting up an API key

Toporic needs an API key to talk to an AI provider. Pick one — most users start with DeepSeek (free credits available) or Anthropic.

Option A: Save it once (recommended)

toporic set-key --provider deepseek --key your-key-here
toporic set-key --provider anthropic --key sk-ant-...

The key is saved locally on your machine. You only need to do this once.

Option B: Set it per session

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

Environment variables take priority over saved keys. Useful for temporary keys or CI environments.

If you don’t have a key yet, you can still launch Toporic — the TUI opens with a welcome screen and guides you through setting one up.

Using local models (Ollama)

No API key needed. Make sure Ollama is running, then:

ollama pull llama3.2        # download a model (once)
toporic --provider ollama --model llama3.2

Your first interaction

Run toporic from your project folder:

cd ~/my-project
toporic

The terminal UI opens. You’ll see a welcome screen with tips. Type your message and press Enter.

❯ Add unit tests for the user login function

The agent reads your project, plans its approach, and starts working. You’ll see its thinking process, tool calls, and results appear in real time.

One-shot mode

If you prefer a single command without opening the TUI:

toporic --goal "Fix all clippy warnings in the project"

The agent runs autonomously and exits when done. This is ideal for CI/CD pipelines or quick tasks.

Switching between modes

Toporic has three agent modes. The default is Coding (full tool access):

toporic                          # coding — edit files, run commands, search web
toporic --mode assistant         # assistant — conversation only, no tools
toporic --mode research          # research — web search, no file editing

You can also switch modes from within the TUI by typing /mode assistant or /mode research.

Choosing a provider

Toporic works with many AI providers. Here are the most common ones:

ProviderSet up withNotes
DeepSeektoporic set-key --provider deepseek --key <key>Default. Great balance of speed and quality.
Anthropictoporic set-key --provider anthropic --key sk-ant-...Claude models. Strong coding performance.
OpenAItoporic set-key --provider openai --key sk-...GPT models.
Ollama(none)Local models. No key, no internet needed.

20+ providers are supported — see the Configuration page for the full list and how to switch between them.

Next steps

Next → TUI Reference