CLI reference
Reference

CLI reference

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.

FlagDescription
-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-updateSkip the automatic update check for this run.
--auto-updateAuto-update when a newer build exists (default true for release builds).
--quietSuppress non-error CLI/status output for scripts and wrappers. Also RAYU_QUIET=1.
--traceLog tool inputs/outputs and token usage to stderr.
--socket <PATH>Custom server socket instead of the shared daemon socket.
--debug-socketEnable 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-selfdevDisable auto-detection of the rayucode repository and self-dev mode.
--onboarding-simRehearse real first-run onboarding as if rayu were new on this machine.
--update-simLaunch the TUI and autoplay a safe simulated update.
--licensesPrint the bundled software licenses and third-party notices.
-h, --helpShow help.
-V, --versionPrint the version line.

There is no --print / -p "prompt" flag in v3. -p is --provider. Non-interactive prompting is the run subcommand.

Tool exposure#

FlagDescription
--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-toolsHide 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.

text
rayu run [--json | --ndjson] <MESSAGE>
FlagDescription
--jsonEmit one JSON result object instead of streaming text.
--ndjsonEmit 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.


rayu login#

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

text
rayu login [OPTIONS] [PROVIDER]
FlagDescription
-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-urlPrint 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.
--jsonMachine-readable output for scripted logins.
--completeResume a pending scriptable flow that needs no callback or code.
--flow-id <ID>Isolate temporary login state (1–64 ASCII letters, digits, _, -).
--cancelCancel one provider's pending flow. Saved credentials are untouched.
--no-validateSave 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.
--setupRe-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
CommandDescription
loginOpen the Rayu browser sign-in and wait for the loopback redirect (--no-browser, --print-auth-url, --callback-url supported).
statusPrint email, name, plan, credits remaining/used, and reset date.
manageOpen the Rayu dashboard in your browser.
logoutSecurely 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
CommandDescription
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.


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.


Server and sessions#

rayu server#

text
rayu server start | promote | reload | stop
CommandDescription
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>
CommandDescription
listList 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#

text
rayu telegram link [--botfather] | uninstall | status | disconnect
CommandDescription
linkPair your Rayu account (or --botfather for a dedicated bot) with this daemon.
statusLink status for this Rayu profile.
disconnectDisconnect Telegram from this profile.
uninstallControl 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.

text
rayu cloud move | return | where | fork | send | status | wait | logs
rayu cloud problems | doctor | attach | env | sessions | replace
CommandDescription
moveMove a live session (transcript, repo state, env notes) to a cloud host and keep working there. Local files stay editable; git reconciles on return.
returnPull the cloud transcript back and merge its git work with a normal 3-way merge.
whereShow where moved sessions live and how repos have diverged.
forkFork 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.
statusWhether a cloud session is running, idle or failed, with recent messages and the run log.
waitBlock until a detached turn finishes. Exits 2 on timeout without cancelling the turn.
logsTail a cloud session's detached run log.
problemsRecent failed /cloud and /local attempts recorded on this machine.
doctorRead-only health check: SSH reachability, remote version, moved sessions, recent failures.
attachAttach this terminal to a session that lives on a cloud host.
envTransfer explicit project environment requirements without exposing values.
sessionsJade cloud storage: configure, status, upload, upload-latest, sync, list, verify, dashboard, view.
replaceReplace 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#

CommandDescription
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-testEnd-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.


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 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#

CommandDescription
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-launcherInstall 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#

CommandDescription
rayu serve [--server-name <NAME>]Start the agent server (background daemon).
rayu connectConnect a client to a running server.
rayu acpRun 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 replSimple 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#

CodeMeaning
0Success.
1Error: authentication failure, provider error, invalid arguments.
2rayu 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 →