@ricsam/r5dctl

CLI for managing r5d.dev platform resources (projects, branches, and sessions).

Installation

npm install -g @ricsam/r5dctl

Login

r5dctl auth login

This starts a device-authorization flow, prints an eight-character code and QR, and opens https://r5d.dev/auth. Approve the matching device details in the browser before the credential is saved.

Use --no-open when no host browser is available, --no-qr to print only the short code, --device-name <name> to label the authorized device, and --worker-label <label> to record the worker it is intended to run.

Credentials are stored in:

• ~/.config/r5d/r5dctl/config.json

Global Flags

• --base-url <url>
• --json
• --config <path>
• --token <token>
• --api-key <key>
• -p, --project <namespace/name|id>
• -b, --branch <branch>
• -s, --session <sessionId>

Common Commands

r5dctl auth status
r5dctl auth logout
r5dctl auth api-key create --name "ci" --save
r5dctl auth api-key list
r5dctl auth api-key revoke <key-id>

r5dctl get projects
r5dctl describe project <namespace/name|id>
r5dctl update project <namespace/name|id> --mode prod
r5dctl delete project <namespace/name|id>

r5dctl -p <project> get branches
r5dctl -p <project> describe branch <branch>
r5dctl -p <project> get envs
r5dctl -p <project> get envs --show-values
r5dctl -p <project> get env API_KEY
r5dctl -p <project> set envs --from-env-file ~/.env --only-missing
r5dctl -p <project> set envs -e API_KEY=value --description "API credential"
r5dctl -p <project> get sessions --branch <branch>
r5dctl -p <project> create session -b <branch> --name "Spec session"
r5dctl describe session <session-id>
r5dctl -s <session-id> update session --name "Renamed session"
r5dctl -s <session-id> delete session

r5dctl -s <session-id> conversation                    # human-readable transcript without system/tools
r5dctl -s <session-id> conversation --raw              # raw JSON message/tool parts
r5dctl -s <session-id> conversation --tools            # include provider-shaped tool definitions
r5dctl -s <session-id> conversation --system           # include system prompt messages
r5dctl -s <session-id> conversation --raw --tools --system  # exact raw agent request transcript
r5dctl -s <session-id> conversation -f                  # print current transcript, then follow new output (--watch also works)
r5dctl conversation overview <session-id>               # dialogue/thinking with tool work omitted
r5dctl conversation overview <session-id> --skeleton     # user messages, decisions, and per-turn work markers only
r5dctl conversation inspect-node <session-id> <node-id>  # raw persisted node plus traversal metadata
r5dctl conversation inspect-work <session-id> <work-id> # compact call list for one omitted turn
r5dctl conversation inspect-work <session-id> <work-id> --summary
r5dctl conversation inspect-work <session-id> <work-id> --full --calls 12-20
r5dctl conversation inspect-work <session-id> <work-id> --include-polls
r5dctl conversation move-head <session-id> <node-id>     # rewind or replay the transcript; files stay put
r5dctl conversation fork <session-id> <node-id>          # copy the branch up to a node into a new session
r5dctl conversation fork <session-id> <node-id> --name "Retry with tests"
r5dctl session prompt --worker <label> --mode plan --model max <session-id> "..."
r5dctl -s <session-id> answer-questions --worker <label> --mode plan --model max -a1 "Recipe Collection" -a2 "Both Manual & AI"
r5dctl -s <session-id> answer-env-request --worker <label> --mode agent --model max -e KEY=value --context "Generate the remaining salts"

r5dctl -p <project> session start --worker <label> --worktree main --model max "Explore the failure"
r5dctl -p <project> session start --worker <label> --new-worktree fix/tests --source worktree:main --model max -f "Fix the failing tests"
r5dctl session status <session-id>
r5dctl session prompt --worker <label> --mode agent --model max <session-id> "Also check the migration"
r5dctl session stop <session-id>

r5dctl -p <project> merge fix/tests
r5dctl -p <project> merge --worker <label> --create-conflict-worktree fix/tests
r5dctl -p <project> merge --worker <label> --launch-conflict-resolution-agent fix/tests
r5dctl -p <project> merge finish --worker <label> conflicts/fix-tests --summary "Resolved the conflicts"

r5dctl -p <project> -b <branch> shell
r5dctl -p <project> -b <branch> shell -c "bun test"

r5dctl ps list
r5dctl -p <project> -b <branch> ps list --worker <label>
r5dctl -s <session-id> ps list --json
r5dctl ps stop <run-id>

r5dctl k8s usage
r5dctl k8s usage --namespace default --workload api --container server
r5dctl k8s usage --window 7d
r5dctl k8s usage --workload default/api --window 7d --json

session start creates an ordinary agent-mode chat on an explicitly selected existing worktree, or creates a named worktree from an explicit worktree:<branch> source. It requires project, worker, model, and prompt and never infers them from the current shell. Starts and prompts return after durable enqueue while execution continues asynchronously. Task specialization belongs in the prompt; there are no predefined debug, explore, research, or test agents. session stop returns as soon as the agent run is stopped; the stopped worktree's workspace publication finishes asynchronously behind the response, and merge republishes at its own boundary before reading the worktree.

Add -f/--follow/--watch to session start to attach after enqueue, or to conversation to print the current transcript and follow new output. Assistant text is written to stdout and lifecycle/tool progress to stderr; --tools includes tool calls and results. With global --json, follow mode emits one JSON event per line. Ctrl-C only detaches and never stops the session. The CLI reconnects transiently interrupted event streams and resynchronizes committed conversation revisions without repeating assistant text.

