Arcana user guide

Overview

Arcana is a terminal AI agent (arcana) with an optional hosted console and proxy:

• CLI — TUI sessions, tools, skills, memory, local server.
• Console — arcana.otnelhq.com sign-in, workspace UI, billing.
• Proxy — proxy.arcana.otnelhq.com OpenAI-compatible HTTP API billed against your license.

You can use the CLI with your own provider keys only (BYOK), or pair with the console for a proxy license.

Install

The published package is arcana-ai. The binary name is always arcana.

# Quick start
npx arcana-ai

# Global install
npm install -g arcana-ai
# pnpm add -g arcana-ai
# bun add -g arcana-ai

# From source
git clone https://github.com/Lento47/arcana && cd arcana
bun install && bun link   # from packages/arcana/

arcana --version
# 0.3.5

Data lives under ~/.arcana/ (override with ARCANA_HOME): accounts, workspace trust, sessions, local DB.

Quick start

# 1) Provider key (BYOK)
export OPENAI_API_KEY=sk-...
# or ANTHROPIC_API_KEY / GEMINI_API_KEY / …

# 2) Optional: console + proxy license
arcana console login

# 3) Optional: trust this repo for project plugins/tools/MCP
arcana trust

# 4) Run
arcana doctor
arcana run "explain this codebase"
# or open the TUI: arcana

Console login

Device flow pairs this machine with your Arcana account. No password is typed into the CLI.

arcana console login
# default server https://arcana.otnelhq.com
arcana console login https://arcana.otnelhq.com

arcana console orgs
arcana console switch
arcana console logout [email]
arcana console open

1. CLI prints a seal code (e.g. 3D8C-CVQA) and opens the browser.
2. Sign in on the site (password, GitHub, or Google).
3. Page completes pairing; CLI stores the license bearer and account.
4. Close the browser when the terminal shows success.

Provider keys

BYOK keys stay local. Prefer environment variables for CI and shells.

export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export GEMINI_API_KEY=...

arcana providers          # interactive provider management
arcana models             # list available models
arcana license status     # machine / license activation (separate from console)
arcana license activate <key>

Console login does not replace provider keys: proxy models use the Arcana license; direct models use your vendor keys.

Workspace trust

By default, project plugins, custom tools, agents on disk, and local MCP from the repo are not loaded until you trust the workspace.

arcana trust              # trust current directory
arcana trust status
arcana trust list
arcana trust revoke

# Dev / CI only — loads project executable config without a trust record
export ARCANA_DISABLE_WORKSPACE_TRUST=1

Trust is stored in ~/.arcana/workspace-trust.json and is invalidated when executable project config changes.

CLI command map

Top-level commands registered by the engine (public user surface):

Run arcana --help or arcana <command> --help for flags on your installed version.

Core

arcana run

Start an interactive or one-shot agent session in the current project.

arcana run
arcana run "summarize the auth flow"
arcana run --model <provider/model>

arcana models

arcana models

arcana providers

arcana providers

Account & license

arcana console

arcana console login [url]
arcana console logout [email]
arcana console orgs
arcana console switch
arcana console open

arcana license

arcana license activate <key>
arcana license status
arcana license deactivate

arcana trust

arcana trust
arcana trust status [path]
arcana trust list
arcana trust revoke [path]
arcana trust grant [path]

Sessions & data

arcana session

arcana session list
arcana session delete <sessionID>

arcana memory

Local memory lives under ~/.arcana/data/. Cloud facts (visible on the workspace Memory page) sync via the proxy when you are logged in.

arcana memory facts
arcana memory search --query <q>
arcana memory stats
arcana memory push    # local facts → cloud
arcana memory pull    # cloud facts → local
arcana memory sync    # push then pull

export / import

arcana export
arcana import

arcana stats

arcana stats

arcana db

Local database utilities for the Arcana data store (inspect / path). Prefer higher-level session commands unless you are debugging.

arcana db --help

MCP, plugins, agents

arcana mcp

arcana mcp list
arcana mcp add [name]
arcana mcp auth [name]
arcana mcp logout [name]
arcana mcp debug <name>

