RomanNum3ral
/
cai
mirror of https://github.com/aliasrobotics/cai.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
cai/docs/cli/commands_reference.md

834 lines
28 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# CAI CLI and REPL commands reference
This page documents flags accepted by the `cai` binary and slash commands in the **CLI** interactive REPL. For **Textual TUI** shortcuts, multi-terminal routing, and UI-only behavior, see the [TUI commands reference](../tui/commands_reference.md).
---
## On this page
1. [Binary `cai` CLI flags](#binary-cai-cli-flags)
2. [REPL syntax](#repl-syntax)
3. [Agents and models](#agents-and-models)
4. [Conversation and context](#conversation-and-context)
5. [Memory](#memory)
6. [Parallel execution and queues](#parallel-execution-and-queues)
7. [Configuration and environment](#configuration-and-environment)
8. [Integrations](#integrations)
9. [System and processes](#system-and-processes)
10. [Utilities](#utilities)
11. [Quick reference table](#quick-reference-table)
12. [Commands registered](#commands-registered)
13. [Next steps](#next-steps)
---
## Binary `cai` CLI flags
The binary parses known flags and treats **unrecognized tokens as an initial prompt** (positional prompt text), similar to `parse_known_args()` semantics.
| Flag | Type | Default | Description |
| -------------------- | -------- | --------- | ------------------------------------------------------------------------------------- |
| `--tui` | flag | false | Start CAI in Textual TUI (multi-terminal). Sets `CAI_TUI_MODE=true`. |
| `--yaml FILE` | option | — | Load parallel agent definitions from a YAML file. |
| `--prompt TEXT` | option | — | Initial prompt executed immediately on startup. |
| `--version` | flag | false | Print `cai-framework` version and exit. |
| `--update` | flag | false | Check for updates and install if available. Requires `ALIAS_API_KEY`. |
| `--continue` / `-c` | flag | false | Enable auto-continue mode (`CAI_CONTINUE_MODE=true`). |
| `--resume [SESSION]` | optional | — | Resume a prior session: `last`, `list`, a session id, or path to a `.jsonl` log. |
| `--logpath PATH` | option | — | Custom log directory (often used with `--resume`). |
| `--unrestricted` | flag | false | Enable abliteration steering: `CAI_UNRESTRICTED=true`. |
| `--yolo` | flag | false | Skip confirmation for sensitive commands (`CAI_YOLO=true`). **Insecure.** |
| `--api` | flag | false | Run CAI as an HTTP API backend (FastAPI + uvicorn). See [CAI API Backend](../api.md). |
| `--api-host` | option | 127.0.0.1 | API bind host. Env: `CAI_API_HOST`. |
| `--api-port` | int | 8000 | API bind port. Env: `CAI_API_PORT`. |
| `--api-reload` | flag | false | Uvicorn auto-reload. Env: `CAI_API_RELOAD`. |
| `--api-workers` | int | 1 | Uvicorn workers. Env: `CAI_API_WORKERS`. |
**API mode:** operational details, auth headers, and routes are documented in [CAI API Backend](../api.md). For a single list of all binary flags, stay on this page; the API doc focuses on HTTP behavior.
**Example (non-interactive prompt):**
```bash
cai --prompt "Summarize SSH hardening for Ubuntu 22.04"
```
---
## REPL syntax
```text
/command [subcommand] [arguments ...]
```
Aliases are listed per command. Arguments in `[]` are optional; `|` means alternatives.
In **Example** sections below, lines starting with `CAI>` are commands you type; other lines are **representative** REPL output (exact text, tables, and colors vary by build and environment).
---
## Agents and models
### `/agent` (`/a`)
Manage and switch agents.
| Subcommand | Arguments | Description |
| ---------- | ----------------------- | ------------------------------------------------------- |
| `list` | — | List available agents and parallel patterns. |
| `select` | name / number / pattern | Switch to the given agent; transfers history. |
| `info` | [name / number] | Detailed info: key, model, tools, handoffs, guardrails. |
| `current` | — | Active agent configuration (in TUI: all terminals). |
| `new` | — | Create a new agent interactively. |
- **No arguments:** same as `/agent current`.
- **Shortcut:** `/agent red_teamer` is equivalent to `/agent select red_teamer`.
**Example:**
```text
CAI> /agent list
… table of agents, models, and ids (layout varies by build) …
CAI> /agent select red_teamer
Switched to agent: red_teamer
CAI> /agent
… same as /agent current: active agent, model, tools summary …
```
### `/model` (`/mod`)
View or change the active LLM. The LiteLLM-backed catalog is under the `**show**` subcommand (for example `**/model show**` or `**/mod show**`).
| Usage | Description |
| -------------------------------- | -------------------------------------------------------------------------------------------------- |
| `/model` (no extra args) | Prints the current model and a numbered table of predefined models (with pricing where available). |
| `/model <name>` | Sets the model by name (typically via `CAI_MODEL`), e.g. `/model gpt-4o`. |
| `/model <n>` | Selects by number from the last displayed table, e.g. `/model 5`. |
| `/model show` | Lists LiteLLM-backed models (full catalog). Use `/model` / `/model <n>` to switch after choosing. |
| `/model show supported` | Same catalog filtered to models with function-calling support. |
| `/model show <search>` | Filter the catalog by substring. |
| `/model show supported <search>` | Filter to supported models matching a substring. |
**Examples:**
```text
CAI> /model
Current model: alias1
… numbered shortcuts / pricing table …
CAI> /model gpt-4o
Model set to gpt-4o
CAI> /model show ollama
… LiteLLM rows whose id/name contains "ollama" …
CAI> /mod show supported
… catalog filtered to function-calling models …
```
---
## Conversation and context
### `/flush` (`/clear`)
Clear conversation history.
| Subcommand | Arguments | Description |
| ---------- | --------- | ---------------------------------------------------- |
| `all` | — | Clear **all** agents, plus sudo cache and allowlist. |
| `agent` | name | Clear history for one agent. |
- **CLI, no args:** interactive menu of agents that have history.
- **TUI, no args:** clears **only** the current terminal.
- **Shortcut:** `/flush Red Teamer` or `/flush P2` clears by display name or agent id.
**Example:**
```text
CAI> /flush agent red_teamer
Cleared history for red_teamer.
CAI> /flush all
Cleared all agent histories (and related caches per build).
```
### `/compact` (`/cmp`)
Summarize the conversation into memory.
| Subcommand | Arguments | Description |
| ---------- | ------------------------- | --------------------------------- |
| `model` | name / number / `default` | Model used for compaction. |
| `prompt` | text / `reset` | Custom summarization prompt. |
| `status` | — | Show current compaction settings. |
Inline flags: `--model …`, `--prompt …`. **No args:** in parallel mode compacts all; in single-agent / TUI shows a menu.
**Example:**
```text
CAI> /compact status
Compaction model: default | custom prompt: (none)
CAI> /compact
… summary written to memory / thread shortened (wording varies) …
```
### `/history` (`/his`)
History with optional filtering.
| Subcommand | Arguments | Description |
| ---------- | --------- | ---------------------------- |
| `all` | — | Full history for all agents. |
| `agent` | name | History for one agent. |
| `search` | term | Search the history. |
| `index` | — | Message index. |
**No arguments:** interactive control panel.
**Example:**
```text
CAI> /history search "nmap"
… matching transcript excerpts …
CAI> /history agent red_teamer
… recent messages for that agent …
```
### `/load` (`/l`)
Load JSONL into context.
| Subcommand | Arguments | Description |
| ---------- | --------- | ---------------------------------- |
| `agent` | [path] | Load history for the active agent. |
| `all` | [path] | Load for all agents. |
| `parallel` | [path] | Load into parallel configuration. |
| `load-all` | — | Load all available logs. |
**No arguments:** load from `logs/last`.
**Example:**
```text
CAI> /load session_2025-04-01.jsonl
Loaded conversation from session_2025-04-01.jsonl
```
### `/merge` (`/mrg`)
Shortcut for `/parallel merge`. Merges parallel contexts into the main thread and exits parallel mode.
**Example:**
```text
CAI> /merge
… merged parallel branches into main; returned to single-agent mode …
```
---
## Memory
### `/memory` (`/mem`)
Persistent memory under `~/.cai/memory`.
| Subcommand | Arguments | Description |
| -------------- | -------------- | -------------------------------------- |
| `list` | — | List saved memories. |
| `save` | [name] [agent] | Save conversation as memory. |
| `apply` | id / name | Apply memory to context. |
| `show` | id / name | Show one memory’s content. |
| `delete` | id / name | Delete a memory. |
| `remove` | id / name | Alias of `delete`. |
| `merge` | id1 id2 … | Merge multiple memories. |
| `status` | — | Memory subsystem status. |
| `compact` | [agent] | Compact memory for an agent. |
| `clear` | — | Delete all memories. |
| `list-applied` | — | Memories applied to the current agent. |
**No arguments:** control panel. A single id such as `M001` routes to `show`.
**Example:**
```text
CAI> /memory list
M001 pentest-notes-20250401 12 messages
M002 ctf-web-flags 8 messages
CAI> /memory show M001
… saved memory content …
```
---
## Parallel execution and queues
### `/parallel` (`/par`, `/p`)
Configure and run parallel agents.
| Subcommand | Arguments | Description |
| ----------------- | ----------------------- | ------------------------------------------- |
| `add` | agent [`--model` model] | Add an agent to the parallel set. |
| `list` | — | List configured parallel agents. |
| `clear` | — | Remove parallel agents (no merge). |
| `remove` | agent / index | Remove one parallel agent. |
| `override-models` | model | Set a shared model for all parallel agents. |
| `merge` | [`all` / agent] | Merge contexts into the main thread. |
| `prompt` | agent / `all` `"text"` | Enqueue a prompt for agent(s). |
| `run` | — | Run all enqueued prompts in parallel. |
**No arguments:** show current parallel configuration.
**Example:**
```text
CAI> /parallel list
P1 red_teamer alias1
P2 blueteam gpt-4o
CAI> /parallel prompt all "Enumerate TLS on target:443"
… prompts queued …
CAI> /parallel run
… parallel fan-out; per-terminal output in TUI …
```
### `/queue` (`/que`)
Sequential prompt queue.
| Subcommand | Arguments | Description |
| --------------- | --------- | ----------------------------- |
| `show` / `list` | — | Show queued prompts. |
| `add` | `"text"` | Append a prompt. |
| `run` | — | Run all prompts sequentially. |
| `remove` | index | Remove one entry. |
| `clear` | — | Empty the queue. |
| `next` | — | Run only the next prompt. |
| `load` | path | Load prompts from a file. |
**Example:**
```text
CAI> /queue add "Run nmap -sV on 10.0.0.5"
Queued #1
CAI> /queue show
#1 Run nmap -sV on 10.0.0.5
CAI> /queue run
… runs prompts in order …
```
### `/continue`
Auto-continue mode.
| Subcommand | Description |
| ---------- | ----------------------------- |
| `on` | Set `CAI_CONTINUE_MODE=true`. |
| `off` | Disable auto-continue. |
| `status` | Show state. |
**No arguments:** turns the mode **on**.
**Example:**
```text
CAI> /continue status
CAI_CONTINUE_MODE=false
CAI> /continue on
Auto-continue enabled.
```
---
## Configuration and environment
### `/env` (`/e`)
Catalog and edit `CAI_*` and `CTF_*` variables; sensitive values are masked in listings.
| Subcommand | Arguments | Description |
| ---------- | ------------------------ | ----------------------------------------------------------------------------- |
| `list` | — | Numbered catalog with descriptions and current values (default when helpful). |
| `get` | `VAR` or index | Print one variable's effective value. |
| `set` | `VAR` or index, `value…` | Set a variable (by name or by catalog number from `list`). |
| `default` | — | Restore catalog defaults where applicable. |
**No arguments / bare `/env`:** compact view of live `CAI_`* / `CTF_`* values (not the full numbered catalog). Piping: `/env \| grep VAR` works in supported terminals.
Alternate assignment style (some builds): `/env set VAR=value` or multiple tokens after `set`.
**Examples:**
```text
CAI> /env list
… numbered catalog: CAI_MODEL, CAI_MAX_TURNS, CTF_NAME, … with current values …
CAI> /env get CAI_MODEL
CAI_MODEL=alias1
CAI> /env set CAI_MODEL gpt-4o
Set CAI_MODEL=gpt-4o
CAI> /env set 18 5.0
Set variable #18 to 5.0 (index 18 from /env list)
CAI> /env
CAI_MODEL=gpt-4o
CAI_MAX_TURNS=100
CTF_NAME=
… other CAI_* / CTF_* keys in this session …
CAI> /env default
… restored defaults where the catalog defines them …
```
### `/settings` (`/set`)
Interactive settings and FAQ.
| Topic | Description |
| ------------------------------- | ------------------------- |
| `faq` / `help` / `troubleshoot` | FAQ and troubleshooting. |
| `validate` / `check` | Validate API keys. |
| `status` / `info` | System status. |
| `lang` / `language` | Language selector. |
| `ollama` / `local` | Ollama / local model FAQ. |
**No args:** full-screen interactive UI in CLI; TUI-adapted UI in TUI.
**Example:**
```text
CAI> /settings faq
… opens FAQ / troubleshooting flow …
```
### `/temperature` (`/temp`)
Show or set `CAI_TEMPERATURE` (float `0.0`–`2.0`).
**Example:**
```text
CAI> /temp
CAI_TEMPERATURE=0.7
CAI> /temp 0.2
CAI_TEMPERATURE=0.2
```
### `/topp` (`/top_p`)
Show or set nucleus sampling `CAI_TOP_P` (float `0.0`–`1.0`).
**Example:**
```text
CAI> /topp
CAI_TOP_P=1.0
CAI> /topp 0.9
CAI_TOP_P=0.9
```
---
## Integrations
### `/mcp`
Model Context Protocol servers.
| Subcommand | Arguments | Description |
| -------------- | ------------ | --------------------------------------------------------------------------- |
| `load` | url name | Load an MCP **SSE** server. |
| `load-stdio` | command name | Load an MCP **stdio** server (some builds use `/mcp load stdio …` instead). |
| `list` | — | Active MCP connections. |
| `add-to-agent` | agent server | Attach MCP tools to an agent. |
Many builds also support extra helpers (`tools`, `status`, `remove`, …); use `/mcp help` locally.
**Example:**
```text
CAI> /mcp load https://example.com/mcp/sse ctf-tools
Loaded MCP server "ctf-tools" (SSE).
CAI> /mcp list
ctf-tools SSE connected
```
### `/api` (`/apikey`)
Manage `ALIAS_API_KEY` in the environment / `.env`.
| Subcommand | Arguments | Description |
| ---------- | --------- | ------------------------ |
| `show` | — | Display key (masked). |
| `set` | key | Persist `ALIAS_API_KEY`. |
**No arguments:** `show`. Shortcut: `/api sk-…` behaves like `/api set sk-…`.
**Example:**
```text
CAI> /api
ALIAS_API_KEY=sk-…xxxx (masked)
CAI> /api set sk-proj-…
API key saved to environment / .env (path depends on build).
```
### `/auth`
API users and device pairing.
| Subcommand | Arguments | Description |
| ---------- | ----------------- | --------------------------- |
| `add-user` | username password | Add an API user. |
| `add-ip` | ip[:port] | Register an IP for pairing. |
**Example:**
```text
CAI> /auth add-user analyst hunter2
User "analyst" created.
CAI> /auth add-ip 203.0.113.10
Registered pairing for 203.0.113.10
```
---
## System and processes
### `/shell` (`/s`, `$`)
Run the remainder of the line as a shell command.
Examples: `/shell ls -la`, `/s whoami`, `$ nmap -sV 10.0.0.1`
**Example:**
```text
CAI> $ whoami
alice
CAI> /shell ls -la /tmp
total 12
drwxrwxrwt … /tmp
```
### `/workspace` (`/ws`)
Workspace (host or Docker container).
| Subcommand | Arguments | Description |
| ---------- | --------- | ---------------------------------- |
| `set` | path | Set working directory / workspace. |
| `get` | — | Show current workspace. |
| `ls` | [path] | List files. |
| `exec` | command | Run a command in the workspace. |
| `copy` | src dst | Copy between host and container. |
**No arguments:** same as `get`.
**Example:**
```text
CAI> /ws get
Workspace: /home/alice/projects/cai-target
CAI> /ws ls src
agent.py tools.py …
```
### `/virtualization` (`/virt`)
Docker environments.
| Subcommand | Arguments | Description |
| ---------- | --------------- | ---------------- |
| `pull` | image | Pull an image. |
| `run` | image [options] | Run a container. |
**No arguments:** Docker status. A single non-subcommand argument can select/activate an image as container context (see `/help virtualization` on your build).
**Example:**
```text
CAI> /virt
Docker: running images: 12 active: cai-kali:latest
CAI> /virt pull kalilinux/kali-rolling
… pull progress …
```
---
## Utilities
### `/help` (`/h`, `/?`)
Built-in help and topic deep-dives.
Example topics: `agent`, `parallel`, `queue`, `memory`, `history`, `compact`, `flush`, `load`, `merge`, `env`, `workspace`, `virtualization`, `mcp`, `shell`, `model`, `graph`, `aliases`, `commands`, `quick`, `quickstart`, `topics`.
Examples: `/help`, `/help parallel`, `/? model`
**Example:**
```text
CAI> /help env
… environment catalog / usage for /env …
```
### `/cost` (`/costs`, `/usage`)
| Subcommand | Description |
| ---------- | --------------------------------------- |
| `summary` | Session summary (default when no args). |
| `models` | Per-model breakdown. |
| `daily` | Daily costs. |
| `sessions` | Per-session costs. |
| `reset` | Reset counters. |
**Example:**
```text
CAI> /cost
Session spend: $0.42 tokens in: 120k tokens out: 18k
CAI> /cost models
alias1 $0.30
gpt-4o $0.12
```
### `/graph` (`/g`)
| Subcommand | Arguments | Description |
| ---------- | --------- | -------------- |
| `all` | — | Full graph. |
| `timeline` | — | Timeline view. |
| `stats` | — | Statistics. |
| `export` | [path] | Export graph. |
**No args:** active agent view. A free argument can select `P1`, `P2`, or an agent name.
**Example:**
```text
CAI> /graph
… ASCII or Rich-rendered interaction graph for the active agent …
```
### `/exit` (`/q`, `/quit`)
Clean exit: telemetry flush, session end, `sys.exit(0)`.
**Example:**
```text
CAI> /exit
Goodbye.
```
### `/quickstart` (`/qs`, `/quick`)
Essential setup instructions and tables (no args).
**Example:**
```text
CAI> /quickstart
… printed checklist: keys, /env list, /model show, agents, … …
```
### `/replay`
Replay a session JSONL.
- Path to `.jsonl`, or no args → `logs/last`.
- Optional trailing **numeric** argument: delay in seconds between actions.
- `stop` / `cancel`: stop in-progress replay (TUI).
Sets `CAI_DISABLE_SESSION_RECORDING=true` while replaying.
**Example:**
```text
CAI> /replay logs/last.jsonl 0.5
… replay with 0.5s delay between actions …
```
### `/resume` (`/r` when registered)
Resume a previous session. Optional:
- `--full` / `-f` — full history.
- Path to `.jsonl`, or session id.
- No args — latest session.
**Example:**
```text
CAI> /resume --full ./logs/session_20250401.jsonl
… session restored with full transcript …
```
### `/sessions` (`/sess`)
List recent sessions; optional count limit or session id / label for details.
**Example:**
```text
CAI> /sessions 5
… last five session ids, paths, and labels …
```
### `/ctr`
Cyber threat reasoning / attack graphs. Optional alias form `ctr` (without leading `/`) in some builds.
| Subcommand | Description |
| ---------- | --------------------------- |
| `show` | Current CTR analysis. |
| `graph` | Attack graph visualization. |
| `list` | Available analyses. |
| `use` | Select an analysis. |
| `open` | Open dedicated view. |
**No arguments:** full CTR analysis output.
**Example:**
```text
CAI> /ctr show
… current CTR narrative / indicators …
```
### `/metadebug` (`/md`)
Meta-agent debugging (**TUI**). Requires `CAI_META_AGENT=true`.
**Example:**
```text
CAI> /md
… meta-agent trace / routing (TUI only; requires CAI_META_AGENT=true) …
```
---
## Quick reference table
| Command | Aliases | Description |
| ----------------- | ------------------ | ----------------------------------------------------------------- |
| `/agent` | `/a` | Manage and switch agents |
| `/api` | `/apikey` | Show or set `ALIAS_API_KEY` |
| `/auth` | — | API users and device pairing |
| `/compact` | `/cmp` | Compact conversation to memory |
| `/continue` | — | Auto-continue mode |
| `/cost` | `/costs`, `/usage` | Usage cost statistics |
| `/ctr` | `ctr` | CTR analysis / attack graphs |
| `/env` | `/e` | Catalog / get / set / `default` for `CAI_*` and `CTF_*` variables |
| `/exit` | `/q`, `/quit` | Exit the REPL |
| `/flush` | `/clear` | Clear conversation history |
| `/graph` | `/g` | Interaction graph |
| `/help` | `/h`, `/?` | Help and documentation |
| `/history` | `/his` | History with filters |
| `/load` | `/l` | Load JSONL into context |
| `/mcp` | — | MCP servers |
| `/memory` | `/mem` | Persistent memory (`~/.cai/memory`) |
| `/merge` | `/mrg` | Merge parallel contexts |
| `/metadebug` | `/md` | Meta-agent debug (TUI) |
| `/model` | `/mod` | View or change model; `show` subcommand lists LiteLLM catalog |
| `/parallel` | `/par`, `/p` | Parallel agents |
| `/queue` | `/que` | Sequential prompt queue |
| `/quickstart` | `/qs`, `/quick` | Quick start guide |
| `/replay` | — | Replay JSONL session |
| `/resume` | `/r` | Resume session |
| `/sessions` | `/sess` | List recent sessions |
| `/settings` | `/set` | Interactive settings / FAQ |
| `/shell` | `/s`, `$` | Shell escape |
| `/temperature` | `/temp` | Sampling temperature |
| `/topp` | `/top_p` | Top-p sampling |
| `/virtualization` | `/virt` | Docker environments |
| `/workspace` | `/ws` | Workspace management |
---
## Commands registered
The following modules are imported in `[src/cai/repl/commands/__init__.py](../../src/cai/repl/commands/__init__.py)` in a typical OSS snapshot: `agent`, `compact`, `cost`, `env`, `exit`, `flush`, `graph`, `help`, `history`, `load`, `mcp`, `memory`, `merge`, `model`, `parallel`, `quickstart`, `shell`, `virtualization`, `workspace`. Your checkout may load extra modules; use `/help` locally for the authoritative list.
Commands such as `/resume`, `/queue`, `/continue`, `/settings`, `/api`, `/auth`, `/replay`, `/sessions`, `/ctr`, and `/metadebug` are listed above for completeness but may ship only in builds that add their modules to the REPL registry.
---
## Next steps
- [CLI getting started](getting_started.md)
- [CLI advanced usage](advanced_usage.md)
- [CLI overview](cli_index.md)
- [CAI API Backend](../api.md) — HTTP API when using `cai --api`
---
Reference in New Issue View Git Blame Copy Permalink