CLI Reference

The aibutler binary is more than a chat REPL. It’s the full management surface for the runtime: vault, configuration, costs, agents, schedules, backups, plugins, MCP, voice, RBAC, and GDPR operations all live behind subcommands. This page is the live, exhaustive reference — every command, what it does, and an example of its actual output.

Quick Start

aibutler              # Start AI Butler (channels + scheduler)
aibutler help         # Show all commands
aibutler version      # Print version

Commands

version

Print the running version. Useful for bug reports.

$ aibutler version
aibutler v0.1.0

setup and config show

setup shows the current configuration along with the path to your config file (typically ~/.aibutler/config.yaml). config show is the same idea but groups output by the Three-Tier Configuration layers (Settings / Configurations / Options).

To change anything, edit the config file directly:

$EDITOR ~/.aibutler/config.yaml

start (also: bare aibutler)

Start AI Butler with all enabled channels, the scheduler, and the agent loop. Bind address and port come from configurations.web — defaults to localhost:3377.

$ aibutler start
AI Butler v0.1.0 starting...
AI provider connected: Claude (claude-sonnet-4-6)
Scheduler started.
Channel started: webchat
LAN discovery started.

WebChat: http://localhost:3377
Dashboard: http://localhost:3377/api/dashboard/stats

Ready. Press Ctrl+C to stop.

repl

Interactive terminal chat with streaming responses. See Terminal for the slash-command surface and multi-line input details.

resume [ID]

Resume a previous session. With no ID, opens an interactive picker; with an ID, jumps straight back into that session’s history.

vault and auth

vault is for storing credentials in your OS keyring (Keychain, GNOME Keyring, Windows Credential Manager). auth is the read-side companion (list, status, revoke).

aibutler vault set <key> <value>     # Store
aibutler vault get <key>             # Read (echoes the value)
aibutler vault list                  # List stored keys (no values)
aibutler vault delete <key>          # Remove

aibutler auth list                   # Same as vault list
aibutler auth status                 # Health check on the keyring
aibutler auth revoke <key>           # Same as vault delete

Common keys to set up first:

aibutler vault set anthropic_api_key sk-ant-...
aibutler vault set openai_api_key sk-...
aibutler vault set telegram_bot_token <bot_token>
aibutler vault set slack_bot_token xoxb-...

cost

Per-model spend tracking with a monthly budget envelope.

aibutler cost status                  # Current month + remaining + alert level
aibutler cost history                 # Spend trail
aibutler cost breakdown               # Per-model breakdown table
aibutler cost strategy                # Show current strategy
aibutler cost strategy <frugal|balanced|quality>
aibutler cost budget                  # Show current monthly budget
aibutler cost budget <amount-usd>

The Alert field in cost status follows budget thresholds — info at 50%, warn at 75%, critical at 90%, over past 100%. Local Ollama models always cost $0 because no remote API is being charged.

mode [name]

Show or switch the agent mode for the current installation.

aibutler mode                # Show current mode
aibutler mode auto           # Switch to auto (default; behaves as single in v0.1)
aibutler mode single         # Force single-agent mode

Multi-agent / swarm / custom modes downgrade to single in v0.1 with a clear log message — they’re behind the swarm orchestrator which is beta.

agent

Inspect agent runs (each user turn spawns one primary agent, optionally with subagents).

aibutler agent list                       # Currently running + recent
aibutler agent status <id>                # Full state for one agent
aibutler agent history                    # Completed runs with cost + duration

skill

Skills are model-agnostic prompt+capability bundles loaded into the context when their trigger keywords match. Edit on disk in ~/.aibutler/skills/, or use the CLI:

aibutler skill list
aibutler skill enable <name>
aibutler skill disable <name>

mcp

Two halves: serve AI Butler’s tools to other MCP clients, or list what tools you currently expose.

aibutler mcp tools                # List exposed MCP tools (with descriptions)
aibutler mcp serve                # Run MCP server over stdio (for Claude Desktop, etc.)

To add an external MCP server (e.g. clarifyprompt-mcp, GitHub MCP, filesystem MCP), edit configurations.mcp.servers in your config — see Integrate an MCP Server.

plugin

Manage WASM plugins. The runtime is the Extism sandbox; plugins must declare every capability they need.

aibutler plugin install <path-or-url>
aibutler plugin list
aibutler plugin enable <name>
aibutler plugin disable <name>
aibutler plugin info <name>
aibutler plugin remove <name>

memory

Direct access to the memory store.

aibutler memory import <file>     # Bulk-import memories from JSON/markdown
aibutler memory digest             # Generate a digest summary now
aibutler memory digests            # List existing digests

voice

Pipeline status and provider listings. Configuration lives in the config file — this command is read-only.

aibutler voice status              # STT + TTS provider + voice response mode
aibutler voice providers           # List available STT and TTS providers
aibutler voice tui                 # Voice TUI mode (experimental, requires arecord/sox)

backup

Local backup management. Backups land at ~/.aibutler/backups/aibutler-YYYYMMDD-HHMMSS.db.

aibutler backup now                  # Create a fresh snapshot
aibutler backup list                 # All snapshots with size + timestamp
aibutler backup verify               # SQLite integrity check on each snapshot
aibutler backup export <path>        # Copy current DB to <path>
aibutler backup import <path>        # Verify a candidate file (you replace the live DB manually)

integrity

End-to-end health check: SQLite PRAGMA integrity_check plus a vault ping. Run after migrations or before publishing a backup.

$ aibutler integrity
Database integrity... OK
Vault health...      OK

user

RBAC user management (multi-user installs only).

aibutler user create <name> --role <admin|user|viewer|agent>
aibutler user list
aibutler user assign <name> --role <role>

Single-user installs don’t need this — the default user is admin and there’s no auth gate on localhost.

gdpr

Right-to-erasure operations.

aibutler gdpr delete-user <name>     # Remove all data for a user
aibutler gdpr export <name> <path>   # Export everything for a user as JSON
aibutler gdpr purge --before <date>  # Bulk-delete data older than date

The delete-user operation cascades through every table that references the user (sessions, memories, agent runs, schedules, etc.) inside a single transaction.

cleanup

Remove expired sessions (> 7 days idle by default). Ages can be overridden with --older-than <duration> (e.g. 30d, 90d).

aibutler cleanup                       # Default: > 7 days
aibutler cleanup --older-than 30d

---

Where commands store data

All commands operate on ~/.aibutler/:

~/.aibutler/
├── config.yaml           # Three-tier config — edited by hand
├── aibutler.db           # SQLite — sessions, memories, agents, schedules, costs
├── aibutler.db-wal       # Write-ahead log
├── aibutler.db-shm       # Shared memory
├── backups/              # Snapshots from `backup now`
├── plugins/              # Installed WASM plugins
└── traces/               # MCP and agent traces (when enabled)

The vault lives in your OS keyring outside this directory — it’s never written to disk in plaintext.

Programmatic alternatives to CLI scripting

The CLI is interactive-friendly. For automation, use:

• A2A protocol — REST + SSE for cross-agent delegation
• MCP server mode — aibutler mcp serve exposes AI Butler as an MCP server for any compatible client
• Dashboard JSON endpoints at http://localhost:3377/api/dashboard/* — read-only, no auth on localhost