# 6. CLI Reference

Everything below is the surface of the shipped `rayu` **v3** binary. Every flag
and subcommand is real: it was read from `rayu --help` on a release build. When
in doubt, `rayu --help`, `rayu <subcommand> --help` and `/help` inside a session
are authoritative.

```text
rayu [OPTIONS] [COMMAND]
```

- No subcommand → **interactive** terminal UI.
- `rayu run <message>` → one prompt, print the answer, exit.
- A subcommand (`server`, `mcp`, `cloud`, …) runs that subcommand.

---

## Global options

These are accepted before or after a subcommand.

| Flag | Description |
|------|-------------|
| `-p, --provider <PROVIDER>` | Initial provider. In a Rayu-only build the only value is `rayu`; `auto` (the default) resolves to it. |
| `-C, --cwd <DIR>` | Working directory for the local client process. |
| `--remote-working-dir <DIR>` | Working directory to send to a remote server when using `--socket`. |
| `-m, --model <MODEL>` | Model id or alias for this run, e.g. `deepseek-v4.1-flash-cloud`. |
| `--provider-profile <NAME>` | Named profile from `[providers.<name>]` in `config.toml`. Implies `--provider openai-compatible` for OpenAI-compatible profiles. |
| `--resume [<ID>]` | With no value: open the session picker. With a session id: resume it. |
| `--no-update` | Skip the automatic update check for this run. |
| `--auto-update` | Auto-update when a newer build exists (default `true` for release builds). |
| `--quiet` | Suppress non-error CLI/status output for scripts and wrappers. Also `RAYU_QUIET=1`. |
| `--trace` | Log tool inputs/outputs and token usage to stderr. |
| `--socket <PATH>` | Custom server socket instead of the shared daemon socket. |
| `--debug-socket` | Enable the debug socket (broadcasts all TUI state changes). |
| `--ssh <HOST>` | Run the UI locally and attach to the persistent Rayu server on an SSH host. |
| `--ssh-binary <PATH>` | Remote `rayu` name or path (requires `--ssh`). |
| `--ssh-server-socket <PATH>` | Remote daemon socket override (requires `--ssh`). |
| `--no-selfdev` | Disable auto-detection of the rayucode repository and self-dev mode. |
| `--onboarding-sim` | Rehearse real first-run onboarding as if rayu were new on this machine. |
| `--update-sim` | Launch the TUI and autoplay a safe simulated update. |
| `--licenses` | Print the bundled software licenses and third-party notices. |
| `-h, --help` | Show help. |
| `-V, --version` | Print the version line. |

