CLI Reference - oxicrab

Commands

onboard
gateway
agent
cron
auth
channels
status
doctor
pairing
credentials
stats
completion

onboard

oxicrab onboard

Initialize oxicrab configuration and workspace. Creates ~/.oxicrab/config.toml with defaults, sets up the workspace directory, and generates template files (USER.md, AGENTS.md, TOOLS.md).

If a config file already exists, prompts for confirmation before overwriting.

gateway

oxicrab gateway [--model <MODEL>] [--echo]

Start the long-running oxicrab runtime. It loads configuration, initializes the LLM provider, starts all enabled channels, the agent loop, cron service, and optional HTTP endpoints, then runs until interrupted.

Flag	Description
--model	Override the default LLM model for this session (use `provider/model` prefix notation to specify a provider, e.g. `groq/llama-3.1-70b`)
--echo	Echo mode: test channel connectivity without an LLM. Echoes received messages back to the sender without agent processing.

oxicrab gateway
oxicrab gateway --model gpt-4o
oxicrab gateway --model anthropic/my-fine-tune
# Test channels without LLM
oxicrab gateway --echo

agent

oxicrab agent [-m <MESSAGE>] [-s <SESSION>]

Interact with the agent directly from the terminal. Without -m, starts an interactive REPL. With -m, sends a single message and prints the response.

Flag	Description
-m, --message	Send a single message (non-interactive)
-s, --session	Session key (default: `cli:default`)

# Interactive REPL
oxicrab agent

# Single message
oxicrab agent -m "What's the weather in London?"

# Named session for persistent context
oxicrab agent -s "project-x" -m "Summarize yesterday's work"

cron

oxicrab cron <SUBCOMMAND>

Manage scheduled jobs. Jobs can run in agent mode (full LLM turn with tools) or echo mode (deliver message directly). Supports cron expressions, intervals, and one-shot timers.

cron list

oxicrab cron list [-a]

Flag	Description
-a, --all	Include disabled jobs

cron add

oxicrab cron add -n <NAME> -m <MESSAGE> <SCHEDULE> <TARGET>

Flag	Description
-n, --name	Job name (required)
-m, --message	Message to process or deliver (required)
-e, --every	Run every N seconds (interval schedule)
-c, --cron	Cron expression (e.g. `"0 9 * * *"`)
--at	One-shot ISO 8601 datetime
--tz	Timezone for cron expressions (auto-detected if omitted)
--agent-echo	Deliver agent response to targets after processing
--channel	Target channel (use with `--to`)
--to	Target chat ID (use with `--channel`)
--all-channels	Target all enabled channels with allowFrom configured

# Every hour
oxicrab cron add -n "Hourly check" -m "Check my inbox" -e 3600 --channel telegram --to 123456

# Cron expression with timezone
oxicrab cron add -n "Morning briefing" -m "Morning briefing" -c "0 9 * * *" --tz "America/New_York" --all-channels

# One-shot at a specific time
oxicrab cron add -n "Reminder" -m "Meeting in 5 minutes" --at "2026-03-01T14:55:00Z" --channel discord --to 123456

cron remove

oxicrab cron remove --id <ID>

cron enable

oxicrab cron enable --id <ID> [--disable]

Flag	Description
--id	Job ID (required)
--disable	Disable instead of enable

cron edit

oxicrab cron edit --id <ID> [OPTIONS]

Modify an existing job. Any flag not provided is left unchanged.

Flag	Description
--id	Job ID (required)
-n, --name	New name
-m, --message	New message
-e, --every	New interval (seconds)
-c, --cron	New cron expression
--at	New one-shot ISO 8601 datetime
--tz	New timezone
--agent-echo	New agent echo setting
--channel / --to / --all-channels	New targets

cron run

oxicrab cron run --id <ID> [-f]

Flag	Description
--id	Job ID (required)
-f, --force	Run even if the job is disabled

auth

oxicrab auth <SUBCOMMAND>

Manage authentication for external services.

auth google

oxicrab auth google [-p <PORT>] [--headless]

Start the Google OAuth2 flow for Gmail, Calendar, and Tasks access. Opens a browser for authentication (or uses manual mode if --headless). Tokens are saved to the workspace database.

Requires tools.google.clientId and tools.google.clientSecret in config.

Flag	Description
-p, --port	Local redirect port (default: 8099)
--headless	Use manual code entry instead of browser redirect

channels

oxicrab channels <SUBCOMMAND>

Manage channel connections.

channels status

oxicrab channels status

Show the status of all channels: enabled/disabled, token configuration, and WhatsApp session state.

channels login

oxicrab channels login

Link a WhatsApp device via QR code. Displays a QR code in the terminal to scan with your phone. Session is saved to ~/.oxicrab/whatsapp/whatsapp.db.

Requires the channel-whatsapp feature to be compiled.

status

oxicrab status

Show a quick overview of your oxicrab setup: config path, workspace, active model, configured API keys, voice transcription status, and Google authentication state.

doctor

oxicrab doctor

Run comprehensive system diagnostics. Checks each component and reports PASS, FAIL, or SKIP with details.

Checks performed

Category	Checks
Core	Config file exists, parses as valid TOML, passes validation, workspace directory exists and is writable
Provider	API keys configured for any provider, provider connectivity (warmup test with latency measurement)
Channels	Each channel (Telegram, Discord, Slack, WhatsApp, Twilio): compiled, enabled, tokens/credentials configured
Voice	Transcription backend availability (local model, cloud API, or both)
External Tools	ffmpeg and git available in PATH (with version info)
Security	Config file/dir permissions, process sandbox availability (Landlock/Seatbelt), keyring, credential helper, sender allowlists, pairing store
MCP	MCP servers configured and enabled

