Metadata-Version: 2.4
Name: cade-cli
Version: 0.15.4
Summary: Cade - The CLI Agent from Arcade.dev
Project-URL: Homepage, https://arcade.dev
Project-URL: Documentation, https://docs.arcade.dev
Project-URL: Repository, https://github.com/arcadeai-labs/cade
Project-URL: Issues, https://github.com/arcadeai-labs/cade/issues
Project-URL: Changelog, https://github.com/arcadeai-labs/cade/releases
Author-email: "Arcade AI Inc." <dev@arcade.dev>
License: MIT License
        
        Copyright (c) 2024 Arcade AI Inc.
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agent,ai,arcade,cli,coding-assistant,llm,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Code Generators
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: agent-library<1.0.0,>=0.14.0
Requires-Dist: anthropic<1.0.0,>=0.34.0
Requires-Dist: arcade-core<5.0.0,>=4.7.0
Requires-Dist: arcade-mcp-server<2.0.0,>=1.22.0
Requires-Dist: arcade-tdk<4.0.0,>=3.8.0
Requires-Dist: arcadepy<2.0.0,>=1.10.0
Requires-Dist: authlib<2.0.0,>=1.6.0
Requires-Dist: croniter<4.0.0,>=2.0.0
Requires-Dist: filelock<4.0.0,>=3.0.0
Requires-Dist: html2text>=2024.2.26
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: keyring<26.0,>=24.0
Requires-Dist: openai<2.0.0,>=1.0.0
Requires-Dist: prompt-toolkit<4.0.0,>=3.0.52
Requires-Dist: pydantic[email]<3.0.0,>=2.0.0
Requires-Dist: python-telegram-bot<22.0,>=21.0
Requires-Dist: rich<14.0.0,>=13.0.0
Requires-Dist: toml<1.0.0,>=0.10.0
Requires-Dist: typer>0.10.0
Requires-Dist: ulid==1.1
Requires-Dist: websockets<16.0,>=14.0
Provides-Extra: build
Requires-Dist: pyinstaller<7.0.0,>=6.16.0; extra == 'build'
Provides-Extra: dev
Requires-Dist: mypy<2.0.0,>=1.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio<1.0.0,>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov<5.0.0,>=4.0.0; extra == 'dev'
Requires-Dist: pytest-mock<4.0.0,>=3.11.0; extra == 'dev'
Requires-Dist: pytest<9.0.0,>=8.0.0; extra == 'dev'
Requires-Dist: ruff<1.0.0,>=0.5.0; extra == 'dev'
Provides-Extra: training
Requires-Dist: accelerate>=0.27.0; extra == 'training'
Requires-Dist: safetensors>=0.4.2; extra == 'training'
Requires-Dist: torch>=2.1.0; extra == 'training'
Requires-Dist: transformers>=4.38.0; extra == 'training'
Provides-Extra: voice
Requires-Dist: mlx-audio<0.4.0,>=0.2.0; extra == 'voice'
Requires-Dist: mlx-whisper>=0.1.0; extra == 'voice'
Requires-Dist: numpy>=1.24.0; extra == 'voice'
Requires-Dist: sounddevice<1.0.0,>=0.5.5; extra == 'voice'
Requires-Dist: webrtcvad>=2.0.10; extra == 'voice'
Description-Content-Type: text/markdown

# Cade

The CLI agent from [Arcade.dev](https://arcade.dev). Coding, research, and everyday automation — driven from a terminal, a single shell pipe, or a long-lived daemon that replies over Telegram.

```bash
curl -fsSL https://arcadeagent.dev/install | sh   #  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 / memory), [Arcade Cloud](https://arcade.dev) tools (Slack, GitHub, Gmail, calendars, …), and any [MCP](https://modelcontextprotocol.io/) 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).
- **Agents + per-agent memory.** Multiple agents, each with their own model, system prompt, tools, and an indexed memory store backed by [agent-library](https://pypi.org/project/agent-library/).
- **Extensibility surface.** Hooks (lifecycle events), tasks (durable work), cron (scheduled prompts) — 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 |
|---|---|
| **Install script** (recommended) | `curl -fsSL https://arcadeagent.dev/install \| sh` |
| 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` |

The install script detects your OS/arch, downloads the matching prebuilt binary
(macOS arm64, Linux x64), verifies its checksum, and drops `cade` in
`~/.local/bin` — no GitHub token required. Pin a version or install location:

```bash
CADE_VERSION=0.15.4 CADE_INSTALL_DIR=/usr/local/bin \
  sh -c "$(curl -fsSL https://arcadeagent.dev/install)"
```

On Linux the installer auto-picks a **cpu** or **gpu** build (GPU when
`nvidia-smi` detects a card; the GPU build bundles the CUDA stack and is a much
larger download). Force it with `CADE_VARIANT=cpu` or `CADE_VARIANT=gpu`.

(Windows: grab the `.zip` from the releases page, or `pip install cade-cli`.)

**Prerequisites:** Python 3.11+, an Arcade account ([arcade.dev](https://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`.

The first run walks you through picking a model provider and key (stored in your
OS keyring); re-run it any time with `cade init`.

```bash
cade init           # pick provider + model (runs automatically on first launch)
cade login          # Arcade Cloud OAuth (skip with --local-only)
cade --version
```

Full install and first-run docs: [`docs/install.md`](./docs/install.md) and
[`docs/quickstart.md`](./docs/quickstart.md).

---

## Quick start

```bash
cade                                       # interactive chat
cade -m "What changed in HEAD?"            # single message, then exit
cade -m "What went wrong?" < error.log     # prompt + file/stdin
cade resume                                # resume the most recent thread
cade resume "auth-rewrite"                 # resume a thread by name
cade use reviewer                          # switch the current agent
cade --voice                               # speak / hear (requires cade-cli[voice])
```

### Top-level options

| Flag | Description |
|---|---|
| `-m`, `--message` | Single-message mode; piped stdin is appended to the prompt |
| `--voice` | Voice mode; install `cade-cli[voice]` first |
| `-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`, `/notify` | Coordination surfaces (mirrored as `cade tasks` / `cade cron` / `cade hooks`) |
| `/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`), `Search`, `Git`, `Task*`, `AskUserQuestion`, `RetrieveToolResult`, `ToolSchema`, `PinContext`, `PushNotification`, `WebFetch`, and `WebSearch`.
- **`Memory_*`** — agent-library backed, per-agent indexed knowledge store.
- **Arcade Cloud + user MCP servers** — anything you register.

