RuAgent CLI¶
Interactive and headless client for Ru's coding loop. It delegates runs to the Public Host over authenticated HTTP/SSE; model execution and policy remain Harness/Broker owned.
One active chat per terminal¶
/newreplaces the current idle session in the same window./sessionsopens saved history. Finish or cancel active/queued work before switching.- Saved sessions keep their recorded workspace and permission selection.
- Esc cancels current work or closes its panel.
/exitdrains pending acknowledgements, cancels runs started here and detaches adopted runs.
There are no concurrent session tabs or F6/Alt+N tab shortcuts. Session history
remains on disk. Provider/model selections stay pinned for admitted and queued
work. Native submissions require the matching Host's selected-run route; an
older Host reports provider_selection_unsupported without changing models.
Durable history and database maintenance¶
ru session list --limit 100 --query TEXT pages summaries; add --cursor TOKEN
to continue. ru session history SESSION_ID --limit 200 --json returns the
newest chronological message page and an older-page cursor. ru session search
TEXT --limit 50 searches retained messages. The existing agent session ...
spelling remains supported. Plain history output is a bounded preview; JSON
contains the complete returned page. Rewind uses absolute zero-based indices.
ru database status|backup|verify|restore|compact|prune uses the matching Backend
binary directly without starting a model run. See database maintenance
for bundle paths, the same-Windows-identity key constraint, offline operations
and explicit pruning. No automatic conversation deletion is enabled.
Transcript and command navigation¶
The welcome retains the animated galaxy, meteors and wordmark without an FX button or On/Low/Off modes. Tab stays in the composer for slash completion. Local command cancellation keeps the welcome visible; short results use the hint row and multiline results open a closable document.
Terminal.Gui is the default interactive surface on supported terminals. Ctrl+P opens a searchable palette backed by the same slash catalog as help and command completion. Enter selects a command into the composer; arguments can be completed before submission. Escape closes the palette and restores the draft. While a turn is busy, the palette can be browsed but selection is refused visibly.
Interactive transcript content reaches Terminal.Gui as semantic rows and styled runs: Markdown previews/commits, recovered replies, tool updates and notices do not round-trip through ANSI strings. The existing views retain their appearance, scrolling and code gutters. TextWriter/ANSI import remains for command reports and diagnostics; plain and JSON output retain their existing contracts.
Ru's terminal chrome uses a mint-accented signature, a quiet session divider and
a filled prompt surface in the panel tone — the opencode-style block, with no
frame outline and no accent rail. An empty chat centres the logo above the same
block. Its editor uses a steady vertical-bar caret instead of a block cursor,
without an application blink timer. The empty prompt is capped at 80 columns.
Active sessions use a padded
transcript and a full-width bottom prompt with the same side margins as chat; the
model, selected reasoning effort and provider sit on the meta row inside the block. The permission preset
appears in green beside the token cluster in the top header during chat; the
empty welcome screen hides it. The top workspace/path label is removed.
The reasoning label shows only its value, for example max or high.
The header's tokens and percentage describe the current request's prompt context,
using the pinned model's full window. A ~ marks a prepared estimate until provider
input usage arrives; the corrected value can decrease. Run billing totals and output
tokens do not enter this count. Unknown window capacity omits the percentage.
The welcome logo uses green/blue RU and muted green AGENT colors, with
a warm light sweep that visibly brightens the darker AGENT face. Terminals that
report Sixel or enabled Kitty graphics show square tiles, small rims and layered
shadows behind every letter. A solid black backdrop keeps galaxy dots and meteors
from showing through the logo. Other terminals and small windows use the glyph
logo. The welcome decoration disappears when chat starts.
The selected workspace remains available as a wrapped full path in /status.
Removing its header label does not change workspace selection, tool cwd or
permissions. The composer
grows from one to six visible input rows, leaving room for
the transcript on short screens. It shows “Ask anything…” when empty and uses
a steady block cursor. Enter sends; Ctrl+J, Shift+Enter where the terminal
distinguishes it, or a trailing backslash followed by Enter inserts a newline.
Up/Down move within a multiline draft before navigating history at its edges.
Text paste preserves line breaks and indentation and replaces selected text or
inserts at the cursor. A paste exceeding the 16,000-character draft budget is
refused visibly with the draft unchanged. The empty-chat footer shows
ctrl+p commands and pending attachment context; active-session hints adapt to
available width. The footer normally shows only Ctrl+P; while running it keeps
Esc visible. The busy colour wave uses five medium block cells (▬▬▬▬▬)
whose colours sweep aurora green, mint, brand blue, brand2 violet and warn
amber once every 0.8 s, so the row carries more than two hues at any phase
without reading as a slab. Other shortcuts remain available through help.
The header puts the session title (without a product-name prefix)
title/known usage on the first row and workspace on the second. Live activity
occupies a row at the end of the transcript. A colored glyph precedes the readable action; targets
are emphasized and elapsed/tool count align right. Waiting for the model, reported
thinking, response streaming, compaction and tool/request retries have distinct
labels. Idle omits status text, response deltas
show “Writing response”, and parked states have no spinner or running clock.
Tool rows align common action labels and targets, show actual terminal exit codes
when available, and keep every visible detail inline; Ctrl+O belongs to the
model's reasoning only. Failure remains
explicit when a long command is shortened; narrow rows prioritize outcome/exit
evidence over secondary metrics. Frames
shorter than 20 rows use a single heading row. The feed
uses the available width without a side panel. Picker cards page their entries
to fit the current height while keeping the selection and footer visible.
Slash suggestions span the composer width, with descriptions aligned in a
stable column above it. Model/session, approval, secret and report panels
centre on the terminal; the command palette uses the same centred placement.
Approval cards preserve choices and action hints on short screens. Closing a
modal restores the draft, cursor and composer focus.
Streaming defers reflow to drawing/scrolling rather than rebuilding a growing line for every fragment. Completed tool metadata updates its activity by ID; duplicate/late updates cannot turn into the next tool's result. Tool/diff cards are enabled for Terminal.Gui; plain output keeps the sequential tool rows.
Markdown block state advances only on complete raw lines. Terminal.Gui replaces
the unfinished line preview at up to 30 updates per second, then commits its
final formatting; retry removes provisional text. Fenced code retains its full
source line and wraps to the viewport instead of permanently clipping its tail.
Native streaming retains settled Markdown chunks and reparses the changing tail;
late closers can still restyle unresolved emphasis, code or links. Settled chunks
reuse native rows instead of being sanitized, styled and wrapped again for each delta.
Multiline native chunks batch completed rows into bounded UI updates while sending
the first commit immediately. Batches flush before previews and before the chunk
returns, preserving order with tool output and turn completion. This reduces UI
dispatch work for bursty output; it does not change provider generation speed.
Plain line output waits for newline or Flush before committing Markdown.
Markdown tables are grouped from retained raw header/separator/body rows, align
their columns (numeric columns right-align even without a : marker, :---:
centres) and switch to labeled values below 40 cells. A failed tool row adds one
└ <reason> line from its typed failure code or the event's safe summary. Reasoning remains behind Ctrl+O
without adding a Thought row for every model step. Web activity targets use
redacted query detail and host names; URLs do not expose credentials, query
parameters or fragments.
PageUp/PageDown scroll the transcript. Ctrl+Home reads the oldest retained output; Ctrl+End returns to following new output. Streaming preserves a detached scroll position and marks new output until Ctrl+End returns to the tail. Ctrl+O toggles the model's reasoning block, defaulting to the newest retained reasoning. Ctrl+Alt+Up/Down select and reveal earlier/later reasoning blocks. Ctrl+Shift+C copies the selected reasoning block's retained text, or the latest contiguous assistant text when no block is selected; copied content includes any retained formatting or code gutters. Ctrl+End clears block selection and resumes following output. Running, waiting for approval and paused states show the queued prompt count; submission refusals are feedback and do not start a running indicator. The visible history retains at most 2,000 rows and 200,000 Unicode characters, with 16,000 UTF-16 units per line, including collapsed content; a notice marks discarded history. These are rendering limits and do not alter durable model context. Long native assistant paragraphs use multiple bounded storage segments after Markdown styling and tab expansion; copy joins those segments without adding newlines, and display reflow continues across storage boundaries. Quote/list indentation and double-space layout keep their original whole-row wrapping. Provisional segments are replaced together, so preview growth and final commit do not duplicate text.
Project context and run continuity¶
Opening fresh chat or using local commands such as /model, /provider, /status
and /help does not create a saved session. A session is created on the first real
message or explicit /new; /sessions can select an existing one. Local native
commands do not appear as user-message cards or show model-working status. Until
then status displays not started, and session-specific inspections ask you to
send a message or select a session first.
The TUI focuses on chat and coding, with inline tool activity and expandable
errors/diffs, approvals, attachments, session/model controls and run recovery.
The header keeps the live context meter. The agent's Todos list updates beside the
transcript and collapses to a progress button when the terminal is narrow or the
list is complete. Click the heading or press Ctrl+T for the full list. Plain output
prints the checklist and later progress inline. Drop a known file path or use Ctrl+V to add it to
the composer. Up/Down still recalls previous prompts. /exit is the only quit
command; Escape closes an overlay or interrupts an active turn and never exits
the chat. An idle Escape preserves the draft.
The interactive vocabulary omits /delete, /resume, /retry, /release, /clear, /activity, /todos, /files,
/tree, /export, /stats, /tokens, /changes, /history, /rewind, /attach,
/attachments, /paste, /detach, /continue, /follow and /quit. Headless CLI
and RPC commands, including native session fork and rewind, remain available separately.
Continue reopens only a run already tracked by the current session that is still
running or waiting on an approval or a question, using its durable provider/model
metadata. Without one it is an ordinary prompt. Runs never park for a Continue: a run
that stops ends with its error, and a new message starts a fresh run. Unknown pins
show unknown and suppress catalog-based cost/context estimates. Pending approval
recovery reads a bounded tail of durable events, then rechecks the run version
before posting an explicit decision. Another client may resolve the approval first.
After a rejected submission, queued turns stay ordered and paused; exit and reopen the session before submitting fresh work. Model/backend/key/reasoning repair commands and help/status remain available; they leave draft attachments intact. Settings are checked again before a queued run is created. The Host pins provider selection at the first successful model bootstrap; a client preflight is not an atomic lock on global settings.
Commands¶
agent chat [--preset plan|standard|full_access] [--workspace PATH] [--session <id>] [--image PATH]... [--json] [--classic] [--trust-workspace] [--confirm-full-access]
agent session list [--json]
agent session rewind <session-id> --index <n> [--json]
agent session delete <session-id> [--yes]
agent run [--preset plan|standard|full_access] --workspace PATH "prompt" [--session <id>] [--image PATH]... [--json] [--trust-workspace] [--confirm-full-access]
agent attach <run-id> [--json]
agent trust <run-id> --approve|--deny
agent approve <run-id> <approval-id>
agent deny <run-id> <approval-id>
agent answer <run-id> <input-id> [answer] [--json]
agent cancel <run-id>
agent command <run-id> "<slash-command>" [--json]
agent reconcile <run-id> [--outcome applied|not-applied|unknown] [--hash SHA256] [--json]
agent output <run-id> <payload-id> [--json]
agent status <run-id> [--json]
agent policy list [--global | --workspace PATH] [--json]
agent policy import --global FILE
agent policy remove <rule-id>
agent rpc
--jsonis the non-interactive NDJSON rendering, so it is only accepted together with--trust-workspaceor--confirm-full-access: a scripted run cannot take, by omission, the authority those flags exist to confirm. Without one of them the parser refuses withjson_requires_explicit_flags. The transcript renderer is muted in this mode, so stdout carries durable/transient NDJSON frames only; every human line goes to stderr.chat(orrepl) uses Terminal.Gui for interactive streaming, tool/diff rows, approvals, command history and slash completion./newcreates a session;/sessions [query]searches a bounded list;/sessions id:<session-id>switches explicitly and preserves the current session on failure. Reopening a session redraws the turns of its newest 200 messages from their activity records, as they looked live, and discovers retained running, approval and question runs. TypingContinuereopens a tracked running/input/approval run;/followis removed. Useru agent attach <run-id>from another terminal for an explicit run target, andru agent cancel <run-id>outside chat to abandon a run. Native session switching restores the recorded workspace. The line/JSON adapter keeps the operator-selected workspace and warns when retained history belongs elsewhere; reopen with--workspace PATH --session IDto select that root explicitly.- Request skills in ordinary chat prompts, for example
Use the review skill to inspect this change./skillsand/skillare removed from terminal chat handling, suggestions and help. Skill discovery and model-side loading retain their existing invocation policy. - While a turn streams, Enter queues up to eight immutable submissions. Each owns the prompt, session/workspace/preset/model intent, attachment contents and idempotency key captured at admission. The queue retains at most 32 MiB of estimated UTF-16 content; a composed prompt is capped at 16,000 UTF-16 units. Refusal leaves the draft and attachments intact. State-changing commands are refused while busy or queued. Rejected submissions are never automatically resubmitted; queued work remains paused until the chat is closed or an existing explicit run continuation settles it. Escape/Ctrl+C interrupts through the existing run-cancel endpoint; pending tool approval takes over the composer with explicit approve/deny choices.
- All
agent chatinput uses oneChatSessionEnginefor admission, queues, turn cancellation and the latest 100 prompt submissions. Terminal.Gui is its only interactive screen adapter. Windows uses the .NET console driver to preserve emoji across split input packets. Bracketed paste targets the active command palette, secret prompt or composer without changing a hidden draft.--classicretains append-only text with line input between turns; the same adapter serves redirected stdin/stdout,--json, anyNO_COLOR,TERM=dumband startup terminals below 80×24. It writes directly without a second transcript buffer, cursor positioning, screen clearing, resize rebuild, arrow-key picker or framed composer. Bare picker commands show options; select with an explicit argument. A trailing backslash continues the prompt on the next line; ordinary prompt quotes are preserved. Native resize stays native and never starts a separate text chat loop. - Attachments travel with the next turn. Images:
--image PATH(repeatable, max 4), a dropped path, orCtrl+V(clipboard file drop, a screenshot via DIB → temp PNG, a text path, and plain-text paste when no image is present). Images are validated, resized (longest side 2048,>4MBre-encoded, BMP/GIF normalised to JPEG, PNG alpha kept, EXIF orientation applied; WebP passes through only when its header proves it fits) and capped exactly like the GUI: 10MB read, 4MB decoded per image, 20MB per turn, 5.6M-char data URL. Text/code files (5MB) inline as fenced blocks ahead of the prompt; a composed prompt over 16k chars is refused before the run is POSTed. The composer shows the pending attachment summary; the list clears when the run owns it and a declined workspace-trust challenge restores it intact. Temp clipboard files (%TEMP%\ru-img-*) are deleted on send or chat exit. A vision-name pre-check only warns; the backend remains the source of truth and sends an explicit unavailable-image notice to text-only models while keeping the chat and stored attachments. - Office documents (
.docx,.xlsx,.pptx) are unsupported as attachments. Keep them in the workspace and ask Ru to process them through installed terminal tools or optional skills. Ru does not bundle an Office converter or authoring suite; tool permissions still apply. - The pinned header shows the usage cluster (
39,413 20% ($0.29)) when context/rate metadata is available. Its percentage tracks the largest request input seen this turn, and its running cost uses input/output rates for the currently open chat./status contextshows the latest request reading;/status usageprovides cache-aware accounting over a clearly labelled recent-run scope. Neither is an all-time invoice. - The backend
chat/runstart is a managed host shared by CLI, GUI and RPC: it stops itself after 10 minutes with no request in flight, no recent request and no registered run (RU_HOST_IDLE_MINUTES, default10,0disables), so exiting the terminal no longer leaves a detached backend running. The next command starts it again automatically; a run still in progress (even parked) keeps it alive. - An untrusted workspace requires an explicit trust decision before execution. Terminal.Gui shows trust/cancel in the composer with cancel selected by default; Enter or Escape never grants access implicitly. Declining cancels the run, so it stops holding its session. Trust is scoped to the canonical workspace identity; moved or recreated roots require a new decision. Redirected/JSON output reports
workspace_trust_required; resolve it explicitly withru agent trust <run> --approveor--deny. - A trust challenge expires after 24 hours (the approval lifetime), and the host now notices while it is running rather than only at the next startup: the runtime loop cancels the expired run with
terminal_error_code = workspace_trust_expiredand frees the session. Trust is a pre-execution gate, so cancelling cannot roll back a tool side effect. Previously only the startup sweep could do this, so a long-lived desktop host left the run — and its session — parked indefinitely. - A turn that completes with no assistant text and no tool row says so:
▲ no text arrived from the model · the run completed but its reply never reached this terminal · retry, or switch model with /model. Reply text is persisted even when its delta never reaches this client, so a finished run that delivered nothing used to end in total silence — just a✓ idle · 10.6srow, which reads exactly like a very short answer. The note is deliberately withheld when the turn did stream text or did run tools, because there the operator can already see what happened. This reports the observation; it does not recover the missing text. - Assistant text arrives only on transient frames, and the live event hub keeps no replay buffer: a frame published before the client subscribes is dropped. So every finished turn is reconciled against the run's own durable
assistanttext/utf8textpayload, and a missing tail is reprinted. Payload kind controls filtering, so JSON answers withtool_callsandfinish_reasonkeys remain valid prose. A missing head cannot be repaired — a terminal cannot unprint, and appending the head after the tail would interleave into a mangled sentence — so the turn reportsassistant_text_truncated: N/M characters reached this terminaland points at the session, which always holds the whole reply. - A model's own deliberation never enters the transcript: the classic renderer leaves one
· thought · ctrl+orow and keeps the text behindctrl+o; the Terminal.Gui transcript keeps the text behindctrl+owithout adding a row, matching the WinUI surface, where the thinking block is closed by default. - Assistant prose is rendered, not printed: fenced code becomes verbatim rows behind a
│gutter, inline emphasis and links render in place (CommonMark, via Markdig), and headings, bullets, ordered items, quotes and rules lose their markers. The inline markers are:
**bold** *italic* `code` ~~struck~~ [label](https://example.com) \*escaped\*
Tables render as aligned columns (numeric columns right-align); nested lists fall back to indented text. Consecutive prose lines are reflowed into one paragraph, and a blank line or any other block form ends it — a model that hard-wraps at 80 columns no longer leaves a ragged column in a wider terminal. Because a streamed delta can cut a marker in half, only the trailing run of marker characters is held back for the next delta — so the text always arrives complete and in order, even when an emphasis spanning a delta boundary loses its styling.
- Tool rows read as a sentence: provider names are nouns (View, Terminal), so a table of verbs turns them into read, listed, searched, edited, wrote, ran, loaded and so on. The feed groups them: consecutive settled calls share a two-cell indent and close with a summary row (4 tools · 9.6s, prefixed ✗ when one failed), each row orders outcome glyph, muted name, brightest target and right-aligned metrics with a unit that follows the tool (132 lines, 3 matches, +18 −2, 1.2s), and the live row uses the same geometry so it settles in place. The summary trails the block because a terminal can only append; nothing is inserted above rows already printed. The live row uses the present tense (⠋ reading app.cs) and the settled row the past (✓ read app.cs). An unrecognised name keeps its own name, and a provider's name outranks the activity kind so precision is not lost.
- /help lists every command grouped by area. Native /status opens Overview / Context / Session usage; Overview keeps the session card (session id, preset, backend, model, API-key state, turns, tools, tokens and workspace). /status overview, /status context and /status usage open a section directly. Line/JSON /status keeps the overview default.
- Context distinguishes the latest provider prompt count from the estimated System prompt / Tool definitions / Messages breakdown. It shows the retained model's published context window and output reserve, plus a separate unsent draft/image estimate. No request yet, missing fields or a compaction without a newer report remain unknown. The next-turn model selection never supplies a retained run's limit.
- Session usage covers at most eight recent listed runs: uncached input, output, cache read/write, weighted cache hit rate, billed tokens, largest step and estimated cost, with per-run rows and coverage. Cached input is counted once. Missing reports, accounting or rates remain unknown; cost uses each run's recorded provider/model and current catalog rates. Other sessions are excluded, and a bounded history tail is labelled rather than presented as lifetime usage. Reads happen only when opening a report, never on typing or repaint. Esc closes it and pending attachments stay with the draft.
- Reports follow the existing submission queue and show a snapshot when the command executes. Reopen a section for fresh data; opening a report does not interrupt a running model turn.
- /model without an argument lists the live provider catalog for the active backend (current model first, then free models, then the rest A–Z, then dimmed unsupported rows; the footer names the backend and the row count as backend · N rows), falling back to configured models when the catalog is unreachable with a dim catalog unavailable (<reason>) - showing configured models line, the same reasoning /backend prints; pick with ↑↓/digits/Enter, Esc cancels. Free-tier models carry a free tag (OpenRouter :free suffix) and long ids keep both ends so shared prefixes stay apart. Dropdown label columns size to the longest label on wide terminals (narrow screens clip with …); short lists keep the classic 12-cell column.
- /model and /backend without an argument open a picker (↑↓, digits, Enter, Esc); choosing one updates the settings immediately. /backend openrouter and /model <id> also work with explicit arguments. Esc closes an opened picker without printing its options into chat or changing settings; /reasoning follows the same rule. The line adapter lists options when no picker is wired. Cancelling a native picker never enables that text fallback, even when the process console is redirected.
- Starting chat or run against a models.dev:* backend makes one best-effort catalog check. A model id the live catalog does not list prints one bounded model_not_in_catalog: <id> - it may fail with a 404; choose another with /model notice; an unreadable catalog prints model_check_unavailable: <reason>. The run continues either way — the catalog can be stale — and OpenAI, Anthropic and custom backends, whose id spaces are not catalog-bound, are not checked.
- /provider reads the live provider catalog (GET /models-dev), with built-in and fallback choices when the catalog is unavailable. Choose a provider first, then enter its API key in the separate masked box. /provider <name> opens the key box directly.
- The native provider picker shows its catalog notice in the footer. Opening, filtering and cancelling the picker leave the welcome screen in place.
- Every picker can be filtered by typing: letters and the id separators - _ . narrow the rows by substring across label, detail and value, Backspace drops one character, and the footer reports filter: <query> · <matched>/<total>. Digits stay the numbered-pick shortcut, and with an empty filter every picker behaves exactly as before. A query that matches nothing shows one disabled no match row instead of an empty list.
- /reasoning shows or sets the active model's reasoning effort from the live catalog. Bare /reasoning opens a picker of default plus the levels that model actually publishes, or explains that the model offers none; /reasoning <effort> writes it directly and, like /backend, needs no terminal. The save is POST /settings carrying exactly reasoning_effort, reasoning_model and reasoning_identity — the identity is the catalog snapshot the picker drew, so a save can never land on a different selection. default is always accepted, because the host only resolves a non-default effort against the catalog.
- /advisor chooses the model the agent may consult (ADR 0047). Bare /advisor opens a provider picker (with an off row) and then that provider's model catalog; /advisor <model> uses the active provider, /advisor <provider> <model> names one, and /advisor off clears it. The save is POST /settings carrying exactly advisor_backend and advisor_model (two nulls for off). It applies to new runs; JSON refuses the bare picker form with interactive_required. The agent then consults it through the advisor tool when it chooses; you can also name a model or effort in your request ("ask the advisor claude-opus-5-5 with high effort").
- Provider setup saves the selected provider and key together through one POST /settings only after confirmation. Ctrl+V pastes the key into the masked box; Escape cancels without changing either. An empty entry keeps a known saved key; otherwise it saves nothing, except for custom endpoints where a key is optional. Keys use existing credential storage and never enter the transcript or command history. /provider remove <name> signs out. JSON refuses interactive key entry; without a picker the sequential path lists providers. Legacy /backend and /key commands remain callable but are hidden from help/completion. /model continues to select the model; /provider no longer aliases it. Saving a key does not verify it with the provider.
- Scrollback uses PageUp/PageDown, Ctrl+Up/Down for individual rows, Ctrl+Home/End for top/tail, and the mouse wheel. The scrollback hint stays visible while a model turn runs; Session replay resets it with the transcript. Retention limits and queued-submission ownership remain the existing ones.
- A workspace-busy rejection names the blocking run in a persistent hint with ru agent cancel <run-id>. Typing and failed submissions do not dismiss it; an accepted run or successful session switch does. Transcript diagnostics also retain the blocking run and attach/cancel advice.
- Explicit OpenAI HTTP 429 quota codes (including insufficient quota and exhausted credits/spend limits) report provider_quota_exhausted and end the run without automatic retries. Restore provider credits or limits, then send a new message; a zero remaining-request header alone remains ordinary throttling.
- Provider HTTP 402 and Responses streamed payment errors report provider_payment_required without transient retries. The remedy names provider billing/credit instead of assuming a bad key or model. Provider/model selection stays pinned for the run.
- Terminal.Gui relayouts and redraws after screen-size changes. Startup selection remains 80×24; an already active frame stays available while resizing and hands control to append-only output only after remaining below 20×12 for 400 ms. Transcript bounds and detached scrolling survive layout changes. RU_TUI_DEBUG=1 writes diagnostic events to %TEMP%\ru-tui-debug.log; a file path selects another diagnostic destination. Native terminal resize and IME acceptance are recorded separately from headless tests.
- session list, session rewind and session delete provide explicit command-line controls for listing sessions, time-travel rewinds, and deletion. session delete <session-id> asks for a y/N confirmation (default No) and only --yes skips it; a partial cleanup from the backend (Session đã xoá nhưng artifacts còn sót…) surfaces as session_delete_failed bounded to one line instead of reading as success.
- rpc runs the stdio JSON-RPC 2.0 bridge for external tools (ru agent rpc takes no further arguments); it reuses the same loopback host and bearer as every other command and adds no HTTP route. See the RPC bridge contract.
- run creates a single-shot Agent run. If --session is omitted, the tracer creates one dedicated session via POST /sessions/new, prints session_id and run_id, and sends a fresh idempotency_key (32-char hex GUID). Workspace is canonicalized and bounded to 512 chars; prompt is bounded to 16,000 characters; max argument count is 64.
- --preset selects one canonical, session-scoped profile: plan is read-only — workspace read/Web auto, terminal/mutation denied outright, external structured access asks; standard auto-allows workspace mutation and executable/shell launches from a workspace cwd; external structured paths and external launch directories ask; full_access (alias full) is the skip-all mode — external structured files, arbitrary terminal, and structured protected paths (harness key/database files and runtime descriptors) are automatic, while hard-invalid requests remain denied. Repository cleanliness is not an input.
- Workspace trust is explicit once per canonical identity. --trust-workspace approves the returned identity and continues the same run; without it, an untrusted identity returns workspace_trust_required without prompting, and the notice names both recovery options. A moved or recreated identity requires trust again: --trust-workspace re-approves the new identity in one step, so unattended runs recover the same way.
- --preset full_access requires --confirm-full-access; without it the command returns full_access_confirmation_required before session creation or preset mutation. With it, the existing policy route receives X-Interactive-Confirmed: true. Terminal children run as the current Windows user, can access data outside the workspace and network resources, and have no OS filesystem/network confinement; timeout, output, cancellation, and process-tree controls remain.
- Inside Ru, /preset opens a picker, and /preset plan or /preset standard selects directly. /preset full_access requires a separate confirmation that defaults to keeping the current preset. The choice applies to the next new turn through the same policy update/rollback path; running, queued or retained runs cannot have their permission intent changed in place. The top header and /status show the selected next-turn preset.
- Choose Remembered rules inside /preset (or enter /preset rules) to view saved global and current-workspace rules. Inspect a rule's matcher and scope before removing a saved Allow rule; a separate confirmation defaults to keeping it, and Esc cancels. Ask/Deny rules are read-only here. This does not change the preset or clear other grants or existing run snapshots. If the Host cannot identify the current workspace from saved session metadata, project rules are explicitly unavailable; global rules remain visible. Line/JSON mode lists rules without offering deletion.
- Preset updates retry expected versions 0..3 and bind the positive returned version to the run. The CLI creates a durable snapshot token before mutation; the Host persists prior/applied selection and token atomically, enforces capacity without evicting active snapshots, and restores with CAS/single-use semantics. A malformed or lost mutation response uses the known token for safe restore; a lost restore response can replay only while the restored state still matches, otherwise the command fails closed before streaming. Failed creation or trust handling restores the exact prior selection, including a new session with no prior selection.
- --json is accepted with explicit --trust-workspace and, for Full Access, explicit --confirm-full-access; it never auto-approves an approval or workspace.
- attach streams an existing run's durable events from after_sequence=0 via AgentSseClient.
- trust wraps POST /agent/v1/runs/{runId}/trust.
- approve and deny wrap POST /agent/v1/runs/{runId}/approvals/{approvalId} with allow_once, allow_session_directory (external folders only), allow_always (authorizes once and remembers a bounded pattern as a durable project rule — a terminal command prefix, or an approved external folder as a path pattern; rule_asks and terminal_protected_path_requires_approval save no rule and degrade to allow_once), or deny. The Host sends the command that matches the pending kind (session-scoped directory grant for external_directory_required, ephemeral token for terminal_external_cwd_requires_approval, terminal_protected_path_requires_approval, or rule_asks). An allow of a rememberable call also remembers the approved intent in the Host's in-process session ledger (the durable pattern when one was saved, the exact intent otherwise), so a later matching call in the same session authorizes without another prompt (the memory dies with the session or a host restart; external-directory approvals keep the session grant plus the durable rule and write no ledger entry). The interactive approval offers the session folder and the project remember for external_directory_required. terminal_timeout_requires_approval remains the standard-window gate below full_access and web_approval_required remains a compatibility reason for explicit ask rules; timeout above the protocol hard maximum is denied. agent approve --always sends allow_always; no reusable approval token is ever created. Approval is first-writer wins; second concurrent response returns approval_stale (409). approve and deny accept --json: approval is answered explicitly by id, so --json only selects the output format (a versioned approval object with decision, scope, authorized and the matcher preview when the Host returns one). agent run --json prints the pending approval_id on its approval.requested event, which is the handle a headless orchestrator passes back to agent approve/deny.
- answer wraps POST /agent/v1/runs/{runId}/inputs/{inputId} with the user's answer to an ask_user question (1..8192 characters). Without the answer argument it prompts; --json requires the argument because it must never prompt, and prints a versioned envelope carrying run_state. A replayed, foreign, or already-answered input id returns input_stale (409), an unknown run run_not_found (404), and an invalid body invalid_answer (400).
Interactive Terminal.Gui chat opens ask_user questions inside Ru. Use Up/Down,
Tab/Shift+Tab or a click to choose an editable suggestion. The numbered Other row
restores your own draft. In multiline drafts, the arrows move the caret within the
text and select another option at the edge. Enter sends and Ctrl+J/Shift+Enter adds a
newline. Long questions and options wrap, and PageUp/PageDown or the mouse wheel
scrolls them. Free text and text paste also work for questions without suggestions.
Escape closes the question without answering
or cancelling the run and pauses queued prompts. Continue reopens the
pending question, including after reopening its session. Answers use the existing
run/input endpoint and never create a new prompt or change the run's model/preset.
Stale or uncertain submissions stop for explicit Continue recovery instead of
retrying automatically. Line and JSON chat keep the external agent answer
flow; JSON never opens an input panel.
/tasks opens the session's background terminal task list, including while a model
turn streams. Rows show the process label, execution ID, state and available exit
code. Select a running row, choose Stop task (the default is Keep running),
and refresh to observe its final state. Finished rows have no stop action. Refresh
reloads on demand; there is no background polling. Escape closes the current panel.
/tasks kill <execution-id> targets one task directly with the same interactive
confirmation; /tasks <run-id> selects a run in the current session, useful after
reopening a session. With no retained target, Ru discovers the newest session run.
Missing Broker/gateway state is reported as unavailable, not an empty task list.
The task control lane preserves pending attachments and the active model run/queue.
While task control is open, finish it before submitting another command or prompt.
Line/JSON chat lists tasks as text/JSON; an explicit kill argument sends the
stop without reading stdin. All operations use the existing Host command endpoint
and Broker session registry; the CLI never kills local process IDs itself.
The chat surface omits /changes, /history and the legacy /rewind alias.
They are rejected before attachment admission or command dispatch. Saved-session
browsing and replay remain under /sessions; Up/Down still recalls typed prompts.
The separate headless session history/fork/rewind operations remain available.
policy listwrapsGET /agent/v1/policies(scope filter).policy import --global FILEvalidates versioned JSON (rejects unknown version/fields, normalizes and displays matchers/decision before confirmation) and posts each rule withX-Interactive-Confirmed: true; sensitive matcher values are encrypted at rest via Host API.--jsoncannot bypass confirmation.policy removewrapsDELETE /agent/v1/policies/{ruleId}and requires interactive confirmation for global rules.cancel/statusare thin HTTP wrappers.agent continuewas removed and answerscontinue_removed.runandattachreturn exit 2 at a durable park an older build recorded (waiting_userorreconciliation_required); startup recovery fails such a run, andru agent cancel <run-id>releases it. Historical park events from a resumed run do not detach the follower. Under--json, stdout remains NDJSON and human recovery guidance goes to stderr.commandforwards/compact normal|aggressive,/help,/skills,/skill <name>, or/tasks [kill <execution_id>]throughAgentApiClient.DispatchCommandAsync. Slash parsing is shared with the Public Host; malformed or unknown commands return stablecommand_invalid/command_unknowncodes and are never sent as prompts. Human output prints only bounded metadata;--jsonemits the versioned response envelope without raw tool output.reconcilewrapsPOST /agent/v1/runs/{runId}/reconcile. Without--outcomeit fetches the run (showing theintent_codeand a freshsnapshot_hash), prompts forapplied|not-applied|unknown, then posts the decision with the freshly read hash.--outcome applied|not-applied|unknownmaps to wire tokensapplied/not_applied/unknown_continue.--hashmust be a 64-char hex SHA-256; a stale--hashreturnsreconcile_staleand exits non-zero.--jsonnever prompts: it prints the info payload and exits without sending a decision; an--outcomegiven without--hashin--jsonmode fails locally (exit 1) and sends no request.outputwrapsGET /agent/v1/runs/{runId}/payloads/{payloadId}— the explicit user action that fetches final head/tail tool output bytes. Nothing in the tracer fetches private payloads implicitly; the event stream only references payloads by opaquepayload_ref. The command prints the payload'scontentfield just as the host returned it: UTF-8 text forutf8text/jsonpayloads, and the base64 wire form foropaquepayloads (it does not decode them);--jsonis accepted for symmetry with the other commands but adds no envelope, because the payload is already the answer.
Current model tool surface¶
The Agent model-step advertisement selects Protocol definitions from its pinned
coding_v3 (default) or coding_v2 profile. See the
current tool inventory
for explicit file, Windows terminal, Web, question and orchestration tools.
A provider-native model step may return
optional narration and one or more ordered calls; the compatibility text path
still emits exactly one JSON selection. The shared budget is 256 tool calls per
window, read-only concurrency is capped at eight, and mutation/terminal calls
remain sequential. Durable approval resume re-evaluates retained proposals
without a new model proposal, and an ask_user park resumes the same way once
ru agent answer completes the asked call.
The canonical tool policy
owns preset decisions, explicit-rule precedence and session/project approval scope.
Terminal children run as the current Windows user without an OS filesystem or
network sandbox. Timeout, output, cancellation and process-tree bounds remain.
Time, machine status, app discovery,
and optional volume commands use the terminal; notes use write_file.
apply_patch is available in the patch and programmatic profiles; app.open
is not model-usable. Managed
Web results are bounded and marked untrusted. Workspace SKILL.md bodies are
prompt guidance only and grant nothing; a requires: python frontmatter entry
fails the model's skill load closed with python_unavailable when Python is
not on PATH. LSP, extensions, plugin management
and MCP are not part of this CLI surface; plugins enabled in the desktop app still
apply to CLI runs through the Host. All commands ensure the Public Host
is running through PublicHostStarter.GetOrStartAsync and authenticated
PublicHostSession.
Rendering¶
- Interactive (
SafeEventRenderer): displays only safe envelope fields (protocol_version,event_id,run_id,session_id,sequence,event_type,occurred_at,status,safe_summary,payload_ref). Never fetches private payloads;payload_refis shown opaque. - JSON (
NdjsonEventRendererwith--json): versioned NDJSON{"v":1,"type":"event",...safe fields}. Never prompts, never auto-approves, never auto-fetches private payload, and never emitsprompt/command/argv/path/code/diff/output/secret/stdout/stderr/environmentfields. Full Access is accepted only with explicit--confirm-full-access;--trust-workspaceis the explicit non-interactive trust confirmation and is allowed with--json, while approval and global-policy confirmations remain rejected with--json. Under--json, slash-command surfaces write their human text to stderr, bare picker commands refuse with a boundedinteractive_required, and a chat run that reaches an approval request ends the chat (exit 0) with a boundedapproval_requirednotice on stderr namingru agent approve <run-id> <approval-id>orru agent deny <run-id> <approval-id>— the run stays waiting server-side and is never auto-denied; anask_userpark ends it the same way with aninput_requirednotice namingru agent answer <run-id> <input-id> "<answer>". A--jsonchat stream may include blank separator lines between turns, so consumers should skip empty lines. A transient frame's rawdatais therefore withheld and reported asdata_bytes— its bounded size, not its text — so the machine-readable trace never carries streamed assistant text or tool output. - Live terminal frames: transient
tool.output.deltaframes render as[transient:<seq>] <type> <preview>with the preview bounded to 200 chars; any forbidden field (command/output/secret/...) is replaced with[redacted]. Terminal output redaction also seeds from every nonempty secret environment value stripped before child launch, including provider API keys; child processes do not inherit those values. Atransient.frames_droppedevent renders an explicitWARNING dropped-framesnotice. Final tool output is referenced only by opaquepayload_ref; the actual head/tail bytes are fetched solely by the explicitagent outputcommand.
Cancellation¶
Interrupting a chat turn is server-side, not just a local detach: Escape during an active turn, after an open overlay handles the key, and Ctrl+C cancel the turn and POST /agent/v1/runs/{runId}/cancel (best-effort), so the run releases its session. Idle Escape never exits the chat or discards the draft. Success prints Run interrupted by user · cancelled <run-id>.; a failed cancel prints run_cancel_failed plus the manual ru agent cancel <run-id> fallback; a run waiting on an approval or a question is left waiting instead of being cancelled. Ctrl+C also cancels the SSE stream and POSTs /agent/v1/runs/{runId}/cancel before exit for attach/run. Under --json there is no footer to prompt in: an approval request ends the chat (exit 0) with the bounded approval_required notice instead, and the run stays waiting_approval server-side until ru agent approve/deny answers it from another terminal.
Bounds¶
- Running terminal tasks: default 8 per session, configurable from 1–64 with
RU_MAX_BACKGROUND_TERMINAL_TASKSbefore Host startup. Foreground launches reserve a slot and keep it on background promotion; a full session refuses new launches without stopping existing tasks. - Max arguments: 64
- Workspace path: 1..512
- Prompt: 1..16,000 (the composed prompt with inlined attachments uses the same bound)
- Image attachments: max 4, 10MB per file, 4MB decoded each, 20MB per turn, png/jpeg/webp/bmp
- Text/code attachments: 5MB per file; Office/binary documents are unsupported
- Session id: 1..64 (alphanum,
_,-) - Run id:
run_+ 32 lower hex (36 total) - Approval id:
apr_+ 32 lower hex - Rule id:
rule_+ 32 lower hex - Policy file: max 1 MiB, version 1 only, max 64 rules
- Error text: one-shot failures print
code: message(server message, max 200 chars, single line), never raw JSON
Failure catalog¶
Failed turns print a three-line card: title plus code, cause, and fix
(TuiFailureCatalog, which resolves the shared AgentFailureCopy table in
RuAgent.Client; the desktop client resolves the same table).
Covered families: provider auth/key/model (catalog_unauthorized,
provider_not_active, provider_configuration_changed, forbidden),
rate limits (catalog_rate_limited / rate_limited, HTTP 429),
transport (timeout / transport_error), provider errors
(server_error / http_error / malformed_payload), catalog reachability
(catalog_unavailable / catalog_http_error) and shape
(catalog_malformed / catalog_too_large / catalog_configuration_error),
response_too_large, vision_unsupported (image_limit_exceeded,
image_too_large, invalid_image_mime, invalid_image_base64),
invalid_prompt, empty_model_reply,
model_failed / model_timeout / prompt_too_large / model_unavailable,
model-backend reachability (historical worker_unavailable / worker_failed
codes, kept apart from
provider_failed / generation_failed / drive_failed execution failures),
run lifecycle (repeated_tool_call, prompt_contract_invalid,
run_not_runnable, workspace_busy, reconciliation_required,
reconcile_stale, approvals, tool_failed, store/preset/session/workspace
failures, compact_failed, command_invalid / command_unknown),
budget and context (policy_denied, context_limit_reached,
model_step_budget_exhausted, tool_call_budget_exhausted,
commit_conflict, unverified_after_tool_failure), tool execution
(workspace_changed, process_timed_out, git_timed_out,
invalid_terminal_write_set), web tools (web_response_too_large,
web_search_parse_failed, web_redirect_limit, web_redirect_invalid,
web_content_type_not_supported, web_json_invalid, web_encoding_invalid,
web_uri_not_allowed, web_private_host, web_connect_failed,
web_disabled, web_uri_invalid, web_search_endpoint_not_allowed),
recovery and approvals (permission_profile_changed, recovery_pre_dispatch,
recovery_read_only_incomplete, broker_gateway_unavailable,
approval_authorization_failed), and client/backend lifecycle
(invalid_preset, full_access_confirmation_required, trust_failed,
run_not_parked, output_frame_exceeds_limit, unsupported_protocol,
unsupported_protocol_version, reconcile_failed).
Codes outside the table still name themselves and point at
%LOCALAPPDATA%\Ru\logs plus /status instead of rendering bare.
When a models.dev:* backend has no stored credential, the /model card says
use /provider <name> to sign in instead of leaving a silent absence.
References¶
RuAgent.Clientonly (RuAgent.Protocolfor contracts). NoRuBackend,Broker,Worker, orSystem.CommandLine.
Policy JSON (version 1):
{
"version": 1,
"rules": [
{
"scope": "global",
"decision": "allow",
"matcher": {
"tool_id": "read",
"canonical_path_pattern": "src/app.ts"
}
}
]
}
Installed CLI updates¶
ru update --check checks the selected channel; ru update asks before
installation and ru update --yes explicitly installs. /update in TUI is
check-only unless --yes is supplied. Stable is the default;
--channel preview opts into prereleases. Source builds use build.bat instead.
See distribution and updates.
Subagent tasks¶
Use /subagents [run-id] to inspect coding/review children and their pinned models,
results and usage. Add agent-id result [version] to read a versioned result.
Only the main agent can send, cancel or integrate child work. Generic child run
mutations and approvals are refused. RPC exposes subagent.list and subagent.get.
In the Terminal.Gui chat a live strip on the header's workspace row lists the root's children (◐ running, ◇ waiting, ✓ finished, ✗ failed, ○ stopped; active ones first, +N for those that do not fit), and the transcript gets one line when a child starts, finishes, fails or is stopped. Sequential chat prints the same lines; --json stays silent. Both follow the loss-tolerant subagent.changed hints, so a missed hint only skips an intermediate line; /subagents reads the durable list.
See subagent operations.
Custom slash commands¶
Put a Markdown template at <workspace>/.ru/commands/<name>.md (or ~/.ru/commands/<name>.md) and run it as /<name> [arguments]. Names are lowercase letters, digits, _ and -. $ARGUMENTS in the template is replaced by the text after the command; without it, the text is appended after the template. An optional --- front matter may carry description:. Built-in commands win over templates, workspace templates win over user templates, and files over 64 KB, links or non-UTF-8 files are ignored. The expanded text is sent as an ordinary prompt: a template grants no tool, path or approval authority.