There is **no** `--print` / `-p "prompt"` flag in v3. `-p` is `--provider`.
Non-interactive prompting is the [`run`](#rayu-run) subcommand.

### Tool exposure

| Flag | Description |
|------|-------------|
| `--tool-profile <PROFILE>` | `full` (default), `acp`, `minimal`/`lite`, or `none`. |
| `--tools <LIST>` | Explicit allow-list, comma-separated, e.g. `bash,read,write,apply_patch`. `*` or `all` means the unrestricted toolset. |
| `--disabled-tools <LIST>` | Tools to hide after the profile is applied. |
| `--disable-base-tools` | Hide all built-in tools unless `--tools` or `[tools].enabled` opts them back in. |
| `--mcp-tools <MODE>` | MCP tool exposure: `auto` (default), `eager`, `deferred`. |
| `--mcp-tools-token-threshold <TOKENS>` | Accepted for compatibility; retained config value. |

The same settings live in `[tools]` in `config.toml`, and each has an
environment override: `RAYU_TOOL_PROFILE`, `RAYU_TOOLS`, `RAYU_DISABLED_TOOLS`.
See [Configuration](./05-configuration.md).

---

## `rayu run`

Run a single message and exit. This is the headless entry point.

```text
rayu run [--json | --ndjson] <MESSAGE>
```

| Flag | Description |
|------|-------------|
| `--json` | Emit one JSON result object instead of streaming text. |
| `--ndjson` | Emit newline-delimited JSON events while the response streams. |

Global `--model`, `--provider`, `--resume <id>`, `--quiet` and the tool-exposure
flags all apply.

```bash
rayu run "explain what src/auth.rs does"
rayu run --model deepseek-v4.1-flash-cloud "list the modules"
rayu run --json "list the modules" | jq -r '.text'
rayu --resume session_fox_1795191775193_b3fe756d07741edb run "now add tests"
```

`--json` writes one object:

```json
{
  "session_id": "session_eagle_1795229551083_d62d03aec2ee9157",
  "provider": "rayu",
  "model": "deepseek-v4.1-flash-1017-cloud",
  "text": "ok",
  "usage": {
    "input_tokens": 23425,
    "output_tokens": 19,
    "cache_read_input_tokens": 13056,
    "cache_creation_input_tokens": null
  },
  "rayu_credits": 17.732
}
```

`--ndjson` streams one JSON object per line. The event types are `start`
(`session_id`, `provider`, `model`), `text_delta`, `text_replace`,
`text_suffix_replace`, `tool_start`, `tool_input`, `tool_exec`, `tool_done`,
`tokens` (usage counters), and a final event.

Auto-poke can extend a `rayu run` with follow-up turns when the model stops with
unfinished todos. That is why `text` is the whole final answer, not one delta.

`rayu run` loads `~/.rayu/mcp.json`, so MCP tools are available headlessly just
as they are in the TUI. See [Headless & CI](./30-headless-and-ci.md).

---

## `rayu login`

Log in to a provider. In a Rayu-only build, `rayu` is the only provider.

```text
rayu login [OPTIONS] [PROVIDER]
```

| Flag | Description |
|------|-------------|
| `-a, --account <LABEL>` | Account label for multi-account support (stored labels are auto-numbered). |
| `--no-browser` (alias `--headless`) | Do not open a browser; show a login QR for another device. Useful over SSH. |
| `--print-auth-url` | Print a script-friendly URL and persist temporary login state for later completion. |
| `--callback-url <URL>` | Complete a printed flow with a full callback URL or query string. |
| `--auth-code <CODE>` | Complete a printed flow with a provider-issued authorization code. |
| `--json` | Machine-readable output for scripted logins. |
| `--complete` | Resume a pending scriptable flow that needs no callback or code. |
| `--flow-id <ID>` | Isolate temporary login state (1–64 ASCII letters, digits, `_`, `-`). |
| `--cancel` | Cancel one provider's pending flow. Saved credentials are untouched. |
| `--no-validate` | Save credentials without the post-login live validation (offline/CI setup). |
| `--api-base <URL>` | OpenAI-compatible base URL for `openai-compatible`/custom profiles. |
| `--api-key <KEY>` | OpenAI-compatible key. If omitted, `rayu` prompts securely. |
| `--api-key-env <NAME>` | Environment variable name to use for that key. |
| `--google-access-tier <full\|readonly>` | Gmail/Google access tier for non-interactive Google flows. |
| `--google-services <LIST>` | Google services to authorize: `gmail`, `calendar`, `all`. |
| `--google-client-json <PATH\|auto>` | Import a Google OAuth client JSON before login. |
| `--setup` | Re-run the guided Google Cloud setup. |

```bash
rayu login                      # interactive picker
rayu login rayu                 # Rayu account
rayu login --provider rayu --no-browser
rayu account status             # plan, credits, reset date
```

---

## `rayu account`

```text
rayu account login | status | manage | logout
```

| Command | Description |
|---------|-------------|
| `login` | Open the Rayu browser sign-in and wait for the loopback redirect (`--no-browser`, `--print-auth-url`, `--callback-url` supported). |
| `status` | Print email, name, plan, credits remaining/used, and reset date. |
| `manage` | Open the Rayu dashboard in your browser. |
| `logout` | Securely clear the local Rayu session and API-key state. |

`--json` is accepted by `status` for machine-readable output.

---

## `rayu model`

```text
rayu model list [--json] [--verbose]
```

Lists the model ids you can pass to `-m`/`--model`. The list is read from the
live catalog your credential is entitled to, so it changes without a new release.

---

## `rayu provider`

```text
rayu provider list | current | add
```

| Command | Description |
|---------|-------------|
| `list [--json]` | Provider ids accepted by `--provider`. In a Rayu-only build this is `rayu`. |
| `current [--json]` | The requested and resolved provider selection. |
| `add <NAME> --base-url <URL> -m <MODEL>` | Add a named OpenAI-compatible profile. Requires a build with `ENABLE_OTHER_PROVIDER=true`. |

`provider add` also accepts `--api-key-env`, `--api-key-stdin`, `--api-key`,
`--no-api-key`, `--auth`, `--auth-header`, `--env-file`, `--context-window`,
`--provider-routing`, `--model-catalog`, `--set-default`/`--default`,
`--overwrite` and `--json`.

```bash
rayu provider add my-gateway \
  --base-url https://llm.example.com/v1 \
  -m qwen3-coder --api-key-env MY_GATEWAY_API_KEY --set-default
```

On a Rayu-only build this exits with:

```text
Error: Other providers are disabled in this build (ENABLE_OTHER_PROVIDER=false).
Use Rayu authentication ('rayu login --provider rayu' / '/login rayu') or
RAYU_API_KEY, or recompile with ENABLE_OTHER_PROVIDER=true.
```

See [Providers](./03-providers.md).

---

## `rayu usage`

Show usage limits for connected providers. With a Rayu account it prints plan
credits as a bar plus remaining and used numbers.

```bash
rayu usage
rayu usage --json
```

---

## `rayu version`

```bash
rayu version          # human-readable
rayu version --json   # version, semver, git hash/tag, build time, release flag
```

---

## `rayu update`

```bash
rayu update                       # newest build on the current channel
rayu update --channel stable      # persist the stable channel
rayu update --channel preview     # opt into previews
```

Downloads the newest verified release, checks `SHA256SUMS`, swaps the binary
atomically, and reloads a running server without dropping sessions.

---

## `rayu telemetry`

```text
rayu telemetry status | enable | disable
```

`status` prints whether usage telemetry is enabled, whether content sharing is on
(the default is off), and the installation telemetry id. `--json` is accepted.
See [Policies](./21-policies.md).

---

## Server and sessions

### `rayu server`

```text
rayu server start | promote | reload | stop
```

| Command | Description |
|---------|-------------|
| `start [--json]` | Start the background server if it is not already running. |
| `promote [VERSION] [--json]` | Pin the shared server channel to an installed version. Run `reload` to apply. |
| `reload [--force] [--json]` | Gracefully hand live sessions to a freshly exec'd server on the newest binary. |
| `stop --force [--json]` | Terminate the daemon. Requires `--force` because it drops in-flight sessions. |

Prefer `reload` after an update: it preserves headless and swarm work. Use
`stop --force` only for a wedged daemon.

### `rayu session`

```text
rayu session rename <ID|NAME> [NAME] [--clear] [--json]
```

Rename a saved session, or `--clear` its custom name.

### `rayu restart`

```text
rayu restart save | restore | status | clear
```

Snapshot the set of open rayu windows and restore them after a reboot (or
`clear` the snapshot).

---

## `rayu mcp`

```text
rayu mcp test <SERVER> | list | login <SERVER> | logout <SERVER>
```

| Command | Description |
|---------|-------------|
| `list` | List configured servers and local auth state without connecting. |
| `test <SERVER>` | Connect once, list server info and tools, disconnect. Never starts OAuth. |
| `login <SERVER>` | Explicitly sign in to a configured remote MCP server using OAuth. |
| `logout <SERVER>` | Forget local OAuth credentials (does not revoke tokens or remove static headers). |

Servers are declared in `~/.rayu/mcp.json`, `./.mcp.json` or `./.rayu/mcp.json`;
v3 has no `rayu mcp add`. See [MCP servers](./27-mcp.md).

---

## `rayu telegram`

```text
rayu telegram link [--botfather] | uninstall | status | disconnect
```

| Command | Description |
|---------|-------------|
| `link` | Pair your Rayu account (or `--botfather` for a dedicated bot) with this daemon. |
| `status` | Link status for this Rayu profile. |
| `disconnect` | Disconnect Telegram from this profile. |
| `uninstall` | Control whether a linked chat may uninstall this managed CLI. |

See the [Telegram bot](./16-telegram.md) page.

---

## `rayu cloud`

Move live sessions to a cloud host over SSH, or manage Jade cloud-synced session
storage.

```text
rayu cloud move | return | where | fork | send | status | wait | logs
rayu cloud problems | doctor | attach | env | sessions | replace
```

| Command | Description |
|---------|-------------|
| `move` | Move a live session (transcript, repo state, env notes) to a cloud host and keep working there. Local files stay editable; git reconciles on return. |
| `return` | Pull the cloud transcript back and merge its git work with a normal 3-way merge. |
| `where` | Show where moved sessions live and how repos have diverged. |
| `fork` | Fork into a new child session and move only the child, optionally starting a task. |
| `send <message>` | Send a message to a cloud session; the turn runs detached. |
| `status` | Whether a cloud session is running, idle or failed, with recent messages and the run log. |
| `wait` | Block until a detached turn finishes. Exits `2` on timeout without cancelling the turn. |
| `logs` | Tail a cloud session's detached run log. |
| `problems` | Recent failed `/cloud` and `/local` attempts recorded on this machine. |
| `doctor` | Read-only health check: SSH reachability, remote version, moved sessions, recent failures. |
| `attach` | Attach this terminal to a session that lives on a cloud host. |
| `env` | Transfer explicit project environment requirements without exposing values. |
| `sessions` | Jade cloud storage: `configure`, `status`, `upload`, `upload-latest`, `sync`, `list`, `verify`, `dashboard`, `view`. |
| `replace` | Replace the cloud checkout with this local repo, keeping a backup. |

Most commands accept `--json`. A few internal subcommands (`receive`,
`activate`, `export`, `inspect`) are hidden protocol helpers.

---

## `rayu auth`, `auth-test`, `provider-doctor`

| Command | Description |
|---------|-------------|
| `rayu auth status [--json]` | Configured authentication for model and tool providers. |
| `rayu auth doctor [PROVIDER] [--validate] [--json]` | Diagnose provider auth problems and suggest next steps. |
| `rayu auth import --stdin [--json]` | Import one selected OAuth login from a trusted client over stdin. Never overwrites an existing store. |
| `rayu auth-test` | End-to-end auth test: optional `--login`, credential probe, refresh, provider smoke turn. `--all-configured`, `--no-smoke`, `--no-tool-smoke`, `--prompt`, `--json`, `--output`, `--coverage`, `--context-audit`. |
| `rayu provider-doctor <PROVIDER> [--tier offline\|catalog\|full] [--json]` | Walk the strict end-to-end checkpoints: catalog, picker, model switch, chat, streaming, tools. |
| `rayu provider-test-coverage [PROVIDER] [MODEL] [--coverage-file F] [--coverage-limit N]` | Show live-test coverage evidence. |

---

## `rayu memory`

```text
rayu memory list [-s SCOPE] [-t TAG]
rayu memory search <QUERY> [--semantic]
rayu memory export <FILE> [-s SCOPE]
rayu memory import <FILE> [-s SCOPE] [--overwrite]
rayu memory stats
```

Scope is `project`, `global` or `all`. See
[Memory & project instructions](./25-memory-and-project-instructions.md).

---

## `rayu ambient`

```text
rayu ambient status | log | trigger | stop
```

Ambient mode is **off by default**. Enable it in `config.toml`:

```toml
[ambient]
enabled = true
```

Then check `rayu ambient status`, read recent activity with `log`, run one cycle
with `trigger`, or `stop` it. See [Ambient mode](#ambient-mode) below.

---

## `rayu permissions`

Review pending permission requests that ambient sessions raised with
`request_permission`. Approve, deny, or answer the question the agent asked.
Nothing else in v3 prompts for tool approval — see
[Permissions & safety](./23-permissions-and-plan-mode.md).

---

## Desktop and OS integration

| Command | Description |
|---------|-------------|
| `rayu companion [--status]` | Run the desktop companion for this login session: opens URLs and terminals, global voice, lid override. Options `--no-voice`, `--no-voice-waveform`, `--no-voice-notifications`, `--no-open`, `--no-spawn-terminal`, `--no-lid`, `--no-browser-updates`. |
| `rayu dictate [--type]` | Run configured dictation: send to the last focused rayu client, or `--type` raw text into the focused app. |
| `rayu transcript [TEXT] [--mode insert\|append\|replace\|send]` | Inject externally transcribed text into the active TUI. Reads stdin when `TEXT` is omitted. |
| `rayu setup-hotkey [--uninstall]` | Install the platform global hotkey that launches rayu. |
| `rayu setup-launcher` | Install platform launcher integration (Windows shortcut, macOS notification helper). |
| `rayu pair [--list]` | Generate a pairing code for the iOS/web client, or list paired devices. |
| `rayu menubar [--once] [--json]` | macOS menu bar indicator with running/streaming session counts. |
| `rayu browser [setup\|status\|detect] [BROWSER]` | Browser automation setup and status. Target `auto`, `firefox`, `chrome`, `chromium`, `edge`, `brave` or `safari`. |
| `rayu replay <SESSION>` | Replay a saved session in the TUI. `--swarm`, `--export`, `--speed`, `--timeline`, `--auto-edit`, `--video`, `--cols`, `--rows`, `--fps`, `--centered`/`--no-centered`. |

---

## Integration and diagnostics

| Command | Description |
|---------|-------------|
| `rayu serve [--server-name <NAME>]` | Start the agent server (background daemon). |
| `rayu connect` | Connect a client to a running server. |
| `rayu acp` | Run as an Agent Client Protocol adapter backed by the Rayu daemon. |
| `rayu api-bridge [--api-socket <PATH>] [--stdio]` | Serve the stable harness API on a Unix socket for the SDK (`@rayu-dev/rayucode-sdk`). |
| `rayu repl` | Simple REPL mode, no TUI. |
| `rayu self-dev [--build]` (alias `selfdev`) | Self-development mode: run as a canary session on the shared server. |
| `rayu debug [COMMAND] [ARG] [-S <SESSION>] [-s <SOCKET>] [--wait]` | Debug socket CLI. Requires `RAYU_DEBUG_CONTROL=1`, `display.debug_socket`, or a server started from a self-dev session. |

---

## Exit codes

| Code | Meaning |
|------|---------|
| `0` | Success. |
| `1` | Error: authentication failure, provider error, invalid arguments. |
| `2` | `rayu cloud wait` timeout (the remote turn keeps running). |

---

## Ambient mode

Ambient mode is a background agent that gardens memory, scouting recent work and
acting on small improvements while you are away. It is opt-in and runs at most
one cycle at a time; an interactive session always wins.

```toml
# ~/.rayu/config.toml
[ambient]
enabled = true
provider = "rayu"           # optional; defaults to auto-select
model = "deepseek-v4.1-flash-cloud"   # optional; defaults to the strongest
min_interval_minutes = 5
max_interval_minutes = 120
pause_on_active_session = true
proactive_work = true
work_branch_prefix = "ambient/"
visible = true
```

`allow_api_keys = false` by default: ambient prefers an OAuth session and will
not spend a pay-as-you-go key unless you opt in. When it does, `api_daily_budget`
caps the daily spend. Anything that leaves the sandbox or contacts another person
requires approval; those requests show up in `rayu permissions`.

---

## Next

Next: [Slash Commands →](./07-slash-commands.md)