merge merges a managed source worktree into its recorded parent. By default conflicts are reported without creating more work. --create-conflict-worktree prepares a manual conflict worktree, while --launch-conflict-resolution-agent starts the dedicated merge-conflict resolver; those strategies are mutually exclusive. A worker-bound shell credential supplies its own worker automatically; otherwise pass --worker. Finish a reviewed manual resolution with merge finish.

shell connects to the same live worker PTY as the web Shell tab. Without -c it attaches the local terminal interactively. With -c/--command, it runs the supplied shell expression, streams combined PTY output, and exits with the remote command's status. Because command output uses a PTY, stdout and stderr are combined and programs may emit colors or other terminal control sequences.

ps list shows active long-running commands managed by r5d. It does not expose the worker host's general OS process table or interactive PTYs. Global project, branch, and session options filter the list, while --worker selects a worker label. ps stop sends SIGTERM to the selected run. Inside an r5d-provided worker shell, the temporary credential can only list and stop runs on that shell's worker.

k8s usage shows current and rolling CPU and memory usage for every workload container in your managed vCluster. The default window is 24h; pass --window 7d for seven days. Filter with --namespace, --workload, or --container; a workload may be identified by name, namespace/name, or Kubernetes UID. Human-readable output shows current totals across sampled replicas and the selected window's maximum. Global --json includes min/max summaries, the complete five-minute history envelope, per-pod series, coverage, and freshness metadata.

get envs reports names and whether values are set without revealing the values by default. Add --show-values to reveal every value; multiline and control characters are escaped for readable output. Without the global --json flag, get env <name> writes only that value to stdout, with no added newline or labels, so it works directly with command substitution and pipelines:

export API_KEY="$(r5dctl -p <project> get env API_KEY)"
r5dctl -p <project> get env PRIVATE_KEY | openssl pkey -check -noout

An undeclared or unset variable makes get env fail with a nonzero exit status. An explicitly configured empty value succeeds and writes zero bytes. Prefer --from-env-file for bulk imports so secret values do not appear in shell arguments or history. Empty dotenv values are skipped unless --include-empty is passed, and --only-missing preserves values that are already set.

Conversation output is human-readable by default and excludes both the system prompt and tool definitions. --raw keeps the transcript layout but renders structured message and tool parts as JSON, --tools includes the provider-shaped tool definitions, and --system includes system prompt messages. The global --json flag remains separate and prints the complete API response envelope.

When available, conversation rendering uses the newest complete persisted model-request snapshot on the active conversation branch, so its mode, tier, model, thinking mode, tools, and messages reflect the request that actually ran. Legacy or empty sessions without snapshots fall back to reconstruction from the latest conversation context.

conversation overview is a deterministic active-branch projection for recovering earlier work after a fresh-context boundary. It keeps user messages, injected context, assistant thinking/commentary/final responses, and user decisions, while replacing each turn's tool batches with a stable work ID and numbered call ranges. Adjacent tool batches with no visible content between them are coalesced into one range. --skeleton drops thinking and commentary too, keeping only dialogue, questions/answers, terminal responses, and one work marker per turn — the fastest first read of a long session. When the last turn is unfinished, both views end with a [Turn in progress: ...] footer naming the pending state and last node, so "still running" is distinguishable from "ended without a response".

Use conversation inspect-work with that session and work ID to inspect the omitted calls. Inspection is compact by default; --summary adds bounded targets/outcomes and --full renders persisted inputs and results with the normal tool renderers. The explicit --compact, --summary, and --full flags are mutually exclusive. --calls <n[-m]> selects a server-side call range while keeping the original call numbers, so a calls 83–90 omitted marker in the overview can be inspected directly. Compact and summary output are designed to be narrowed with grep, head, tail, sed, or cat -n.

Persisted shell results are dispatch-time snapshots, so a long-running command's stored status can go stale. Rendering joins each unresolved run against the durable process-run store: summary rows gain final_status=/final_exitCode= next to the stale snapshot fields, --full appends a ## Final process outcomes section with byte counts and output tails, and shell_poll calls whose run already finished are folded into one [calls N–M folded: ...] annotation carrying the final status. --include-polls restores the raw poll rows; call numbering never changes either way.

conversation inspect-node reads one exact persisted conversation node as formatted JSON. Its header includes the previous node, every direct next node, the next node on the active branch, whether the selected node is active, and the containing work_... ID when one is available. This allows callers that start with only a copied chat node ID to traverse nearby nodes or zoom out with conversation inspect-work.

conversation move-head and conversation fork change the transcript and nothing else. Neither one checks out, resets, or publishes anything: worker workspaces and the canonical repository keep the state the agent left them in. move-head points the session at any recorded node, so it rewinds past work, replays forward again, or switches to a sibling branch; every node stays stored, which makes the move reversible. The next prompt continues from the new head, and when that head already has children the new message becomes a sibling branch. fork instead copies the branch ending at the chosen node into a new session on the same project branch, named after its source, leaving the original session running untouched. Both refuse hidden maintenance sessions, and move-head refuses while a turn is running — stop the session first.

Project mode is derived from the persisted backwardsCompatible project setting:

• greenfield: agent can make breaking/reset-style changes
• prod: agent should keep changes backwards compatible