# Example output
$ oxicrab doctor
oxicrab doctor

============================================================

  Core
  --------------------------------------------------------
  PASS   Config file                    /home/user/.oxicrab/config.toml
  PASS   Config parses                  valid TOML
  PASS   Config validates               all checks passed
  PASS   Workspace                      /home/user/.oxicrab/workspace (writable)

  Provider
  --------------------------------------------------------
  PASS   API keys                       anthropic, openrouter
  PASS   Provider connectivity          claude-sonnet-4-5 (warmup: 342ms)

  Channels
  --------------------------------------------------------
  PASS   telegram                       enabled, token configured
  PASS   discord                        enabled, token configured
  SKIP   slack                          disabled
  SKIP   whatsapp                       disabled
  SKIP   twilio                         disabled

  Voice
  --------------------------------------------------------
  PASS   Transcription                  local + cloud fallback

  External Tools
  --------------------------------------------------------
  PASS   ffmpeg                         ffmpeg version 6.1.1
  PASS   git                            git version 2.43.0

  MCP
  --------------------------------------------------------
  PASS   MCP servers                    2 server(s): filesystem, git

============================================================
  14 passed, 0 failed, 3 skipped

  All checks passed!

pairing

oxicrab pairing <SUBCOMMAND>

Manage sender pairing for DM access control. Channels with empty allowFrom arrays deny all senders by default. The pairing system lets new senders request access via an 8-character code that you approve from the CLI.

pairing list

oxicrab pairing list

Show pending pairing requests (with code, channel, sender ID, and time remaining) and count of already-paired senders. Codes expire after 15 minutes; max 3 pending per channel.

pairing approve

oxicrab pairing approve <CODE>

Approve a pending request by its 8-character code. The sender is permanently added to the pairing_allowlist table in the workspace database.

Argument	Description
CODE	The 8-character pairing code (e.g. `ABC12345`)

pairing revoke

oxicrab pairing revoke <CHANNEL> <SENDER_ID>

Remove a previously approved sender from the pairing allowlist.

Argument	Description
CHANNEL	Channel name: telegram, discord, slack, whatsapp, or twilio
SENDER_ID	The sender ID to revoke (same format as allowFrom entries)

Workflow

# 1. Configure a channel with empty allowFrom (deny-all)
[channels.telegram]
allowFrom = []

# 2. Start oxicrab
oxicrab gateway

# 3. Send a message from the account you want to authorize
# 4. In another terminal, check pending requests
oxicrab pairing list

# 5. Approve the request
oxicrab pairing approve ABC12345

credentials

oxicrab credentials <SUBCOMMAND>

Manage credentials stored in the OS keyring. Credential resolution order: env vars → credential helper → OS keyring → config.toml. Requires the keyring-store feature (default-on). Containers should use OXICRAB_* env vars instead. See Config → Credentials for env var tables, credential helper setup, and the full resolution order.

credentials set

oxicrab credentials set <NAME> [VALUE]

Store a credential in the OS keychain (macOS Keychain, GNOME Keyring, Windows Credential Manager). If VALUE is omitted, reads from stdin.

Argument	Description
NAME	Credential slot name (e.g. `anthropic-api-key`)
VALUE	Value to store (optional; prompted if omitted)

credentials get

oxicrab credentials get <NAME>

Check if a credential is stored. Shows [set] or [empty] — never prints the actual secret.

credentials delete

oxicrab credentials delete <NAME>

Remove a credential from the OS keyring.

credentials list

oxicrab credentials list

Show all 29 credential slots with their source: env, keyring, config, config/helper, or [empty].

credentials import

oxicrab credentials import

Bulk-import all non-empty credentials from config.toml into the OS keyring. Does not modify the config file — you can remove secrets from it afterward.

# Store a credential (prompts for value)
oxicrab credentials set anthropic-api-key

# Check what's configured
oxicrab credentials list

# Migrate secrets from config.toml to keyring
oxicrab credentials import

# Remove a credential
oxicrab credentials delete anthropic-api-key

stats

oxicrab stats <SUBCOMMAND>

Query memory search and LLM token usage statistics from the local SQLite database. Token usage is recorded per-call with model, input/output counts, and cache breakdown.

stats tokens

oxicrab stats tokens [--days N]

Show token usage summary grouped by date and model.

Flag	Default	Description
`--days, -d`	7	Number of days to look back

stats search

oxicrab stats search

Show memory search statistics: total searches, hit counts, average results per search, and top source files by hit count.

stats complexity

oxicrab stats complexity [--days N]

Show complexity routing statistics: per-band message distribution with percentages, average scores, correlated token totals (via request_id JOIN with llm_cost_log), force override counts, and the 5 most recent heavy routing examples. Requires a chat entry in modelRouting.tasks with complexity escalation.

Flag	Default	Description
`--days, -d`	7	Number of days to look back

# Last 30 days of token usage by model
oxicrab stats tokens -d 30

# Memory search effectiveness
oxicrab stats search

# Complexity routing: tier distribution, cost correlation, force overrides
oxicrab stats complexity -d 7

completion

oxicrab completion <SHELL>

Generate shell completion scripts. Outputs the completion script to stdout. Supported shells: bash, zsh, fish, elvish, powershell.

# Bash (add to ~/.bashrc)
eval "$(oxicrab completion bash)"

# Zsh (add to ~/.zshrc)
eval "$(oxicrab completion zsh)"

# Fish
oxicrab completion fish | source

# Or save to a file
oxicrab completion zsh > ~/.zfunc/_oxicrab