rpi-cli

The terminal coding-agent CLI — the rpi binary — built on the rpi-* library crates. It is the ready-to-run surface of the rpi project: an interactive TUI, a one-shot -p mode, a JSON event mode, durable sessions, and Rust cdylib plugin loading.

Install

cargo install rpi-cli

Requires Rust 1.78 or newer. Then point it at a provider and start it:

export ANTHROPIC_API_KEY=...     # or OPENAI_API_KEY, or ~/.rpi/agent/models.json
rpi

One-shot, and machine-readable output:

rpi -p "summarize the README"
rpi --mode json -p "list the crates"

Authentication

Credentials are resolved in priority order:

--api-key on the command line
~/.rpi/auth.json, written by rpi auth login (mode 0o600 on Unix)
the apiKey field of a provider in ~/.rpi/agent/models.json
provider environment variables: OPENAI_API_KEY, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY

~/.rpi/ can be relocated with RPI_CODING_AGENT_DIR.

Custom providers and gateways

Any Anthropic-Messages or OpenAI-compatible endpoint can be declared in ~/.rpi/agent/models.json:

{
  "providers": {
    "gateway": {
      "api": "anthropic-messages",
      "baseUrl": "https://gateway.example.com",
      "apiKey": "sk-gateway-secret",
      "authHeader": true,
      "headers": { "x-portkey-key": "…" },
      "models": [{ "id": "custom-claude", "name": "Custom Claude" }]
    }
  }
}

rpi --model gateway/custom-claude -p "hi"

Use "api": "openai-completions" for an OpenAI-compatible endpoint. Anthropic endpoint overrides also honour ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN.

Sessions and resources

Sessions are JSONL v4 files under the session directory, with branching and context compaction.
Project resources are discovered from .rpi/ (skills, prompts, themes, and SYSTEM.md), with ~/.rpi/agent/ as the global layer. When both define the same skill or prompt name, the project copy wins.
Plugins are loaded from project .rpi/extensions, global ~/.rpi/agent/extensions, and --extensions-dir.

Plugins

rpi install rpi-extension-example              # from crates.io
rpi install rpi-extension-example --version 0.1.0
rpi install my-extension --path ../my-extension --force   # local
rpi dev                                        # build + watch a local extension

rpi install builds the crate in release mode with Cargo and copies the resulting .dll / .so / .dylib into ~/.rpi/agent/extensions.

Remote mode

rpi --server                      # headless agent over TCP, prints a token
rpi --connect host:port --token T # zero-local-resource TUI client

The client holds no local provider, tools, extensions or session files; all agent work happens on the server. See docs/remote/user-guide.md.

Default tools

The CLI loads the Pi-compatible read, write, edit and bash tools. Additional implementations (grep, find, ls, docs, powershell) remain available in the rpi-tools library and through the default_tools setting.

Library usage

The crate also exposes its internals, so the CLI surface can be embedded:

[dependencies]
rpi-cli = "0.3"

For building your own agent, depend on rpi-agent and rpi-harness directly instead — see docs/agent/project-structure.md.

Documentation

User guide: https://rpi.laofu.online/docs.html
Architecture: docs/architecture/overview.md
Extension authoring: docs/extensions/authoring.md
Changelog: CHANGELOG.md

License

MIT. See LICENSE and NOTICE.

rpi-cli 0.3.23