Local MCP from a project directory requires workspace trust.

arcana plugin / plugin-store

arcana plugin --help
arcana plugin-store --help

arcana agent

arcana agent --help

Server & integrations

arcana serve

Headless control plane. Defaults to loopback. Non-loopback binds require ARCANA_SERVER_PASSWORD.

arcana serve
arcana serve --hostname 127.0.0.1 --port 4096

arcana attach

arcana attach --help

arcana web

arcana web
arcana web --build

github / pr

arcana github --help
arcana pr --help

upgrade / uninstall / audit

arcana upgrade
arcana uninstall
arcana audit --help

Proxy overview

Base URL: https://proxy-arcana.otnelhq.com

OpenAI-compatible surface for chat, embeddings, models, balance, and account-style helpers. Use after arcana console login (or another valid license bearer).

Authentication

Authorization: Bearer <license_key>

License keys look like ARCANA-PRO-… and come from console login. Do not send vendor API keys (sk-…) as the proxy bearer.

export ARCANA_LICENSE='ARCANA-PRO-…'
curl -H "Authorization: Bearer $ARCANA_LICENSE" \
  https://proxy-arcana.otnelhq.com/v1/balance

Chat & embeddings

POST /v1/chat/completions

curl -N -X POST https://proxy-arcana.otnelhq.com/v1/chat/completions \
  -H "Authorization: Bearer $ARCANA_LICENSE" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "messages": [{ "role": "user", "content": "hello" }],
    "stream": true
  }'

POST /v1/embeddings

Models

GET /v1/models

curl -H "Authorization: Bearer $ARCANA_LICENSE" \
  https://proxy-arcana.otnelhq.com/v1/models

Balance & usage

GET /v1/balance

{
  "userId": "[email protected]",
  "credits": 842,
  "dollars": "8.42"
}

credits are integer units (100 = $1.00).

GET /v1/usage

Daily request counters for the authenticated subject.

GET /v1/free-usage/sessions/current

Free-tier session snapshot (turns, weekly tokens) when on free plan.

Health, sessions, profile

GET /v1/health

{
  "status": "ok",
  "service": "arcana-proxy",
  "user": "[email protected]",
  "tier": "pro"
}

GET /v1/sessions

List recent proxy-recorded sessions (model, tokens, cost, optional message preview). Detail: GET /v1/sessions/:id. These are proxy usage records, not full local TUI transcripts.

GET / PUT /v1/memory

Personal cloud memory facts for the workspace Memory page and arcana memory push|pull|sync.

# List
curl -H "Authorization: Bearer $ARCANA_PROXY_KEY" \
  https://proxy-arcana.otnelhq.com/v1/memory

# Upsert facts (last-write-wins by updatedAt)
curl -X PUT -H "Authorization: Bearer $ARCANA_PROXY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"facts":[{"key":"user.theme","value":"dark","confidence":1}]}' \
  https://proxy-arcana.otnelhq.com/v1/memory

# Delete one fact
curl -X DELETE -H "Authorization: Bearer $ARCANA_PROXY_KEY" \
  https://proxy-arcana.otnelhq.com/v1/memory/user.theme

GET / PUT /v1/profile

User profile preferences used by the workspace UI.

GET /v1/purchases

Purchase history for the authenticated account.

How device pairing works

1. Code. CLI → POST /auth/device/code with { client_id: "arcana-cli" } → device_code, user_code, interval, expires_in.
2. Browser. Opens /auth/device?code=XXXX-XXXX for sign-in.
3. Poll. CLI → POST /auth/device/token until approved or expired.
4. Complete. Browser page finishes pairing with the site; site mints a license privately and stores it for this device session.
5. Token. Poll returns access_token (license). CLI loads /api/user and /api/orgs, then persists the account.

user_code format

• Shape: XXXX-XXXX (confusable-free alphabet, no 0/O/1/I/L).
• ~10 minute TTL; rate limits on issue and complete.

/^[A-HJ-NP-Z2-9]{4}-[A-HJ-NP-Z2-9]{4}$/

Device error codes

Public site surfaces