docs commands
Command reference
1,834 слов · README.md
Install
Requires Bun ≥ 1.3.14 (the CLI entry is TypeScript, executed by bun — node cannot run it).
git clone https://github.com/9Code-Labs/rovecode.git && cd rovecode && bun install
bun run src/cli/main.ts --help # or: bun link → `rovecode` on PATH
bun run build:cli # optional: pre-bundle (TUI cold start ~230 ms → ~80 ms); re-run after git pull
# single binary (~110 MB: bun runtime + bundled deps + embedded native addons)
bun run build # scripts/build.ts → dist/rovecode(.exe) + smoke
dist/rovecode.exe --version
# from an npm tarball (npm pack) — global install shims to bun via the shebang
npm install -g ./rovecode-0.2.0.tgz
Not yet published to the npm registry (name availability unverified; no self-update — rebuild or reinstall to update).
Quickstart
rovecode connect # connect a model, step by step: pick a provider, paste the key (hidden), one
# test call
rovecode connect anthropic # the same in one line — see Providers for the flags (rovecode setup = the
# wizard)
rovecode # TUI chat — sextant on a colour TTY ≥ 100×30 (truecolor or 256), else the
# classic chat
rovecode --classic # force the classic chat; --plain = readline REPL; --pet <name> names the
# sextant pet
rovecode "fix the failing test" # one-shot task
rovecode run "<prompt>" --yolo # one-shot in auto mode (never asks)
rovecode --effort high # how hard the model thinks first: auto (default) | off | low | medium | high
# (/effort in the TUI, ROVECODE_EFFORT=…). auto sends no thinking field and
# leaves the endpoint's own default standing. Anthropic takes
# output_config.effort or a thinking budget depending on the model — rovecode
# learns which from the endpoint's own 400 and remembers it; OpenAI takes
# reasoning_effort. Billed as output tokens. `rovecode model show` prints what
# YOUR model receives per level (docs/thinking.md).
rovecode --accept-edits # middle tier: writes INSIDE this folder stop asking; shell, subagents,
/yolo --save # make it stick: the level is written to ~/.rovecode/settings.json and the
/accept-edits --save --project # next launch starts there. --project pins it to this checkout instead.
# Ladder: CLI flag > ROVECODE_PERMISSION > .rovecode/settings.json (project) >
# ~/.rovecode/settings.json (user) > ask. Without --save a toggle lasts one
# session. network and writes outside it still ask (/accept-edits ·
# ROVECODE_ACCEPT_EDITS=1 · or the `all edits` button on a write approval
# card)
rovecode run "<prompt>" --output json # ONE result object on stdout (ndjson: one line per RunEvent + a
# result line)
rovecode run "<prompt>" --max-seconds 300 --max-turns 40 # ceilings on one run: a hit ends it cleanly with
# status "budget" (exit 1) and the work so far, not
# an outside kill. A headless run already has a
# 20-minute clock (--max-seconds off removes it);
# ROVECODE_MAX_TURNS / ROVECODE_MAX_SECONDS set both
# on every surface, TUI included
rovecode run "/review src/x.ts" # a leading /name expands .rovecode/commands/<name>.md (a custom slash
# command) headlessly
rovecode gauntlet # adversarial eval suite (offline, deterministic, 10 tasks)
rovecode gauntlet --live # 9 of those tasks against the configured REAL model, through the real prompt
# (--model provider/model, --effort …): the before/after instrument for prompt
# work
rovecode bench # cross-harness micro-benchmarks
rovecode tools # registered tool listing
rovecode auth set <provider> # store an API key (prompted on the terminal, never echoed); auth list / auth
# remove
rovecode provider add <id> <url> # register any OpenAI-compatible or Anthropic endpoint — live, no
# restart; also provider list|test
rovecode model # pick from a numbered menu of every configured provider's models
rovecode models # just list them (* = current); alias for `model list`
rovecode model use <provider/model> # persist the default model directly (--project pins it to this repo)
rovecode model show # the model, its protocol, and the exact thinking field each --effort level
# sends
rovecode trace <session-id> # replay a session's JSONL tree
rovecode acp # Agent Client Protocol v1 over stdio (Zed/JetBrains)
rovecode serve # headless HTTP + SSE server (ROVECODE_PORT, loopback-only)
Without a provider configured, one-shot runs answer from a scripted mock (also how the packaging
smoke works), and the TUI opens with a card pointing at /setup. The quickest way to a real model is
rovecode connect (or /setup in the TUI). Give it a provider id and it stops asking — the whole
sitting becomes one line that fits in a README, a Dockerfile or a CI step:
rovecode connect # no arguments: the step-by-step wizard (rovecode setup)
rovecode connect anthropic # a built-in: key from the env, else one hidden prompt
rovecode connect anthropic --model claude-opus-5 # pin the model too
rovecode connect ollama --no-key # a local server: nothing to store
rovecode connect gw https://gw.corp/v1 --protocol anthropic --key --project # your own endpoint
echo "$KEY" | rovecode connect groq --key-stdin # scripts and CI: no terminal needed
rovecode connect gw https://gw.corp/v1 --key-env GW_TOKEN --no-test # register only, skip the test call
It registers the endpoint, stores the key, picks the model, makes one tiny real call and persists the
default. A key is never a flag value — that would sit in the shell history and in every ps listing
— so --key prompts (hidden), --key-stdin reads one piped line and --key-env NAME names an env var
to read at call time. Exit codes: 0 connected, 1 the test call failed (the config is still
written — rovecode provider test <id> retries it), 2 a usage error.
By hand, store a key once — built-in providers need nothing else:
rovecode auth set anthropic # prompts for ANTHROPIC_API_KEY — never echoed, never logged
rovecode auth set kaesra --key MY_PROXY_KEY # override the key name recorded for a provider
rovecode auth list # stored providers + key names, values redacted (first 4 chars)
rovecode auth remove anthropic
rovecode auth set openai < key.txt # piped stdin: reads one line, no prompt (scripts)
Any other OpenAI-compatible or Anthropic endpoint — a proxy, a gateway, a local server — is one line
away, and every change is live: a running TUI, rovecode serve or rovecode acp picks it up on the
next model call, no restart:
rovecode provider add myproxy https://llm.example.com/v1 --model gpt-5 --key # --key prompts (never echoed)
rovecode provider add ollama http://127.0.0.1:11434/v1 --no-key # local server, no key
rovecode provider add gw https://gw.corp/v1 --protocol anthropic --key-env GW_TOKEN --project # ./.rovecode
rovecode provider list # configured providers + the default provider/model (key SOURCES
# only)
rovecode provider test myproxy # one tiny real call: url + key + model
rovecode model list myproxy # ids from providers.json or the endpoint's /models
rovecode model use myproxy/gpt-5 # persist the default (running TUIs switch live)
In the TUI the same surface is /connect (bare: the guided cards, same as /setup; with an id: the
one-liner above, minus the key flags — there is no hidden prompt in there, so a missing key is handed
over to rovecode auth set <id> or /provider key <id> <secret> and the command finishes itself the
moment the key lands), /provider list|add|remove|use|test|key <id> <secret>, /models [provider] and /model <provider/model> [--save]; the agent itself has provider_list (read-only) and
provider_edit (add/remove/use — asks for approval, never accepts a key: the human stores it with
rovecode auth set <id> or /provider key, or names an env var with keyEnv).
Keys live in ~/.rovecode/credentials.json (ROVECODE_HOME overrides the directory). On POSIX the file is
written 0600 inside a 0700 directory. On Windows, mode bits are not enforced — the file is protected
by the NTFS ACL of your user profile (%USERPROFILE%, which ~/.rovecode inherits), not by permission
bits. Stored keys beat <NAME>_API_KEY env vars; an explicit ROVECODE_BASE_URL/ROVECODE_API_KEY pair
beats both. Endpoints live in providers.json (see Configuration → Providers) — never keys.
Or configure by env:
ROVECODE_BASE_URL=... ROVECODE_API_KEY=... # any OpenAI-compatible or Anthropic endpoint (always wins)
OPENAI_API_KEY=... / ANTHROPIC_API_KEY=... / DEEPSEEK_API_KEY=... / GROQ_API_KEY=... # named providers
ROVECODE_MODEL=zai-org/glm-5.3 # model id
ROVECODE_MODEL_DEFAULT=prov/a,prov/b # role fallback chains (DEFAULT SMOL PLAN COMMIT TASK); advance on
# 429/5xx
TUI slash commands: /help /setup /status /cost /model /effort /yolo /accept-edits /plan /act /rewind /tree /sessions /resume /new /checkpoints /restore /skills /memory /export /todos /tasks /attach /paste /mcp /exit,
plus one /name per custom command
file in .rovecode/commands/ (project) or ~/.rovecode/commands/ (user scope). The sextant surface adds its own
renderer-local /theme night|ember|contrast, /open <file>, /diff [file], /focus messages|code|files,
/agents and /notices (the notification history, also ⌃b) — they never reach the agent; the names are
reserved against custom commands.
Images: /attach <path> stages an image for your next message (text is still required, at most 8 per
message, ROVECODE_IMAGE_MAX_BYTES caps each), /paste (or ⌃v) takes the image on the clipboard, and
dragging an image file onto the terminal attaches it directly.
The sextant surface (wave 4, ports #40–#46 — ported from the user's own sextant v0.4.0 prototype):
a panelled cockpit instead of a chat log — files (git tree with M/A/D, touched-file spinner) · code
(the file the agent reads/edits with the highlight band, ± HEAD-vs-disk diff after an edit lands and the
approval preview before it, $ run output with PASS/FAIL chips, ∷ the crew board over background tasks)
· messages (compact tool rows · read x … N lines ~ edit x +a −b $ run cmd, the ONE modal card for
approvals and ask_user, the prompt with / suggestions and @file mentions) · plan (the session's
todos + crew) · usage (tokens, context bar, cost) · rovecode, the weather-cloud pet whose mood follows
the run. rovecode picks it when stdout is a TTY of at least 100×30 that renders truecolor (COLORTERM,
WT_SESSION, TERM_PROGRAM vscode/iTerm/WezTerm/ghostty, kitty/-direct TERM) or 256 colors (a
*-256color TERM with no COLORTERM, painted through the xterm-256 quantizer); ROVECODE_TUI=sextant|classic
overrides the heuristics (a non-TTY never gets sextant, nor does a TTY under the 40×12 floor), --classic
beats both. After an edit the code panel's diff is the ONE change that landed — captured before an
approved edit, rebuilt from the edit's own anchors after an ungated one — and falls back to a vs HEAD
view (every uncommitted change) only when neither is possible. Git runs beside the frame loop: a slow
git status never stalls the spinner or the keys. Keys: ⏎ send · tab
complete/cycle focus · esc esc stop the run · ⌃c quit (interrupts first) · ⌃k/⌃p palette · ⌃s code
(and focus it) · ⌃d diff (press again to go back to code) · ⌃r run output · ⌃a agents board · ⌃e files · ⌃o cycle the page tabs (code/files/plan, narrow terminals) · ⌃b
notifications · ⌃v paste a clipboard image · ⌃t theme · ⌃n new session · ⌃u clear the prompt ·
⌃←/⌃→ word jump · mouse: clicks everywhere (tabs, file rows, cards, a tool row opens its file, the header's unread badge, the footer's theme and effort words), wheel over any panel, scrollbar drag. rovecode smoke-tui --sextant renders a
160×44 frame through the real pipeline and prints PASS.