Getting Started

Installation

Arctic is distributed as a standalone binary. Install it using the install script:

macOS / Linux

curl -fsSL https://usearctic.sh/install | bash

Windows

irm https://usearctic.sh/install.ps1 | iex

Or download directly from the releases page:

https://github.com/arctic-cli/interface/releases

System Requirements

• Linux (x64, ARM64), macOS (Intel, Apple Silicon), or Windows (x64)
• Git (recommended for snapshots)
• Terminal with 256 color support (Windows Terminal recommended on Windows)

First Run

Launch Arctic:

arctic

This opens the TUI (Terminal User Interface). Press Ctrl+X then Q to exit.

Claude Code Migration

If you're coming from Claude Code, Arctic will automatically detect and offer to import:

• Commands: From ~/.claude/commands or .claude/commands
• Agents: From ~/.claude/agents or .claude/agents
• MCP Servers: From ~/.claude.json or .mcp.json

You'll be prompted once for each category. Choose "Yes" to import or "No" to skip. Imported items are copied to Arctic's directories (.arctic/command/claude/, .arctic/agent/claude/, etc.).

Authentication (quick)

Start the auth flow:

arctic auth login

Choose your provider and follow the browser flow. For API‑key providers, set environment variables (e.g., OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY).

See Providers for full details.

Your First Prompt

Interactive (TUI)

arctic

Type your message in the input area and press Enter.

One‑Shot Mode

arctic run "summarize this repo"

Attach Files

arctic run -f src/index.ts "review this file"

Or pipe stdin:

git diff | arctic run "explain these changes"

Basic Workflow

1. Start Arctic: arctic
2. Type your prompt and press Enter
3. Review the response
4. Continue the conversation
5. Switch models with Ctrl+X M

Key Concepts

Sessions

Every conversation is a session. Sessions are saved and can be resumed:

arctic session list
arctic run --continue

Projects

Projects are auto‑detected (Git worktree). Sessions are isolated per project.

Models

Pick a model in the TUI (Ctrl+X M) or in CLI:

arctic run --model openai/gpt-4o "..."

Agents

Agents are custom prompts with tool rules:

arctic agent create

Storage Locations

Arctic stores data in standard locations:

• Config: ~/.config/arctic/arctic.json
• Auth: ~/.config/arctic/auth.json
• Sessions: ~/.local/share/arctic/storage/session/<projectID>/
• Messages/Parts: ~/.local/share/arctic/storage/message/<sessionID>/ and ~/.local/share/arctic/storage/part/<messageID>/
• Snapshots: ~/.local/share/arctic/snapshot/

Next Steps

Troubleshooting

Authentication Issues

arctic auth list
arctic auth logout
arctic auth login

Model Not Found

arctic models --refresh

Debug Mode

arctic debug config

Getting Help

• Docs: https://usearctic.sh/docs
• Issues: https://github.com/arctic-cli/interface/issues