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.
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.. |
--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 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.
rayu run#
Run a single message and exit. This is the headless entry point.
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.
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:
{
"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.
rayu login#
Log in to a provider. In a Rayu-only build, rayu is the only provider.
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. |
rayu login # interactive picker
rayu login rayu # Rayu account
rayu login --provider rayu --no-browser
rayu account status # plan, credits, reset daterayu account#
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#
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#
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.
rayu provider add my-gateway \
--base-url https://llm.example.com/v1 \
-m qwen3-coder --api-key-env MY_GATEWAY_API_KEY --set-defaultOn a Rayu-only build this exits with:
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.
rayu usage#
Show usage limits for connected providers. With a Rayu account it prints plan credits as a bar plus remaining and used numbers.
rayu usage
rayu usage --jsonrayu version#
rayu version # human-readable
rayu version --json # version, semver, git hash/tag, build time, release flagrayu update#
rayu update # newest build on the current channel
rayu update --channel stable # persist the stable channel
rayu update --channel preview # opt into previewsDownloads the newest verified release, checks SHA256SUMS, swaps the binary
atomically, and reloads a running server without dropping sessions.
rayu telemetry#
rayu telemetry status | enable | disablestatus 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.
Server and sessions#
rayu server#
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#
rayu session rename <ID|NAME> [NAME] [--clear] [--json]Rename a saved session, or --clear its custom name.
rayu restart#
rayu restart save | restore | status | clearSnapshot the set of open rayu windows and restore them after a reboot (or
clear the snapshot).
rayu mcp#
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.
rayu telegram#
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 page.
rayu cloud#
Move live sessions to a cloud host over SSH, or manage Jade cloud-synced session storage.
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#
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 statsScope is project, global or all. See
Memory & project instructions.
rayu ambient#
rayu ambient status | log | trigger | stopAmbient mode is off by default. Enable it in config.toml:
[ambient]
enabled = trueThen check rayu ambient status, read recent activity with log, run one cycle
with trigger, or stop it. See 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.
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.
# ~/.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 = trueallow_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 →