```bash
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`](./docs/mcp.md).

### Custom MCP servers

```bash
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 on the agent's `~/.cade/config/agents/<name>.toml [[mcp]]` list (with `cade.toml [agent_defaults].mcp` as the shared default). Servers with large catalogs are auto-deferred (parameter schemas stripped to keep tool-list bytes down) and fetched on demand via `Local_ToolSchema`.

---

## Agents + memory

Each **agent** bundles a model, system prompt, tools, and memory. The current
agent is ambient — most commands act on it.

```bash
cade new reviewer --prompt "You are a meticulous code reviewer."  # create + switch
cade list                                     # all agents
cade use reviewer                             # switch the current agent
cade info / cade edit reviewer                # inspect / change config

cade mem                                      # the current agent's memory (status)
cade mem add ~/notes                          # index a directory
cade mem search "auth design"                 # semantic search
cade mem warm                                 # pre-load the semantic memory model
```

Memory is per-agent — each agent has its own
`~/.cade/data/agents/<id>/memory/.librarian/` index, so a `reviewer` agent's
notes never leak into another. Cade advertises `Memory_*` tools without starting
the memory server; the first actual memory call starts it and keeps it warm for
later calls. Use `cade mem warm` when you want to pay that semantic-search
warmup before a conversation.

---

## Headless daemon: `cade serve`

Run Cade as a long-lived daemon that replies through adapters. Telegram is supported for personal bot workflows, and Desktop exposes a local WebSocket for native clients. Each conversation gets its own persistent thread — model, memory, and tools carry across messages.

```bash
cade serve init                          # wizard: bot token, allowed senders
cade serve                               # foreground (current agent)
cade serve --agent ops                   # serve a specific agent (one daemon per agent)
cade serve list                          # agents with a running daemon
cade serve --install launchd             # macOS LaunchAgent (or --install systemd)
cade serve status / stop                 # health, uptime; SIGTERM running daemon
```

Each agent's serve config lives in `~/.cade/config/agents/<name>.toml [serve]`. Edit and `kill -HUP $(cat ~/.cade/run/agents/<name>/serve.pid)` to reload without restart.

**Security defaults are fail-closed:** `allowed_senders = []` blocks everyone; tools are default-deny against `[serve.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, stream live progress, and emit logs through whichever adapter is active. See [`docs/adapters/`](./docs/adapters/) for adapter details, [`docs/mcp.md`](./docs/mcp.md) for protocol details, and [`docs/configuration.md`](./docs/configuration.md) for the full daemon config reference.

---

## Extensibility: hooks, tasks, cron

Three 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** | 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` |

Cross-agent messaging is set up with `cade link` / `cade channel` (an agent can only
reach another it's been linked to). 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):

```bash
# CLI flag for Ollama. Use a model from `ollama list`.
cade chat -L --endpoint http://localhost:11434 --model qwen3:4b

# Or create a dedicated agent for the local model
cade new local-qwen --model qwen3:4b
cade use local-qwen
export OLLAMA_BASE_URL="http://localhost:11434"
CADE_LOCAL_ONLY=1 cade -m "hello from a local model"

# Config — ~/.cade/config/cade.toml
[model_settings]
host = "http://localhost:8000/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` | Global settings + `[agent_defaults]` (model, provider, UI, …) |
| `config/agents/<name>.toml` | Per-agent config (model, prompt, `[[mcp]]`, `[serve]`, hooks) |
| `data/agents/<id>/` | Per-agent state: `threads/ memory/ tasks/ inbox/` |
| `run/agents/<name>/` | Per-agent daemon runtime: `serve.pid`, mcp-services, cron lease |
| `logs/cade.log` | Rotating log file |

Full layout, env vars, and TOML schema in [`docs/configuration.md`](./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

```bash
git clone https://github.com/arcadeai-labs/cade.git
cd cade
uv sync --extra dev
uv run pytest
uv run ruff check 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.

Build/release docs live in [`docs/development.md`](./docs/development.md). PRs
welcome — open an issue first for anything substantial.

---

## Resources

- [arcade.dev](https://arcade.dev) — product
- [docs.arcade.dev](https://docs.arcade.dev) — API and tool catalog
- [`docs/`](./docs/) — quickstart, examples, install, config, MCP, channels, voice, development, and adapters
- [Issues](https://github.com/arcadeai-labs/cade/issues) · [Releases](https://github.com/arcadeai-labs/cade/releases)

## License

MIT
