ARCANA Documentation

Welcome to the official documentation for ARCANA — a self-improving AI agent CLI with skills, memory, gateway, coding, and cron in one terminal. This guide covers installation, configuration, core concepts, and advanced features.

Quick Start

Get up and running in under a minute:

# Quick start (shim downloads binary on first run)
npx arcana-ai@latest

# Or install globally
npm install -g arcana-ai
arcana

Package name is arcana-ai; the binary is always arcana.

# 1) Provider key (BYOK) — any supported vendor
export OPENAI_API_KEY=sk-...        # or ANTHROPIC_API_KEY, GEMINI_API_KEY, etc.

# 2) Optional: pair with Arcana console + proxy license
arcana console login                # https://arcana.otnelhq.com (device seal)

# 3) Optional: trust this repo if it has project plugins/tools/MCP
arcana trust

# 4) Run
arcana doctor
arcana run "explain this codebase"
# or just: arcana

What is Arcana?

Arcana is a terminal-native AI workbench that sits one layer above your model providers. You bring your own API keys. Arcana adds session management, memory, tooling, skills, scheduled automation, and multi-platform gateways on top.

• Multi-provider sessions — Route prompts to different models (GPT-4o, Claude, Gemini, DeepSeek, local Ollama, and 200+ more) from the same session.
• Persistent memory — Facts extracted during sessions are indexed with SQLite FTS5 and searchable across sessions. Optional cloud sync is available after console login.
• Scoped tool execution — Shell, filesystem, git, and MCP tools under explicit permission profiles.
• Skills — Reusable instruction sets (SKILL.md) that give the agent domain expertise. Load automatically or activate with /skills.
• Scheduled automation — Cron jobs that run agent prompts on a schedule from the same runtime.
• Chat gateways — Telegram, Discord, Slack, and WhatsApp adapters with per-chat sessions and allowlists.

Installation

Prerequisites

• Node.js / npm (or Bun for development)
• An API key from any supported provider (OpenAI, Anthropic, Gemini, OpenRouter, xAI, Bedrock, Ollama, etc.)
• A modern terminal with Unicode and truecolor support (iTerm2, Windows Terminal, Kitty, WezTerm, etc.)

Install

npx arcana-ai@latest
# or
npm install -g arcana-ai
arcana --help

First run

Set a provider key via environment variable, then run arcana doctor to confirm detection. Start a session with arcana or arcana run "your prompt". Type /help inside the TUI for slash commands.

Core Concepts

Sessions

An interactive conversation with one or more models. Sessions are recorded locally with full transcript, token usage, and cost tracking. Resume them with arcana history resume. Proxy sessions also appear in the console dashboard.

Providers

Arcana auto-detects providers from environment variables (OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, XAI_API_KEY, etc.). No per-vendor command is required. Use arcana models and arcana providers to inspect what is available. See Configuration for the full list.

Memory

Structured facts are extracted from conversations and indexed with FTS5. Query with arcana memory search . Full details in the Memory documentation.

Tools & MCP

Tools let the agent run shell commands, read/write files, use git, and call MCP servers. Permissions are interactive and profile-based. See MCP & Tools.

Skills

Skills are SKILL.md files that teach the agent domain-specific workflows. They live in skills/ (repo) and ~/.arcana/skills/ (user). List and search with arcana skills list. See Skills.

Configuration

Configuration lives in ~/.arcana/config.json (override root with ARCANA_HOME). Environment variables always take precedence for API keys.

# Typical flow
export OPENAI_API_KEY=sk-...
arcana doctor
arcana run "hello"

Full reference: Configuration.

Next Steps

Explore the documentation by topic: