cade-cli 0.11.0

Cade - The CLI Agent from Arcade.dev

Cade

The CLI agent from Arcade.dev. Coding, research, and everyday automation — driven from a terminal, a single shell pipe, or a long-lived daemon that replies over Telegram.

brew install ArcadeAI/tap/cade   #  or:  uv tool install cade-cli   |   pip install cade-cli
cade login
cade

---

Highlights

• Three deployment modes from the same binary. Interactive chat (cade), one-shot or pipe (cade -m "…"), or a headless daemon that replies over messaging (cade serve).
• Tools from anywhere. Built-in local tools (filesystem / shell / git / search / tasks / channels / memory), Arcade Cloud tools (Slack, GitHub, Gmail, calendars, …), and any MCP server you register — all unified under one tool surface.
• Bidirectional MCP. Tools can call context.ui.elicit(…) for structured input, context.log.* for live operator logs, and context.progress.report(…) for editable progress UI — routed end-to-end through whichever adapter is active (Telegram inline keyboard, terminal prompt).
• Personas + per-persona memory. Multiple agent profiles with their own system prompt and an indexed memory store backed by agent-library.
• Extensibility surface. Hooks (lifecycle events), tasks (file-backed durable work), cron (scheduled prompts), channels (cross-session pub/sub) — all available to the agent as Local_* tools and to you as cade <subcommand>.
• Bring your own LLM. OpenAI, Anthropic, or any OpenAI-compatible endpoint (Ollama, vLLM, Together, Groq, Fireworks, …). --local-only skips Arcade Cloud entirely.

---

Install

Source	Command
Homebrew	brew install ArcadeAI/tap/cade
uv	uv tool install cade-cli
pip	pip install cade-cli
From source	git clone https://github.com/arcadeai-labs/cade.git && cd cade && uv sync

Prerequisites: Python 3.11+, an Arcade account (arcade.dev) for cloud tools, and an LLM provider key (OPENAI_API_KEY or ANTHROPIC_API_KEY). Skip the Arcade account with --local-only or CADE_LOCAL_ONLY=1.

cade login          # Arcade Cloud OAuth (skip with --local-only)
cade --version

---

Quick start

cade                                       # interactive chat
cade -m "What changed in HEAD?"            # single message, then exit
cat error.log | cade -m "What went wrong?" # pipe input
cade -r                                    # resume the most recent thread
cade resume "auth-rewrite"                 # resume a thread by name
cade --persona reviewer                    # use a saved persona's system prompt
cade --voice                               # speak / hear (voice mode)

Top-level options

Flag	Description
-r, --resume	Resume most recent thread
-m, --message	Single-message mode (reads stdin if no arg)
-P, --persona	Use a saved persona
-V, --voice	Voice mode
-v, --verbose	Debug logging
--version	Print version

In-chat slash commands

Command	Description
/help	List commands
/clear	Clear screen
/copy	Copy last response
/logs	Recent log entries
/thread, /history	Current thread info
/pin, /unpin	Pin reference material into the session
/tasks, /cron, /hooks, /channels, /notify	Coordination surfaces (mirrored as cade tasks / cade cron / cade hooks / cade channels)
/usage	Context-window status and token usage
/cd, /pwd, /!	Shell shortcuts
Ctrl+C	Exit

---

Tools

Tools come from three sources and are addressed uniformly by their registered name:

• Local_* — built-in: filesystem (ReadFile, WriteFile, Edit, ListFiles), shell (Bash — async with progress reporting), Search, Git, Task*, Channel, AskUserQuestion, RetrieveToolResult, ToolSchema, Sleep, PinContext, PushNotification.
• Memory_* — agent-library backed, per-persona indexed knowledge store.
• Arcade Cloud + user MCP servers — anything you register.

cade tools list                         # all tools, all sources
cade tools list --source local          # filter by source
cade tools search "send slack"          # keyword search
cade tools info Local_ReadFile          # full schema + description

The full local tool surface (including the bidirectional MCP capabilities and cade serve integration) is documented in docs/mcp.md.

Custom MCP servers

cade mcp add my-server http://localhost:8080
cade mcp add my-server http://… --auth bearer -t <token>
cade mcp authorize my-server                      # OAuth flow (browser)
cade mcp list / status / test / enable / disable / rm

User MCP servers register at ~/.cade/config/contexts/<context>.toml [[mcp]]. Servers with large catalogs are auto-deferred (parameter schemas stripped to keep tool-list bytes down) and fetched on demand via Local_ToolSchema.

---

Personas + memory

cade persona list / create / get / edit / delete / default   # manage system prompts
cade --persona reviewer                       # use one for a session

cade mem list                                 # sources indexed for the active persona
cade mem add ~/notes                          # index a directory
cade mem search "auth design"                 # semantic search

Memory is persona-scoped — each persona has its own ~/.cade/data/contexts/<context>/memory/<persona>/.librarian/ index, so a reviewer persona's notes never leak into default.

---

Headless daemon: cade serve

Run Cade as a long-lived daemon that replies over messaging platforms (Telegram supported today; the adapter protocol is generic). Each chat gets its own persistent thread — persona, memory, and tools carry across messages.

cade serve init                          # wizard: bot token, allowed senders
cade serve                               # foreground
cade serve --install launchd             # macOS LaunchAgent (or --install systemd)
cade serve status / stop                 # health, uptime; SIGTERM running daemon

Config lives at ~/.cade/config/contexts/<context>.toml [serve]. Edit and kill -HUP $(cat ~/.cade/run/serve.pid) to reload without restart.

Security defaults are fail-closed: allowed_senders = [] blocks everyone; tools are default-deny against [tools].allow (globs / regex / pipe lists supported); deny always wins.

The MCP transport is fully bidirectional, so tools running inside the daemon can elicit structured input (rendered as Telegram inline keyboards), stream live progress (rendered as edited placeholder messages), and emit logs that flow into the daemon log. See docs/mcp.md for the protocol details, docs/configuration.md for the full daemon config reference.

---

Extensibility: hooks, tasks, cron, channels

Four primitives the agent uses directly (as Local_* tools) and you can drive from the CLI:

Surface	What it is	CLI
Hooks	Lifecycle event handlers (pre/post tool, user prompt submit)	cade hooks list / add / remove / test
Tasks	File-backed durable work units that survive turn boundaries	cade tasks list / get / create / update / delete
Cron	Scheduled prompts the agent runs on a timer	cade cron list / add / remove / enable / disable / run-now
Channels	JSONL-backed inter-session pub/sub	cade channels list / send / recv / clear

See docs/channels.md for the channels protocol; hooks and tasks/cron details live in their respective cade <subcommand> --help outputs.

---

Bring your own LLM

Cade works with any OpenAI-compatible endpoint. Three ways to wire one in (CLI flag → env → config, first match wins):

# CLI flag
cade chat --endpoint http://localhost:11434/v1 --model llama3

# Environment
export OPENAI_BASE_URL="http://localhost:11434/v1"
export OPENAI_API_KEY="ollama"   # any non-empty value
cade chat --model llama3

# Config — ~/.cade/config/cade.toml
[model_settings]
host = "http://localhost:11434/v1"
api_key = "ollama"

Skip Arcade Cloud authentication entirely with --local-only or CADE_LOCAL_ONLY=1 when running against local LLMs.

---

Configuration

All state lives under ~/.cade/. Override the location with CADE_HOME=/path/to/alt.

File	Purpose
config/cade.toml	Model / provider / UI settings
data/contexts/<context>/history.db	Thread + message storage
logs/cade.log	Rotating log file
config/contexts/<context>.toml [[mcp]]	User MCP server registry
config/contexts/<context>.toml [serve]	cade serve daemon config
personas/, memory/, tasks/, channels/	Persona-scoped state

Full layout, env vars, and TOML schema in docs/configuration.md.

Common env vars

Variable	Purpose
OPENAI_API_KEY / ANTHROPIC_API_KEY	LLM provider keys
OPENAI_BASE_URL	Custom OpenAI-compatible endpoint
ARCADE_API_KEY, ARCADE_BASE_URL	Arcade Cloud (alternative to OAuth)
CADE_LOCAL_ONLY=1	Skip remote tools entirely
CADE_HOME	Override config directory
CADE_PROJECT_ROOT	Sandbox Local_* filesystem tools to this root

---

Contributing

git clone https://github.com/arcadeai-labs/cade.git
cd cade
uv sync --all-extras --dev
pytest                # full suite
ruff check src/ tests/ && ruff format src/ tests/

Style: Python 3.11+ with modern type hints (dict, list, | None); ruff for lint + format; pytest with asyncio_mode = "auto". Public functions and classes get docstrings.

PRs welcome — open an issue first for anything substantial.

---

Resources

• arcade.dev — product
• docs.arcade.dev — API and tool catalog
• docs/ — mcp.md (tool protocol), configuration.md, channels.md, install.md
• Issues · Releases

License

MIT