CLI reference
Every rupu command, argument and flag. This page is generated from the binary’s own --help, so it matches the release it was built from. For walkthroughs, start with the Quickstart; rupu <command> --help prints the same text locally.
Global options
These apply to every command.
| Option | Description |
|---|
--format <FORMAT> | Structured output format for commands that support tabular/report views [possible values: table, pretty, json, jsonl, csv] |
--absolute | Show absolute ISO timestamps in tables instead of relative ages. Useful when correlating a run against external logs |
--all-columns | Keep every table column, including ones that are empty for every row shown. Columns are otherwise suppressed based on the rows actually displayed, so a filtered listing may show fewer columns |
--max-open-files <N> | Raise this process's open-file limit (RLIMIT_NOFILE) to N and cap automatic growth there. Overrides RUPU_MAX_OPEN_FILES and [runtime].max_open_files. Wide fan-outs hold several descriptors per concurrent agent |
Commands
| Command | What it does |
|---|
rupu run | One-shot agent run, or pause/resume a run by id |
rupu agent | Manage agents |
rupu workflow | Manage workflows |
rupu agentiflow | Run goal-directed agent fleets (agentiflows) |
rupu message | Talk to a run as its operator: its message space's messages, participants, and sending into it |
rupu autoflow | Run autonomous workflows against persistent issue state |
rupu transcript | Browse transcripts |
rupu config | Get / set configuration values |
rupu customer | Customers: group projects under a customer with its own config layer |
rupu ui | Manage UI themes and palette imports |
rupu cleanup | Prune archived local sessions and transcripts |
rupu auth | Manage provider credentials |
rupu models | List or refresh available models |
rupu netflow | Manage per-run netflow ledgers (retention / pruning) |
rupu repos | SCM repository operations |
rupu scm | Multi-account SCM routing: rules and the account roster |
rupu session | Persistent agent sessions |
rupu issues | Issue-tracker operations (list / show / run a workflow) |
rupu init | Bootstrap a new rupu project (.rupu/agents, .rupu/workflows, .rupu/netflow, config) |
rupu mcp | Deprecated: mcp serve runs rupu cp serve --no-web (the MCP over HTTP at /mcp) |
rupu coverage | Inspect agentic coverage ledgers and concern catalogs |
rupu fleet | Install the stock security-assessment fleet (the generic agents + workflows the built-in engagement profiles name) into ~/.rupu |
rupu skill | Agent Skills: install, update, list, show and validate SKILL.md skills |
rupu findings | Finding reports: the embedded report schema, and report exports |
rupu cron | Schedule-driven workflow firing (designed for system cron) |
rupu webhook | Webhook receiver for event-triggered workflows (GitHub / GitLab) |
rupu cp | Control-plane HTTP server for the rupu web UI |
rupu usage | Aggregate token spend across persisted transcripts |
rupu watch | Re-attach to an existing run |
rupu completions | Generate or install shell-completion scripts |
rupu host | Manage named rupu-cp hosts (add / list / remove) |
rupu node | Dial-home tunnel agent + node enrollment |
rupu update | Download and install the latest release for the configured channel |
rupu run
One-shot agent run, or pause/resume a run by id
rupu run [OPTIONS]
rupu run <agent>
Run one agent, optionally against a repo/PR/issue target
rupu run [OPTIONS] <AGENT> [TARGET] [PROMPT]
| Argument | Description |
|---|
<AGENT> | Agent name (matches an agents/*.md file) |
[TARGET] | Optional target reference, e.g. github:owner/repo#42. See docs/scm.md#target-syntax for the full grammar. Distinguished from prompt by parsing as a RunTarget |
[PROMPT] | Optional initial user message. Defaults to "go" if omitted. Leading /skill tokens (/pdf summarize it) invoke those skills: their instructions go ahead of the rest of the prompt |
| Option | Description |
|---|
--prompt <PROMPT_FLAG> | Explicit prompt flag (takes precedence over the positional prompt). Use this when the prompt should not be confused with a target string |
--mode <MODE> | Override permission mode (ask | bypass | readonly) |
--no-stream | Don't render tokens as they arrive; show each response once it is complete. The request still streams on the wire, so long responses can't hit the request timeout |
--view <VIEW> | Control live output density (focused | full) [possible values: focused, compact, full] |
--into <PATH> | For <platform>:<owner>/<repo> targets: clone into this directory instead of the default ./<repo>/. The directory must not already exist (refuse-by-default — pass an explicit path you own), except on --continue, which reuses the original run's checkout there. Mutually exclusive with --tmp |
--tmp | For <platform>:<owner>/<repo> targets: clone into a temporary directory that is auto-deleted on exit. Useful for one-shot agents that produce findings without modifying the repo. Mutually exclusive with --into |
--run-id <RUN_ID> | Pre-assign the run id (so a caller can reference the run before it starts) |
--findings-profile <PROFILE> | Findings contract for this run (full | summary), overriding the agent's findingsProfile. A placed workflow unit's coordinator passes its step's resolved profile this way |
--engagement-profile <ID> | Engagement profile(s) for this run — the asset domain(s) findings are validated against (e.g. network, binary, or a composite like pentest). Repeatable or comma-separated. Empty = the code path [aliases: --engagement-profiles] |
--skill <SKILL> | A skill this run may load, on top of the agent's own; repeat the flag for several. A coordinator passes a workflow step's skills: this way. --continue keeps the continued run's unless this is given, which replaces the whole list |
--preload-skill <SKILL> | A skill whose body goes in this run's system prompt; repeat the flag for several |
--no-messaging | Turn this run's messaging tools off, and its children's, as an agent's messaging: false would. A placed unit's coordinator passes it for a workflow whose messaging is off |
--messaging-tool <NAME> | A messaging tool this run is offered, and only these; repeat the flag for several (--messaging-tool= alone for none), as a workflow's messaging: { tools } gives its steps. A placed unit's coordinator passes them. Only board.* / msg.* tools |
--continue <AGENT_RUN_ID> | Continue an earlier run of this agent from its transcript instead of starting fresh: the earlier conversation is rebuilt. Every flag and the target the original run was launched with are restored (recorded as RunStart.launch_args); a flag given here replaces only its own setting. A repo target reuses the checkout the original run cloned. Run it from the same directory as the original run. With no prompt, an interrupted run is told it was interrupted and carries on; a run that had already finished prints its recorded answer without calling the model; and a run that failed on a provider-side outcome (a refusal, say) is continued only with --model or --provider, on that model. With a prompt (positional, when it is not a run target, or --prompt), any ended run continues: an interrupted one gets the interruption note and then the prompt, a finished one gets the prompt as a new turn, and a failed one continues on the same model too. The prompt is never restored from, or recorded in, the launch command: it is in the new run's conversation, which a --continue of that run rebuilds. |
--model <MODEL> | Model for this run, overriding the agent's model: and the config default |
--provider <PROVIDER> | Provider for this run, overriding the agent's provider: and the config default |
Continuing a run. A bare
rupu run <agent> --continue <run id> picks an interrupted run up where it stopped, with every flag and the target of the original run restored; a run that had already finished prints its recorded answer. Give it a prompt —
rupu run <agent> --continue <run id> "<instruction>" — and any ended run continues with it: an interrupted one gets the interruption note and then the prompt, a finished one gets it as a new turn, a failed one continues on its own model. Without a prompt, a run that failed on a provider-side outcome (a refusal, say) is continued only with
--model or
--provider, on that model. Skills (
--skill,
--preload-skill, a leading
/name in the prompt) are covered in
Skills; the messaging switches (
--no-messaging,
--messaging-tool) in
Messaging.
rupu run pause
Pause a running workflow run by id
rupu run pause <RUN_ID>
| Argument | Description |
|---|
<RUN_ID> | Full run id (run_<ULID>) as printed by rupu run / rupu workflow run |
rupu run resume
Resume a paused workflow run by id
rupu run resume [OPTIONS] <RUN_ID>
| Argument | Description |
|---|
<RUN_ID> | Full run id (run_<ULID>) of the run to resume |
| Option | Description |
|---|
--mode <MODE> | Override permission mode for the resumed run (ask | bypass | readonly) |
--plain | Use the plain line printer instead of the live graph view |
--restart-interrupted | Start every interrupted step and for_each unit over from its prompt instead of continuing it from its transcript |
rupu run list
List recent workflow runs, newest first
rupu run list [OPTIONS]
| Option | Description |
|---|
--limit <LIMIT> | Return at most N runs, newest first [default: 10000] |
--status <STATUS> | Filter by status (running, completed, failed, …) |
rupu run show
Show one workflow run's detail
rupu run show <RUN_ID>
| Argument | Description |
|---|
<RUN_ID> | Full run id (run_<ULID>) |
rupu agent
Manage agents
rupu agent [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
list | List all available agents (global + project) |
show | Print an agent's frontmatter and body |
edit | Open an agent file in $VISUAL / $EDITOR. Validates the frontmatter on save (warn-only) |
validate | Check agent files: each must parse and its tools: must name known tools (an unknown name is a load error). Checks every file in the global and project agent dirs with --all, shadowed ones included. Exits nonzero when any check fails |
create | Scaffold a new agent file, then open it for editing. Prompts interactively for scope and name when omitted. With --describe, a model drafts the definition before you review it |
rupu agent list
List all available agents (global + project)
rupu agent list [OPTIONS]
| Option | Description |
|---|
--no-color | Disable colored output (also honored: NO_COLOR env, [ui].color = "never" in config) |
rupu agent show
Print an agent's frontmatter and body
rupu agent show [OPTIONS] <NAME>
| Argument | Description |
|---|
<NAME> | Name of the agent |
| Option | Description |
|---|
--no-color | Disable colored output (also honored: NO_COLOR env var) |
--theme <THEME> | syntect theme name. Default: base16-ocean.dark |
--pager | Force pager. Default: page when stdout is a tty |
--no-pager | Disable pager |
rupu agent edit
Open an agent file in $VISUAL / $EDITOR. Validates the frontmatter on save (warn-only)
rupu agent edit [OPTIONS] <NAME>
| Argument | Description |
|---|
<NAME> | Name of the agent |
| Option | Description |
|---|
--scope <SCOPE> | Force the project shadow (.rupu/agents/<name>.md) or the global file (<global>/agents/<name>.md). Default: prefer project if it exists, else global [possible values: global, project] |
--editor <EDITOR> | Override the editor (e.g. --editor "code --wait"). Default: $VISUAL then $EDITOR then vi |
rupu agent validate
Check agent files: each must parse and its tools: must name known tools (an unknown name is a load error). Checks every file in the global and project agent dirs with --all, shadowed ones included. Exits nonzero when any check fails
rupu agent validate [OPTIONS] <NAME|--all>
| Argument | Description |
|---|
[NAME] | Name of the agent (frontmatter name: or file stem) |
| Option | Description |
|---|
--all | Check every agent file in both layers |
rupu agent create
Scaffold a new agent file, then open it for editing. Prompts interactively for scope and name when omitted. With --describe, a model drafts the definition before you review it
rupu agent create [OPTIONS] [NAME]
| Argument | Description |
|---|
[NAME] | Name for the new agent (no .md extension) |
| Option | Description |
|---|
--scope <SCOPE> | Target scope (global or project). Prompts when omitted [possible values: global, project] |
--editor <EDITOR> | Override the editor (e.g. --editor "code --wait") |
--describe <DESCRIBE> | Natural-language description — a model drafts the agent |
--gen-provider <GEN_PROVIDER> | Provider for generation (default: first authenticated) |
--gen-model <GEN_MODEL> | Model for generation (default: provider's default) |
--host <HOST> | Host to create on (only local available today) [default: local] |
rupu workflow
Manage workflows
rupu workflow [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
list | List all workflows (global + project) |
show | Inspect a workflow definition |
edit | Open a workflow file in $VISUAL / $EDITOR. Validates the YAML on save (warn-only) |
create | Scaffold a new workflow YAML from a template, then open it for editing. Prompts interactively for scope and name when omitted. With --describe, a model drafts the definition before you review it |
run | Run a workflow |
runs | List recent workflow runs from the persistent run-store (<global>/runs/). Newest first |
show-run | Inspect one persisted run: status, inputs, per-step transcript pointers |
approve | Approve a paused run and resume execution from the awaited step. The run must be in awaiting_approval status |
reject | Reject a paused run. Marks it rejected; no further steps dispatch |
cancel | Cancel a running workflow run |
pause | Cooperatively pause a running workflow run at its next safe boundary, leaving it non-terminal and resumable via rupu workflow resume |
resume | Resume a failed/cancelled run, re-running only the agent runs that didn't succeed. An agent run the interrupted process left mid-flight is picked up where it stopped (or its finished answer reused) rather than started over |
archive-run | Archive a terminal run (move it out of the active list; reversible) |
restore-run | Restore an archived run back to the active list |
delete-run | Permanently delete a run and its transcripts. Requires --force |
rupu workflow list
List all workflows (global + project)
rupu workflow list [OPTIONS]
rupu workflow show
Inspect a workflow definition
rupu workflow show [OPTIONS] <NAME>
| Argument | Description |
|---|
<NAME> | Workflow name (filename stem under workflows/) |
| Option | Description |
|---|
--view <VIEW> | Human snapshot density (focused | compact | full) [default: full] [possible values: focused, compact, full] |
--no-color | Disable colored output (also honored: NO_COLOR env var) |
--theme <THEME> | syntect theme name. Default: base16-ocean.dark |
--pager | Force pager. Default: page when stdout is a tty |
--no-pager | Disable pager |
rupu workflow edit
Open a workflow file in $VISUAL / $EDITOR. Validates the YAML on save (warn-only)
rupu workflow edit [OPTIONS] <NAME>
| Argument | Description |
|---|
<NAME> | Workflow name (filename stem under workflows/) |
| Option | Description |
|---|
--scope <SCOPE> | Force the project shadow (.rupu/workflows/<name>.yaml) or the global file (<global>/workflows/<name>.yaml). Default: prefer project if it exists, else global [possible values: global, project] |
--editor <EDITOR> | Override the editor (e.g. --editor "code --wait"). Default: $VISUAL then $EDITOR then vi |
rupu workflow create
Scaffold a new workflow YAML from a template, then open it for editing. Prompts interactively for scope and name when omitted. With --describe, a model drafts the definition before you review it
rupu workflow create [OPTIONS] [NAME]
| Argument | Description |
|---|
[NAME] | Workflow name (no .yaml extension) |
| Option | Description |
|---|
--scope <SCOPE> | Target scope (global or project). Prompts when omitted [possible values: global, project] |
--editor <EDITOR> | Override the editor (e.g. --editor "code --wait") |
--describe <DESCRIBE> | Natural-language description — a model drafts the workflow |
--gen-provider <GEN_PROVIDER> | Provider for generation (default: first authenticated) |
--gen-model <GEN_MODEL> | Model for generation (default: provider's default) |
--host <HOST> | Host to create on (only local available today) [default: local] |
rupu workflow run
Run a workflow
rupu workflow run [OPTIONS] [NAME] [TARGET]
| Argument | Description |
|---|
[NAME] | Workflow name (filename stem under workflows/). Omit when running from a file with --file |
[TARGET] | Optional run-target: a repo, PR, or issue reference. Accepts repo (github:owner/repo, gitlab:group/proj), PR (github:owner/repo#42), or issue (github:owner/repo/issues/42). Repo / PR targets clone to a tmpdir for the run; issue targets pre-fetch the issue payload and bind it as {{ issue.* }} in step prompts. |
| Option | Description |
|---|
--input <INPUT> | KEY=VALUE template inputs (repeatable) |
--mode <MODE> | Override permission mode (ask | bypass | readonly) |
--view <VIEW> | Control live output density (focused | full) [possible values: focused, compact, full] |
--plain | Use the plain line printer instead of the live graph view |
--run-id <RUN_ID> | Pre-assign the run id (e.g. so a caller can reference the run before it starts) |
--engagement-profile <ID> | Engagement profile(s) for this run — the asset domain(s) every step's findings are validated against (e.g. network, binary, or a composite like pentest). Repeatable or comma-separated. Empty = the code path [aliases: --engagement-profiles] |
--file <PATH> | Run a workflow directly from a file path instead of resolving a name from the catalog. The workflow is not added to the catalog |
rupu workflow runs
List recent workflow runs from the persistent run-store (<global>/runs/). Newest first
rupu workflow runs [OPTIONS]
| Option | Description |
|---|
--limit <LIMIT> | Show only the N most recent runs [default: 50] |
--status <STATUS> | Filter by status: pending / running / completed / failed / awaiting_approval / rejected |
--issue <ISSUE> | Filter by issue ref (full or shorthand). Matches the textual RunRecord.issue_ref persisted at run start. Accepts <platform>:<owner>/<repo>/issues/<N> (full), <owner>/<repo>#<N> (GitHub shorthand), or bare <N> (autodetects from cwd's git remote) |
--no-color | Disable colored output (also honored: NO_COLOR env, [ui].color = "never" in config) |
rupu workflow show-run
Inspect one persisted run: status, inputs, per-step transcript pointers
rupu workflow show-run [OPTIONS] <RUN_ID>
| Argument | Description |
|---|
<RUN_ID> | Full run id (run_<ULID>) as printed by rupu workflow run |
| Option | Description |
|---|
--view <VIEW> | Live view density for the retained snapshot [possible values: focused, compact, full] |
--no-color | Disable colored output (also honored: NO_COLOR env, [ui].color = \"never\" in config) |
--pager | Force pager. Default: page when stdout is a tty |
--no-pager | Disable pager |
rupu workflow approve
Approve a paused run and resume execution from the awaited step. The run must be in awaiting_approval status
rupu workflow approve [OPTIONS] <RUN_ID>
| Argument | Description |
|---|
<RUN_ID> | Full run id (run_<ULID>) of the run awaiting approval |
| Option | Description |
|---|
--mode <MODE> | Override permission mode for the resumed run (ask | bypass | readonly) |
--gate <GATE> | Target a specific parked approval gate by step id — required once a run has more than one gate parked at once (a concurrent DAG run with several gates in the same batch-park wave). Omit for the legacy/single-gate case: the sole parked gate is approved exactly as before. Approving one gate of several leaves the others parked; the run stays awaiting_approval until every gate is resolved |
rupu workflow reject
Reject a paused run. Marks it rejected; no further steps dispatch
rupu workflow reject [OPTIONS] <RUN_ID>
| Argument | Description |
|---|
<RUN_ID> | Full run id (run_<ULID>) of the run awaiting approval |
| Option | Description |
|---|
--reason <REASON> | Optional human-readable reason recorded in the run's error_message |
--gate <GATE> | Target a specific parked approval gate by step id — same targeting rule as approve --gate. Rejecting one gate of several runs THAT gate's on_reject cleanup chain and leaves the others parked; the run flips to rejected only once every gate is resolved |
rupu workflow cancel
Cancel a running workflow run
rupu workflow cancel [OPTIONS] <RUN_ID>
| Argument | Description |
|---|
<RUN_ID> | Full run id (run_<ULID>) as printed by rupu workflow run |
rupu workflow pause
Cooperatively pause a running workflow run at its next safe boundary, leaving it non-terminal and resumable via rupu workflow resume
rupu workflow pause [OPTIONS] <RUN_ID>
| Argument | Description |
|---|
<RUN_ID> | Full run id (run_<ULID>) as printed by rupu workflow run |
rupu workflow resume
Resume a failed/cancelled run, re-running only the agent runs that didn't succeed. An agent run the interrupted process left mid-flight is picked up where it stopped (or its finished answer reused) rather than started over
rupu workflow resume [OPTIONS] <RUN_ID>
| Argument | Description |
|---|
<RUN_ID> | Full run id (run_<ULID>) of the terminal run to resume |
| Option | Description |
|---|
--mode <MODE> | Override permission mode for the resumed run (ask | bypass | readonly) |
--plain | Use the plain line printer instead of the live graph view |
--restart-interrupted | Start every interrupted step and for_each unit over from its prompt instead of continuing it from its transcript |
rupu workflow archive-run
Archive a terminal run (move it out of the active list; reversible)
rupu workflow archive-run [OPTIONS] <RUN_ID>
| Argument | Description |
|---|
<RUN_ID> | Full run id (run_<ULID>) |
rupu workflow restore-run
Restore an archived run back to the active list
rupu workflow restore-run [OPTIONS] <RUN_ID>
| Argument | Description |
|---|
<RUN_ID> | Full run id (run_<ULID>) |
rupu workflow delete-run
Permanently delete a run and its transcripts. Requires --force
rupu workflow delete-run [OPTIONS] <RUN_ID>
| Argument | Description |
|---|
<RUN_ID> | Full run id (run_<ULID>) |
| Option | Description |
|---|
--force | Confirm the permanent deletion (required). A run that has not finished is refused even with --force; cancel it first |
rupu agentiflow
Run goal-directed agent fleets (agentiflows)
rupu agentiflow [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
run | Run an agentiflow in the foreground until its envelope stops it |
list | List agentiflow runs, newest first |
status | Show one agentiflow run: goals, budget, rounds and why it stopped |
send | Send a message to a running agentiflow's lead, as its operator |
stop | Stop a running agentiflow |
attach | Watch an agentiflow run: its event log and its lead's current round |
serve | Supervise agentiflow runs: reap the ones whose coordinator died |
rupu agentiflow run
Run an agentiflow in the foreground until its envelope stops it. Loads <project>/.rupu/agentiflows/<DEF>.yaml (else ~/.rupu/agentiflows/<DEF>.yaml), validates it against its engagement profiles, and runs it to a stop: goals met, coverage reached, a budget or ceiling, or an operator stop. Prints the run id up front (stderr) and the outcome at the end. With --detach the run goes to a background process of its own and the command returns as soon as the run has started, printing the run id on stdout; follow it with agentiflow status <id>, steer it with send, end it with stop. A run that cannot start (no credential, an invalid definition) is reported here with the cause, not left to fail unseen.
rupu agentiflow run [OPTIONS] <DEF>
| Argument | Description |
|---|
<DEF> | Agentiflow name (matches an agentiflows/<name>.yaml file) |
| Option | Description |
|---|
--detach | Run in the background: start the run in its own process group and return once it has started. The background process's stderr is kept in <run dir>/detach.log; a run that fails before it starts has that error printed here and no run directory left behind |
rupu agentiflow list
List agentiflow runs, newest first. Reads <RUPU_HOME>/agentiflows/af_*/agentiflow.json. The definition files that sit beside the run directories are not runs and are not listed (see rupu agent list / rupu workflow list for definitions).
rupu agentiflow list [OPTIONS]
rupu agentiflow status
Show one agentiflow run: goals, budget, rounds and why it stopped
rupu agentiflow status [OPTIONS] <ID>
| Argument | Description |
|---|
<ID> | Run id (af_...): the full id, the compact form list prints, or a unique prefix / suffix of it |
rupu agentiflow send
Send a message to a running agentiflow's lead, as its operator. The message goes into the run's message space and the lead receives it before its next model call, mid-round included; the next round's prompt recaps it. --now marks it urgent: it is put first, and the lead's current round ends early so the lead turns to it. A run that isn't running (finished, or its coordinator died) takes no message.
rupu agentiflow send [OPTIONS] <ID> <MESSAGE>
| Argument | Description |
|---|
<ID> | Run id (af_...): the full id, the compact form list prints, or a unique prefix / suffix of it |
<MESSAGE> | What to tell the lead |
| Option | Description |
|---|
--now | Mark the message urgent and end the lead's current round early |
Shorthand. rupu agentiflow send <id> <text> [--now] is
rupu message send <id> --to lead [--urgent]. The operator side of a run’s message space is described in
Messaging.
rupu agentiflow stop
Stop a running agentiflow. By default the stop is graceful: it is queued for the envelope, which winds the run down at the next round boundary (the units it launched are stopped with it). --now is the hard stop: it SIGTERMs the coordinator (and, for a detached run, the process group it leads, so what its lead's tools started goes too), SIGTERMs every unit still running (SIGKILL for one that outlives a short grace), then records the run as failed (operator_stop:now) without waiting for the round.
rupu agentiflow stop [OPTIONS] <ID>
| Argument | Description |
|---|
<ID> | Run id (af_...): the full id, the compact form list prints, or a unique prefix / suffix of it |
| Option | Description |
|---|
--now | Hard stop: signal the coordinator and its units now |
rupu agentiflow attach
Watch an agentiflow run: its event log and its lead's current round. Prints the run's events.jsonl (everything so far, then each line as it lands) and the lead's transcript for the round in progress, moving on to the next round's transcript as it starts. By default it follows the run until it ends (a goal met, a budget, a stop, a failure) and then prints why it stopped. --no-follow (--once) prints what the run has recorded so far and returns. Attaching to a run that already finished shows its log and returns at once. Ctrl-C leaves the run going.
rupu agentiflow attach [OPTIONS] <ID>
| Argument | Description |
|---|
<ID> | Run id (af_...): the full id, the compact form list prints, or a unique prefix / suffix of it |
| Option | Description |
|---|
--no-follow | Print what the run has recorded so far and return, instead of following it until it ends [aliases: --once] |
rupu agentiflow serve
Supervise agentiflow runs: reap the ones whose coordinator died. A coordinator that is killed (SIGKILL, a crash, the machine going down) leaves its run running forever and its detached units burning tokens. This runs a sweep at startup and then every [agentiflow] serve_interval_secs (default 60), recording each such run as failed (orphaned: coordinator pid <p> not running) and stopping its units. It runs until SIGTERM / Ctrl-C. rupu cp serve runs the same sweep on its own tick, so this is for hosts that do not run the control plane. [agentiflow] serve_enabled = false or reaper_enabled = false turns it off.
rupu agentiflow serve [OPTIONS]
rupu message
Talk to a run as its operator: its message space's messages, participants, and sending into it
rupu message [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
list | Show what was said in a run's message space |
send | Send a message into a running run's message space, as its operator |
participants | List the participants in a run's message space |
rupu message list
Show what was said in a run's message space. One line per message (time from → to [kind] body), then, indented, whom it could not reach and who saw it on which turn. --follow keeps printing new messages and receipts until the run stops, then says why; Ctrl-C leaves the run going. --json prints the whole view as one object or, with --follow, one message per line (printed again when its receipts change).
rupu message list [OPTIONS] <RUN_ID>
| Argument | Description |
|---|
<RUN_ID> | Run id: a workflow run, an agentiflow (af_...), a session (ses_...) or a standalone run; the full id, the compact form a list prints, or a unique prefix / suffix of it |
| Option | Description |
|---|
--after <MSG_ID> | Only the messages after this one (msg_...) |
--follow | Keep printing new messages and receipts until the run stops |
--kind <KINDS> | Only these kinds, comma-separated: post, direct, broadcast, directive, retract, operator |
--json | Print JSON: the whole view, or with --follow one message per line |
rupu message send
Send a message into a running run's message space, as its operator. It goes to --to (a participant, a codename, role:<agent>, step:<id>, lead or broadcast); by default to an agentiflow's lead, and to everyone in any other run. Each recipient gets it before its next model call. --urgent puts it first, and ends an agentiflow lead's round early. A run that isn't running takes no message.
rupu message send [OPTIONS] <RUN_ID> <TEXT>...
| Argument | Description |
|---|
<RUN_ID> | Run id: a workflow run, an agentiflow (af_...), a session (ses_...) or a standalone run; the full id, the compact form a list prints, or a unique prefix / suffix of it |
<TEXT>... | The message (its words are joined with spaces) |
| Option | Description |
|---|
--to <ADDRESS> | Who the message is for: a participant, a codename, role:<agent>, step:<id>, lead or broadcast |
--urgent | Put the message first; an agentiflow lead ends its round early |
rupu message participants
List the participants in a run's message space
rupu message participants [OPTIONS] <RUN_ID>
| Argument | Description |
|---|
<RUN_ID> | Run id: a workflow run, an agentiflow (af_...), a session (ses_...) or a standalone run; the full id, the compact form a list prints, or a unique prefix / suffix of it |
| Option | Description |
|---|
--json | Print the participants as JSON |
Operator messages. Without
--to, a message goes to an agentiflow’s
lead, and to
broadcast in any other run; a broadcast into a run with nobody else joined reaches no one, and
send prints
not delivered to broadcast: no_live_participant. A recipient sees the message before its next model call, framed as an instruction from its operator;
--urgent delivers it ahead of everything else and never interrupts a tool call in progress. A run that isn’t running takes no message. The control plane serves the same over
GET/POST /api/{runs,sessions,agentiflows}/:id/messages. See
Messaging.
rupu autoflow
Run autonomous workflows against persistent issue state
rupu autoflow [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
list | List autoflow-enabled workflows |
show | Show one autoflow workflow and its resolved metadata |
run | Execute one autonomous cycle for one issue target |
tick | Reconcile every discovered autoflow once |
serve | Run the autoflow reconciler as a long-lived local worker |
stop | Stop a running local autoflow serve worker |
wakes | Inspect queued and recently processed wakes |
monitor | Show a read-only operator view across workers, claims, wakes, and recent activity |
history | Show durable autoflow cycle and event history |
explain | Explain the current autonomous state for one issue |
doctor | Run consistency checks across claims, wakes, and runs |
repair | Apply safe, bounded remediation to one issue claim |
requeue | Enqueue one manual wake for an issue |
status | Summarize persisted autoflow claim state |
claims | Inspect persisted autoflow claims |
release | Force-release one claim |
create | Scaffold a new autoflow-enabled workflow YAML, then open it for editing. Same template as workflow create plus an autoflow: block pre-filled with reasonable defaults |
rupu autoflow list
List autoflow-enabled workflows
rupu autoflow list [OPTIONS]
| Option | Description |
|---|
--repo <REPO> | Limit results to one repo target, for example github:owner/repo |
rupu autoflow show
Show one autoflow workflow and its resolved metadata
rupu autoflow show [OPTIONS] <NAME>
| Argument | Description |
|---|
<NAME> | Name of the autoflow-enabled workflow |
| Option | Description |
|---|
--repo <REPO> | Limit resolution to one tracked repo |
rupu autoflow run
Execute one autonomous cycle for one issue target
rupu autoflow run [OPTIONS] <NAME> <TARGET>
| Argument | Description |
|---|
<NAME> | Name of the autoflow-enabled workflow |
<TARGET> | Issue target in full run-target form: github:owner/repo/issues/42 or gitlab:group/project/issues/9 |
| Option | Description |
|---|
--repo <REPO> | Limit resolution to one bound repo |
--mode <MODE> | Override permission mode (bypass | readonly) |
rupu autoflow tick
Reconcile every discovered autoflow once
rupu autoflow tick [OPTIONS]
rupu autoflow serve
Run the autoflow reconciler as a long-lived local worker
rupu autoflow serve [OPTIONS]
| Option | Description |
|---|
--repo <REPO> | Limit reconciliation to one tracked repo |
--worker <WORKER> | Optional worker name override, for example team-mini-01 |
--idle-sleep <IDLE_SLEEP> | Idle sleep between reconciliation passes, for example 10s [default: 10s] |
--view <VIEW> | Live operator view mode (focused, compact, or full) [possible values: focused, compact, full] |
--quiet | Suppress the live interactive serve view |
rupu autoflow stop
Stop a running local autoflow serve worker
rupu autoflow stop [OPTIONS]
| Option | Description |
|---|
--worker <WORKER> | Limit to one worker id or display name |
--repo <REPO> | Limit to one repo filter, for example github:owner/repo |
rupu autoflow wakes
Inspect queued and recently processed wakes
rupu autoflow wakes [OPTIONS]
| Option | Description |
|---|
--repo <REPO> | Limit results to one repo target, for example github:owner/repo |
rupu autoflow monitor
Show a read-only operator view across workers, claims, wakes, and recent activity
rupu autoflow monitor [OPTIONS]
| Option | Description |
|---|
--repo <REPO> | Limit results to one repo target, for example github:owner/repo |
--worker <WORKER> | Limit results to one worker id or display name |
--watch | Refresh the operator view until interrupted |
--interval <INTERVAL> | Refresh interval for --watch, for example 2s [default: 2s] |
--view <VIEW> | Human/operator view mode (focused, compact, or full) [possible values: focused, compact, full] |
rupu autoflow history
Show durable autoflow cycle and event history
rupu autoflow history [OPTIONS] [REF]
| Argument | Description |
|---|
[REF] | Optional issue ref filter, for example linear:eng-team/issues/42 |
| Option | Description |
|---|
--repo <REPO> | Limit results to one repo target, for example github:owner/repo |
--source <SOURCE> | Limit results to one source target, for example linear:eng-team |
--worker <WORKER> | Limit results to one worker id or display name |
--event <EVENT> | Limit results to one event kind, for example run_launched |
--limit <LIMIT> | Maximum number of history rows to show [default: 50] |
--watch | Refresh the operator view until interrupted |
--interval <INTERVAL> | Refresh interval for --watch, for example 2s [default: 2s] |
--view <VIEW> | Human/operator view mode (focused, compact, or full) [possible values: focused, compact, full] |
rupu autoflow explain
Explain the current autonomous state for one issue
rupu autoflow explain [OPTIONS] <REF>
| Argument | Description |
|---|
<REF> | Issue ref, for example github:owner/repo/issues/42 |
| Option | Description |
|---|
--repo <REPO> | Limit resolution to one bound repo |
rupu autoflow doctor
Run consistency checks across claims, wakes, and runs
rupu autoflow doctor [OPTIONS]
| Option | Description |
|---|
--repo <REPO> | Limit results to one repo target, for example github:owner/repo |
rupu autoflow repair
Apply safe, bounded remediation to one issue claim
rupu autoflow repair [OPTIONS] <REF>
| Argument | Description |
|---|
<REF> | Issue ref, for example github:owner/repo/issues/42 |
| Option | Description |
|---|
--release | Explicitly release the claim after repair |
--requeue | Explicitly enqueue a follow-up wake after repair |
rupu autoflow requeue
Enqueue one manual wake for an issue
rupu autoflow requeue [OPTIONS] <REF>
| Argument | Description |
|---|
<REF> | Issue ref, for example github:owner/repo/issues/42 |
| Option | Description |
|---|
--event <EVENT> | Override the synthetic event id |
--not-before <NOT_BEFORE> | Delay wake visibility by a relative duration like 10m |
rupu autoflow status
Summarize persisted autoflow claim state
rupu autoflow status [OPTIONS]
| Option | Description |
|---|
--repo <REPO> | Limit results to one repo target, for example github:owner/repo |
rupu autoflow claims
Inspect persisted autoflow claims
rupu autoflow claims [OPTIONS]
| Option | Description |
|---|
--repo <REPO> | Limit results to one repo target, for example github:owner/repo |
rupu autoflow release
Force-release one claim
rupu autoflow release [OPTIONS] <REF>
| Argument | Description |
|---|
<REF> | Issue ref, for example github:owner/repo/issues/42 |
rupu autoflow create
Scaffold a new autoflow-enabled workflow YAML, then open it for editing. Same template as workflow create plus an autoflow: block pre-filled with reasonable defaults
rupu autoflow create [OPTIONS] [NAME]
| Argument | Description |
|---|
[NAME] | Workflow name (no .yaml extension) |
| Option | Description |
|---|
--scope <SCOPE> | Target scope (global or project). Prompts when omitted [possible values: global, project] |
--editor <EDITOR> | Override the editor (e.g. --editor "code --wait") |
rupu transcript
Browse transcripts
rupu transcript [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
list | List transcripts (project-local + global) sorted newest first |
show | Print a transcript's full event stream |
archive | Archive a standalone transcript and its metadata |
delete | Permanently delete a standalone transcript and its metadata |
prune | Delete archived standalone transcripts older than a cutoff |
rupu transcript list
List transcripts (project-local + global) sorted newest first
rupu transcript list [OPTIONS]
| Option | Description |
|---|
--limit <LIMIT> | Show only the N most recent transcripts. Pass a large value to list everything — every row beyond the limit costs a full read of its transcript, and a busy workspace accumulates thousands [default: 50] |
--no-color | Disable terminal colors. Honors NO_COLOR and the [ui].color config knob too — flag is the explicit override |
--all | Include both active and archived transcripts |
--archived | Show only archived transcripts |
rupu transcript show
Print a transcript's full event stream
rupu transcript show [OPTIONS] <RUN_ID>
| Argument | Description |
|---|
<RUN_ID> | Run id (run_<ULID>), a unique prefix, or a codename |
| Option | Description |
|---|
--view <VIEW> | [possible values: focused, compact, full] |
--no-color | Disable colored output (also honored: NO_COLOR env var) |
--pager | Force pager. Default: page when stdout is a tty |
--no-pager | Disable pager |
rupu transcript archive
Archive a standalone transcript and its metadata
rupu transcript archive [OPTIONS] <RUN_ID>
| Argument | Description |
|---|
<RUN_ID> | Run id (run_<ULID>), a unique prefix, or a codename |
| Option | Description |
|---|
--ignore-liveness | Skip the still-running check; only use when the recorded pid was reused by an unrelated process — deleting a live run's transcript loses it |
rupu transcript delete
Permanently delete a standalone transcript and its metadata
rupu transcript delete [OPTIONS] <RUN_ID>
| Argument | Description |
|---|
<RUN_ID> | Run id (run_<ULID>), a unique prefix, or a codename |
| Option | Description |
|---|
--force | Confirm the permanent deletion (required) |
--ignore-liveness | Skip the still-running check; only use when the recorded pid was reused by an unrelated process — deleting a live run's transcript loses it. Independent of --force: both are required to delete a transcript that still looks live |
rupu transcript prune
Delete archived standalone transcripts older than a cutoff
rupu transcript prune [OPTIONS]
| Option | Description |
|---|
--older-than <DURATION> | Retention cutoff, e.g. 30d, 12h, or 1w |
--dry-run | Preview deletions without removing files |
rupu config
Get / set configuration values
rupu config [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
get | Print the value of a key. Dotted keys (ui.theme) descend into nested tables |
set | Set a key. Dotted keys (ui.theme) descend into nested tables, creating them as needed. The value is parsed as a TOML scalar (string / integer / bool) |
rupu config get
Print the value of a key. Dotted keys (ui.theme) descend into nested tables
rupu config get [OPTIONS] <KEY>
| Argument | Description |
|---|
<KEY> | Dotted key to read from the global config.toml, e.g. ui.theme |
rupu config set
Set a key. Dotted keys (ui.theme) descend into nested tables, creating them as needed. The value is parsed as a TOML scalar (string / integer / bool)
rupu config set [OPTIONS] <KEY> <VALUE>
| Argument | Description |
|---|
<KEY> | Dotted key to write in the global config.toml, e.g. ui.theme |
<VALUE> | Value to store, parsed as a TOML scalar; text that doesn't parse is stored as a string |
rupu customer
Customers: group projects under a customer with its own config layer
rupu customer [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
list | List customers |
show | Metadata, assigned projects, and the customer's effective config |
create | Create a customer |
set | Change metadata. An empty value clears --notes, --contact, --color |
edit | Edit the customer's config layer in $EDITOR (validated on save) |
archive | Hide a customer from pickers; its projects keep running |
unarchive | Restore an archived customer to pickers |
delete | Delete a customer. Refused while any project is assigned |
assign | Assign a project (default: the current directory) |
unassign | Remove a project's customer (default: the current directory) |
rupu customer list
List customers
rupu customer list [OPTIONS]
| Option | Description |
|---|
--archived | Include archived customers |
rupu customer show
Metadata, assigned projects, and the customer's effective config
rupu customer show [OPTIONS] <SLUG>
| Argument | Description |
|---|
<SLUG> | Customer slug (e.g. acme) |
rupu customer create
Create a customer
rupu customer create [OPTIONS] --name <NAME> <SLUG>
| Argument | Description |
|---|
<SLUG> | New customer's slug: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters |
| Option | Description |
|---|
--name <NAME> | Display name |
--notes <NOTES> | Free-form notes |
--contact <CONTACT> | Contact (a person, email, or channel) |
--color <COLOR> | Display color, #rrggbb |
rupu customer set
Change metadata. An empty value clears --notes, --contact, --color
rupu customer set [OPTIONS] <SLUG>
| Argument | Description |
|---|
<SLUG> | Customer slug (e.g. acme) |
| Option | Description |
|---|
--name <NAME> | New display name |
--notes <NOTES> | New notes; an empty value clears them |
--contact <CONTACT> | New contact; an empty value clears it |
--color <COLOR> | New display color, #rrggbb; an empty value clears it |
rupu customer edit
Edit the customer's config layer in $EDITOR (validated on save)
rupu customer edit [OPTIONS] <SLUG>
| Argument | Description |
|---|
<SLUG> | Customer slug (e.g. acme) |
| Option | Description |
|---|
--editor <EDITOR> | Editor command; defaults to [ui].editor, then $VISUAL / $EDITOR |
rupu customer archive
Hide a customer from pickers; its projects keep running
rupu customer archive [OPTIONS] <SLUG>
| Argument | Description |
|---|
<SLUG> | Customer slug (e.g. acme) |
rupu customer unarchive
Restore an archived customer to pickers
rupu customer unarchive [OPTIONS] <SLUG>
| Argument | Description |
|---|
<SLUG> | Customer slug (e.g. acme) |
rupu customer delete
Delete a customer. Refused while any project is assigned
rupu customer delete [OPTIONS] <SLUG>
| Argument | Description |
|---|
<SLUG> | Customer slug (e.g. acme) |
rupu customer assign
Assign a project (default: the current directory)
rupu customer assign [OPTIONS] <SLUG>
| Argument | Description |
|---|
<SLUG> | Customer slug (e.g. acme) |
| Option | Description |
|---|
--project <PROJECT> | A project directory or workspace id (ws_…) |
rupu customer unassign
Remove a project's customer (default: the current directory)
rupu customer unassign [OPTIONS]
| Option | Description |
|---|
--project <PROJECT> | A project directory or workspace id (ws_…) |
rupu ui
Manage UI themes and palette imports
rupu ui [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
themes | List available UI themes |
theme | Manage a specific palette theme |
rupu ui themes
List available UI themes
rupu ui themes [OPTIONS]
rupu ui theme
Manage a specific palette theme
rupu ui theme [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
show | Show one theme in detail |
validate | Validate a theme file on disk |
import | Import a theme from a local file or URL |
rupu ui theme show
Show one theme in detail
rupu ui theme show [OPTIONS] <NAME>
| Argument | Description |
|---|
<NAME> | Theme name, as listed by rupu ui themes |
rupu ui theme validate
Validate a theme file on disk
rupu ui theme validate [OPTIONS] <PATH>
| Argument | Description |
|---|
<PATH> | Path to the theme file to check |
rupu ui theme import
Import a theme from a local file or URL
rupu ui theme import [OPTIONS] <SOURCE>
| Argument | Description |
|---|
<SOURCE> | Local path or URL to a theme file |
| Option | Description |
|---|
--from <FROM> | Import format. auto tries native rupu theme first, then Base16 [default: auto] [possible values: auto, rupu, base16] |
--name <NAME> | Override the installed theme name |
--project | Install the theme under the current project's .rupu/themes/ |
rupu cleanup
Prune archived local sessions and transcripts
rupu cleanup [OPTIONS]
| Option | Description |
|---|
--stats | Show cleanup inventory instead of deleting archived resources |
--older-than <DURATION> | Retention cutoff override for every selected resource, e.g. 30d, 12h, or 1w |
--dry-run | Preview deletions without removing files |
--sessions | Only clean archived sessions |
--transcripts | Only clean archived standalone transcripts |
rupu auth
Manage provider credentials
rupu auth [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
login | Store credentials for a provider |
logout | Remove a stored credential |
status | Show configured providers + backend |
backend | Show where credentials are stored |
rupu auth login
Store credentials for a provider
rupu auth login [OPTIONS] --account <ACCOUNT>
| Option | Description |
|---|
--account <ACCOUNT> | Account name — the identity. Use a distinct name per identity (e.g. anthropic-work, anthropic-personal). A bare vendor name (anthropic) is the single-account default |
--kind <KIND> | Vendor this account authenticates against (anthropic | openai | gemini | copilot | github | gitlab | linear | jira | local). Required the first time an account name is used; inferred from config or from the account name afterwards |
--mode <MODE> | Authentication mode [default: api-key] [possible values: api-key, sso] |
--key <KEY> | API key (only valid with --mode api-key). If omitted, reads from stdin |
rupu auth logout
Remove a stored credential
rupu auth logout [OPTIONS]
| Option | Description |
|---|
--account <ACCOUNT> | Account name (omit with --all to clear everything) |
--mode <MODE> | Specific auth mode to remove. If omitted, both api-key and sso for that provider are removed [possible values: api-key, sso] |
--all | Remove every stored credential across all providers and modes |
--yes | Skip the confirmation prompt for --all |
rupu auth status
Show configured providers + backend
rupu auth status [OPTIONS]
rupu auth backend
Show where credentials are stored. There is one backend: a chmod-600 JSON file at ~/.rupu/auth.json. The OS keychain backend was retired.
rupu auth backend [OPTIONS]
| Option | Description |
|---|
--use <KIND> | file — the only supported value, and already in effect. Accepted so existing scripts keep working; keychain is refused with an explanation. Omit to print where credentials currently live |
--view <VIEW> | Human snapshot density (focused | compact | full) [default: full] [possible values: focused, compact, full] |
--no-color | Disable colored output |
--pager | Force pager. Default: page when stdout is a tty |
--no-pager | Disable pager |
rupu models
List or refresh available models
rupu models [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
list | List available models (custom + cached + baked-in) |
refresh | Re-fetch live model lists from each provider |
rupu models list
List available models (custom + cached + baked-in)
rupu models list [OPTIONS]
| Option | Description |
|---|
--provider <PROVIDER> | Filter output to a single provider |
rupu models refresh
Re-fetch live model lists from each provider
rupu models refresh [OPTIONS]
| Option | Description |
|---|
--provider <PROVIDER> | Limit refresh to a single provider |
rupu netflow
Manage per-run netflow ledgers (retention / pruning)
rupu netflow [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
show | Print one run's netflow flow records |
prune | Delete per-run netflow ledgers older than a cutoff |
rupu netflow show
Print one run's netflow flow records
rupu netflow show [OPTIONS] <RUN_ID>
| Argument | Description |
|---|
<RUN_ID> | Full run id (run_<ULID>) whose netflow ledger to print |
rupu netflow prune
Delete per-run netflow ledgers older than a cutoff
rupu netflow prune [OPTIONS]
| Option | Description |
|---|
--older-than <DURATION> | Retention cutoff, e.g. 30d, 12h, or 1w. Must be positive — 0s or a negative value is rejected, not treated as "everything". Defaults to 30d (mirrors transcript prune's own fallback) when omitted. A ledger is matched by file mtime, but a ledger whose run is still live is never deleted however old it is: a workflow run that is not finished (and whose recorded runner pid, if any, is alive) protects its own, its steps', its fan-out units' and its sub-agents' ledgers, and a standalone rupu run whose process is alive protects its own and its sub-agents'. Such ledgers are listed as skipped_live. Anything modified in roughly the last hour is never eligible regardless of what you pass here |
--dry-run | Preview deletions without removing files. Always cheap to run first — the default (no flag) deletes immediately, same as transcript prune |
rupu repos
SCM repository operations
rupu repos [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
list | List repositories accessible via configured SCM platforms |
attach | Attach a local checkout to a repo ref in the local registry |
prefer | Mark one tracked checkout as the preferred path for a repo |
tracked | List locally tracked repo checkouts |
forget | Forget a tracked repo or one tracked path |
rupu repos list
List repositories accessible via configured SCM platforms
rupu repos list [OPTIONS]
| Option | Description |
|---|
--platform <PLATFORM> | Filter to one platform (github | gitlab). Default: all |
--no-color | Disable colored output (also honored: NO_COLOR env, [ui].color = "never" in config) |
rupu repos attach
Attach a local checkout to a repo ref in the local registry
rupu repos attach [OPTIONS] <REPO> [PATH]
| Argument | Description |
|---|
<REPO> | Repo target in the run-target syntax (e.g. github:Section9Labs/rupu) |
[PATH] | Local checkout path. Defaults to the current working directory |
rupu repos prefer
Mark one tracked checkout as the preferred path for a repo
rupu repos prefer [OPTIONS] <REPO> [PATH]
| Argument | Description |
|---|
<REPO> | Repo target in the run-target syntax (e.g. github:Section9Labs/rupu) |
[PATH] | Local checkout path. Defaults to the current working directory |
rupu repos tracked
List locally tracked repo checkouts
rupu repos tracked [OPTIONS]
| Option | Description |
|---|
--no-color | Disable colored output |
rupu repos forget
Forget a tracked repo or one tracked path
rupu repos forget [OPTIONS] <REPO>
| Argument | Description |
|---|
<REPO> | Repo target in the run-target syntax (e.g. github:Section9Labs/rupu) |
| Option | Description |
|---|
--path <PATH> | Remove only this local path from the tracked repo. When omitted, the entire tracked repo record is deleted |
rupu scm
Multi-account SCM routing: rules and the account roster
rupu scm [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
bind | Add an account-selection rule: route repos under an owner glob, or checkouts under a path glob, to a named account |
accounts | List configured SCM accounts: kind, base_url, and which rules point at them |
rupu scm bind
Add an account-selection rule: route repos under an owner glob, or checkouts under a path glob, to a named account
rupu scm bind [OPTIONS] --account <ACCOUNT> <--owner <OWNER>|--path <PATH>>
| Option | Description |
|---|
--owner <OWNER> | Owner glob this rule matches (e.g. acme/* or acme). Matched against RepoRef.owner — the tier that works for daemons, which know the owner but have no cwd. Mutually exclusive with --path; exactly one is required |
--path <PATH> | Filesystem-path glob this rule matches against the caller's cwd (e.g. ~/Code/work/*). Mutually exclusive with --owner |
--account <ACCOUNT> | The account this rule selects |
rupu scm accounts
List configured SCM accounts: kind, base_url, and which rules point at them
rupu scm accounts [OPTIONS]
rupu session
Persistent agent sessions
rupu session [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
start | Start a persistent agent session |
list | List persistent agent sessions |
show | Show session details |
usage-timeline | Per-turn token series across every run this session recorded |
archive | Archive an inactive session and its owned transcripts |
restore | Restore an archived session and its owned transcripts |
delete | Permanently delete a session and its owned transcripts |
prune | Delete archived sessions older than a cutoff |
send | Send a follow-up prompt to an existing session |
attach | Attach to the current or last run in a session |
stop | Stop an active session worker |
compact | Compact a session's stored conversation (summarize older turns now) |
rupu session start
Start a persistent agent session
rupu session start [OPTIONS] <AGENT> [TARGET] [PROMPT]
| Argument | Description |
|---|
<AGENT> | Agent name (matches an agents/*.md file) |
[TARGET] | Optional target reference, e.g. github:owner/repo#42 |
[PROMPT] | Optional initial user message. Defaults to go if omitted. Leading /skill tokens invoke those skills in the first turn |
| Option | Description |
|---|
--prompt <PROMPT_FLAG> | Initial user message via flag (preferred over the positional prompt; lets a caller pass a prompt without it being parsed as a target) |
--mode <MODE> | Override permission mode (ask | bypass | readonly) |
--no-stream | Don't render tokens as they arrive, for every turn in this session. The request still streams on the wire, so long responses can't hit the request timeout |
--into <PATH> | For repo targets: clone into this directory instead of ./<repo>/ |
--detach | Start the first turn without auto-attaching |
--view <VIEW> | Live renderer mode when auto-attaching [possible values: focused, compact, full] |
--engagement-profile <ID> | Engagement profile(s) every turn of the session runs under — the asset domain(s) findings are validated against (e.g. network, binary). Repeatable or comma-separated. Empty = the code path [aliases: --engagement-profiles] |
--skill <SKILL> | A skill every turn of the session is given beside the agent's own (name, global:name or project:name). Repeatable |
--preload-skill <SKILL> | A skill whose instructions go into the session's system prompt. Repeatable |
Session skills. A session fixes its skills when it starts:
start --skill /
--preload-skill add to the agent’s own, and every turn sends the same skills section.
send --skill <name> (or a leading
/name in the prompt) invokes any installed skill for that one turn, granted or not; the prompt is optional when a skill is given. See
Skills.
rupu session list
List persistent agent sessions
rupu session list [OPTIONS]
| Option | Description |
|---|
--all | Include both active and archived sessions |
--archived | Show only archived sessions |
rupu session show
Show session details
rupu session show [OPTIONS] <SESSION_ID>
| Argument | Description |
|---|
<SESSION_ID> | Session id (ses_<ULID>), a unique prefix, or a codename |
| Option | Description |
|---|
--view <VIEW> | [possible values: focused, compact, full] |
--no-color | Disable colored output (also honored: NO_COLOR env var) |
--pager | Force pager. Default: page when stdout is a tty |
--no-pager | Disable pager |
rupu session usage-timeline
Per-turn token series across every run this session recorded
rupu session usage-timeline [OPTIONS] <SESSION_ID>
| Argument | Description |
|---|
<SESSION_ID> | Session id (ses_<ULID>), a unique prefix, or a codename |
rupu session archive
Archive an inactive session and its owned transcripts
rupu session archive [OPTIONS] <SESSION_ID>
| Argument | Description |
|---|
<SESSION_ID> | Session id (ses_<ULID>), a unique prefix, or a codename |
rupu session restore
Restore an archived session and its owned transcripts
rupu session restore [OPTIONS] <SESSION_ID>
| Argument | Description |
|---|
<SESSION_ID> | Session id (ses_<ULID>), a unique prefix, or a codename |
rupu session delete
Permanently delete a session and its owned transcripts
rupu session delete [OPTIONS] <SESSION_ID>
| Argument | Description |
|---|
<SESSION_ID> | Session id (ses_<ULID>), a unique prefix, or a codename |
| Option | Description |
|---|
--force | Confirm the permanent deletion (required). A session whose worker is still running is refused even with --force; stop it first |
rupu session prune
Delete archived sessions older than a cutoff
rupu session prune [OPTIONS]
| Option | Description |
|---|
--older-than <DURATION> | Retention cutoff, e.g. 30d, 12h, or 1w |
--dry-run | Preview deletions without removing files |
rupu session send
Send a follow-up prompt to an existing session
rupu session send [OPTIONS] <SESSION_ID> [PROMPT]
| Argument | Description |
|---|
<SESSION_ID> | Session id (ses_<ULID>), a unique prefix, or a codename |
[PROMPT] | Follow-up prompt to send as the session's next turn. Optional when the turn invokes a skill. Leading /skill tokens (/pdf summarize it) invoke those skills, as --skill does |
| Option | Description |
|---|
--skill <SKILL> | A skill to invoke in this turn (name, global:name or project:name): any installed skill, granted or not. Its instructions go ahead of the prompt, and the session may load it from then on. Repeatable |
--detach | Start the turn without auto-attaching |
--view <VIEW> | Live renderer mode when auto-attaching [possible values: focused, compact, full] |
rupu session attach
Attach to the current or last run in a session
rupu session attach [OPTIONS] <SESSION_ID>
| Argument | Description |
|---|
<SESSION_ID> | Session id (ses_<ULID>), a unique prefix, or a codename |
| Option | Description |
|---|
--view <VIEW> | [possible values: focused, compact, full] |
rupu session stop
Stop an active session worker
rupu session stop [OPTIONS] <SESSION_ID>
| Argument | Description |
|---|
<SESSION_ID> | Session id (ses_<ULID>), a unique prefix, or a codename |
rupu session compact
Compact a session's stored conversation (summarize older turns now)
rupu session compact [OPTIONS] <SESSION_ID>
| Argument | Description |
|---|
<SESSION_ID> | Session id (ses_<ULID>), a unique prefix, or a codename |
| Option | Description |
|---|
--window <WINDOW> | Context-window size (tokens) to size compaction against. Overrides the session's stored contextWindowTokens; required for sessions created before that field existed |
rupu issues
Issue-tracker operations (list / show / run a workflow)
rupu issues [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
list | List issues for a repo. Auto-detects repo from cwd's origin remote when --repo is omitted |
show | Show one issue's full body + metadata |
run | Convenience: run a workflow with an issue run-target. Equivalent to rupu workflow run <name> <issue-ref> (the run-target is a positional on workflow run, not a flag) |
rupu issues list
List issues for a repo. Auto-detects repo from cwd's origin remote when --repo is omitted
rupu issues list [OPTIONS]
| Option | Description |
|---|
--repo <REPO> | Repo target in the run-target syntax (e.g. github:Section9Labs/rupu). When omitted, auto-detected from the cwd's git origin remote |
--state <STATE> | Filter by state. open (default) | closed | all [default: open] |
--label <LABELS> | Filter by label. Repeatable; matched as AND |
--labels <LABELS_CSV> | Comma-separated label list (alternative to repeating --label). AND semantics — all listed labels must be present |
--limit <LIMIT> | Cap on returned issues. Default: 50 [default: 50] |
--no-color | Disable colored output (also honored: NO_COLOR env var, [ui].color = "never" in config) |
--account <ACCOUNT> | Which configured SCM account to use, when more than one is configured for this platform (e.g. two GitHub accounts). Skips the owner/path rule engine entirely. Errors on an unknown name |
rupu issues show
Show one issue's full body + metadata
rupu issues show [OPTIONS] <REF>
| Argument | Description |
|---|
<REF> | Issue ref in run-target syntax (e.g. github:Section9Labs/rupu/issues/42). May omit the <owner>/<repo> portion if cwd has a detectable remote — #42 or 42 alone resolves against that |
| Option | Description |
|---|
--no-color | Disable colored output |
--pager | Force pager. Default: page when stdout is a tty |
--no-pager | Disable pager |
--account <ACCOUNT> | Which configured SCM account to use, when more than one is configured for this platform. Skips the owner/path rule engine |
rupu issues run
Convenience: run a workflow with an issue run-target. Equivalent to rupu workflow run <name> <issue-ref> (the run-target is a positional on workflow run, not a flag)
rupu issues run [OPTIONS] <WORKFLOW> <REF>
| Argument | Description |
|---|
<WORKFLOW> | Workflow filename stem under .rupu/workflows/ (or <global>/workflows/). Same name rupu workflow run accepts |
<REF> | Issue ref. Same shorthand rules as show |
| Option | Description |
|---|
--mode <MODE> | Override permission mode (ask | bypass | readonly) |
rupu init
Bootstrap a new rupu project (.rupu/agents, .rupu/workflows, .rupu/netflow, config)
rupu init [OPTIONS] [PATH]
| Argument | Description |
|---|
[PATH] | Target directory for the new project. Defaults to the current working directory [default: .] |
| Option | Description |
|---|
--with-samples | Include the curated agent + workflow templates |
--force | Overwrite existing template files (still merges by default) |
--git | Run git init afterwards if the target is not already inside a git repo |
rupu mcp
Deprecated: mcp serve runs rupu cp serve --no-web (the MCP over HTTP at /mcp)
rupu mcp [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
serve | Deprecated: runs rupu cp serve --no-web (MCP over HTTP) |
rupu mcp serve
Deprecated: runs rupu cp serve --no-web (MCP over HTTP)
rupu mcp serve [OPTIONS]
| Option | Description |
|---|
--transport <TRANSPORT> | Ignored: stdio is no longer supported, the MCP is HTTP only [possible values: stdio, http] |
--tools <TOOLS> | The tools to serve, in the agent tools: grammar: exact names, legacy aliases, ns.*, core.* or * (comma-separated or repeated). Passed to rupu cp serve --tools |
--mode <MODE> | Ignored: every tool is served and your MCP client's permissions decide what runs |
Deprecated. rupu mcp serve prints a deprecation notice and runs
rupu cp serve --no-web on
127.0.0.1:7878;
--transport and
--mode are ignored and
--tools is passed on. stdio is gone: point clients at
http://127.0.0.1:7878/mcp (a client that only speaks stdio can use
mcp-remote). See
MCP & tools.
rupu coverage
Inspect agentic coverage ledgers and concern catalogs
rupu coverage [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
list | List coverage targets recorded under .rupu/coverage/ |
templates | List or show bundled concern templates |
catalog | Print the effective catalog snapshot for a target |
show | Show the derived ledger view (touched files + assertions + findings) |
audit | Generate the coverage audit report for a target |
gap | Show only the coverage gaps (in-scope files lacking an assertion) |
diff | Diff two runs against a target (defaults to previous latest) |
runs | List the runs recorded against a target (to find ids to diff) |
rerun | Replay an agent run by id, appending a new run to the same target |
rupu coverage list
List coverage targets recorded under .rupu/coverage/
rupu coverage list [OPTIONS]
rupu coverage templates
List or show bundled concern templates
rupu coverage templates [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
list | List bundled template names |
show | Print a bundled template's concerns |
rupu coverage templates list
List bundled template names
rupu coverage templates list [OPTIONS]
rupu coverage templates show
Print a bundled template's concerns
rupu coverage templates show [OPTIONS] <NAME>
| Argument | Description |
|---|
<NAME> | Template name, as listed by rupu coverage templates list |
rupu coverage catalog
Print the effective catalog snapshot for a target
rupu coverage catalog [OPTIONS] <TARGET_ID>
| Argument | Description |
|---|
<TARGET_ID> | Target id (from coverage list) |
rupu coverage show
Show the derived ledger view (touched files + assertions + findings)
rupu coverage show [OPTIONS] <TARGET_ID>
| Argument | Description |
|---|
<TARGET_ID> | Target id (from coverage list) |
rupu coverage audit
Generate the coverage audit report for a target
rupu coverage audit [OPTIONS] <TARGET_ID>
| Argument | Description |
|---|
<TARGET_ID> | Target id (from coverage list) |
rupu coverage gap
Show only the coverage gaps (in-scope files lacking an assertion)
rupu coverage gap [OPTIONS] <TARGET_ID>
| Argument | Description |
|---|
<TARGET_ID> | Target id (from coverage list) |
rupu coverage diff
Diff two runs against a target (defaults to previous latest)
rupu coverage diff [OPTIONS] <TARGET_ID> [BASE] [COMPARE]
| Argument | Description |
|---|
<TARGET_ID> | Target id (from coverage list) |
[BASE] | Base run selector: a run id, latest, or previous |
[COMPARE] | Compare run selector: a run id, latest, or previous |
rupu coverage runs
List the runs recorded against a target (to find ids to diff)
rupu coverage runs [OPTIONS] <TARGET_ID>
| Argument | Description |
|---|
<TARGET_ID> | Target id (from coverage list) |
rupu coverage rerun
Replay an agent run by id, appending a new run to the same target
rupu coverage rerun [OPTIONS] <TARGET_ID> <RUN_ID>
| Argument | Description |
|---|
<TARGET_ID> | Target id (from coverage list) |
<RUN_ID> | Run id to replay (from coverage runs) |
rupu fleet
Install the stock security-assessment fleet (the generic agents + workflows the built-in engagement profiles name) into ~/.rupu
rupu fleet [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
install | Install the stock fleet (agents + workflows) onto disk |
list | List the agents and workflows the stock fleet ships |
rupu fleet install
Install the stock fleet (agents + workflows) onto disk
rupu fleet install [OPTIONS]
| Option | Description |
|---|
--force | Overwrite fleet files that already exist (default: keep them) |
--project | Install into the current project's .rupu/ instead of the global ~/.rupu |
rupu fleet list
List the agents and workflows the stock fleet ships
rupu fleet list [OPTIONS]
rupu skill
Agent Skills: install, update, list, show and validate SKILL.md skills
rupu skill [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
list | List installed skills in both layers |
show | Show one skill: frontmatter, files, fingerprints and source. Accepts global:<name> / project:<name> |
validate | Check skills against the Agent Skills format; exit 1 on any failure |
install | Install skills from a directory, owner/repo, a GitHub tree URL, or an https git URL (#path narrows to a folder in the repository) |
update | Re-fetch installed skills from the source they were installed from |
rupu skill list
List installed skills in both layers
rupu skill list [OPTIONS]
| Option | Description |
|---|
--project | Only the project layer |
rupu skill show
Show one skill: frontmatter, files, fingerprints and source. Accepts global:<name> / project:<name>
rupu skill show [OPTIONS] <NAME>
| Argument | Description |
|---|
<NAME> | |
rupu skill validate
Check skills against the Agent Skills format; exit 1 on any failure
rupu skill validate [OPTIONS] [NAME]
| Argument | Description |
|---|
[NAME] | |
rupu skill install
Install skills from a directory, owner/repo, a GitHub tree URL, or an https git URL (#path narrows to a folder in the repository)
rupu skill install [OPTIONS] <SOURCE>
| Argument | Description |
|---|
<SOURCE> | |
| Option | Description |
|---|
--ref <GIT_REF> | Branch, tag or commit to install from |
--skill <SKILLS> | Install this skill from a source that holds several (repeatable) |
--all | Install every valid skill in the source |
--list | List the skills in the source; install nothing |
--project | Install into the current project's .rupu/skills instead of ~/.rupu/skills |
--force | Replace installed skills of the same name |
rupu skill update
Re-fetch installed skills from the source they were installed from
rupu skill update [OPTIONS] [NAMES]...
| Argument | Description |
|---|
[NAMES]... | |
| Option | Description |
|---|
--all | Every installed skill with a source record |
--project | The project layer instead of the global one |
--force | Replace skills whose installed copy was edited |
Names and sources. show takes a bare name (every layer that has it) or a
global: /
project: prefixed one.
install takes an existing path,
owner/repo, a GitHub tree URL, or any
https:// git URL with an optional
#<path>; only
https:// is fetched.
list supports
--format json|csv. See
Skills.
rupu findings
Finding reports: the embedded report schema, and report exports
rupu findings [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
schema | Print the finding report JSON Schema embedded in this build |
export | Export findings as a report: one finding, or a project report |
import | Attach reports written before the full profile to their findings |
list | List findings matching a query, e.g. severity>=high -tag:noise |
tag | Add or remove tags on findings |
tags | List the tags in use, with how many findings carry each (optionally only on the findings a query selects) |
rupu findings schema
Print the finding report JSON Schema embedded in this build
rupu findings schema [OPTIONS]
| Option | Description |
|---|
--advertised | Print the simplified copy used in tool definitions instead |
rupu findings export
Export findings as a report: one finding, or a project report. A single --id with no other selection writes that finding as a stand-alone document; anything else writes one report over the selection, or with --split a zip holding an index and one file per finding. Findings are numbered within their project (SEC-001, …) before the selection is applied, so a finding keeps its number whatever else is left out. The number prefix is [findings].export_id_prefix in the GLOBAL config (~/.rupu/config.toml); a project's .rupu/config.toml never changes it.
rupu findings export [OPTIONS] --output <PATH>
| Option | Description |
|---|
--id <FINDING_ID> | Export this finding (repeatable) |
--project <WS_ID|PATH> | Only this project: a workspace id, or the path of its checkout |
--run <RUN_ID> | Only the findings a run (and its sub-runs) declared |
--severity <SEVERITY> | Only this severity and worse [possible values: critical, high, medium, low, info] |
--owner <OWNER> | Only findings whose report names this owner |
--cwe <CWE-N> | Only findings for this CWE (e.g. CWE-79), compared by number: CWE-79 never selects CWE-798 |
--include-summaries | Keep findings recorded without a full report (left out by default) |
--split | Write a zip of one file per finding plus an index |
--title <TITLE> | Title of the project report (default: "Findings report") |
--to <TO> | Document format [default: md] [possible values: md, html, pdf] |
-o, --output <PATH> | Where to write the report. An existing directory receives the generated file name |
rupu findings import
Attach reports written before the full profile to their findings. A one-time migration aid: reads Markdown finding reports in the report layout, and attaches each to the summary finding its Finding ID: line names (also read: Native Finding:, Rupu Finding ID: and similar labels; an id mentioned only in prose is never used). The finding becomes a full-profile finding. A report attaches whole or not at all; a finding that already has a report is left alone; each changed ledger is backed up first (findings.jsonl.pre-import-<time>).
rupu findings import [OPTIONS] <PATH>...
| Argument | Description |
|---|
<PATH>... | Report files, or directories to search for *.md files |
| Option | Description |
|---|
--id <FINDING_ID> | The finding a single report belongs to, for a report with no Finding ID: line. Only with one file; refused when the report's own Finding ID: line names a different finding |
--dry-run | Parse and validate every report, check that the artifacts it lists exist and that it is within the size limits once they are recorded; write nothing (no ledger change, backup or lock file). No artifact is copied (only its first 8 KiB is read), so trouble found only while copying one shows up only on a real import |
rupu findings list
List findings matching a query, e.g. severity>=high -tag:noise. Put flags (--ids-only, --limit) before the query words.
rupu findings list [OPTIONS] [QUERY]...
| Argument | Description |
|---|
[QUERY]... | Findings query, e.g. severity>=high tag:class:sqli -tag:false-positive. Several words are joined with spaces; quote anything with >, < or spaces for your shell. Keys: severity (>=,>,<=,<), tag, has, project, cwe, owner, product, verified, profile, scope, concern, agent, workflow, file, run, id; bare words search title/summary/id/file. Put flags before the query words |
| Option | Description |
|---|
--limit <N> | Show at most N findings; how many were left out goes to stderr |
--ids-only | Print only the finding ids, one per line |
rupu findings tag
Add or remove tags on findings. Tags are free-form: lowercase a-z, 0-9 and . _ : / -, starting with a letter or digit, at most 64 characters (Needs-POC is stored as needs-poc). Give - as the only id to read ids from stdin, one per line: rupu findings list --ids-only tag:class:sqli | rupu findings tag - --add needs-poc. Findings in different projects are changed project by project; an unknown id fails the command after the rest are changed.
rupu findings tag [OPTIONS] <FINDING_ID>...
| Argument | Description |
|---|
<FINDING_ID>... | Finding ids, or - alone to read them from stdin |
| Option | Description |
|---|
--add <TAG> | Tag to add (repeatable) |
--remove <TAG> | Tag to remove (repeatable) |
List the tags in use, with how many findings carry each (optionally only on the findings a query selects)
rupu findings tags [OPTIONS] [QUERY]...
| Argument | Description |
|---|
[QUERY]... | Count only the tags on findings this query selects (same syntax as findings list) |
rupu cron
Schedule-driven workflow firing (designed for system cron)
rupu cron [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
list | List every cron-triggered workflow + its schedule + next-fire time. Read-only; doesn't update state |
tick | Walk all workflows, fire any whose schedule matches between the persisted last_fired and now. Designed to run from system cron at 1-minute granularity |
events | Read-only inspection of event-triggered workflows |
rupu cron list
List every cron-triggered workflow + its schedule + next-fire time. Read-only; doesn't update state
rupu cron list [OPTIONS]
| Option | Description |
|---|
--no-color | Disable colored output (also honored: NO_COLOR env, [ui].color = "never" in config) |
rupu cron tick
Walk all workflows, fire any whose schedule matches between the persisted last_fired and now. Designed to run from system cron at 1-minute granularity
rupu cron tick [OPTIONS]
| Option | Description |
|---|
--dry-run | Don't actually run workflows or update state; just print what would fire. Useful for verifying a crontab line |
--skip-events | Run only the cron-scheduled tier; skip event polling. Useful for crontab lines that want predictable cost |
--only-events | Run only the event-polling tier; skip cron-scheduled fires. Useful for splitting tick frequencies (cron at 1 min, events at 5 min) |
rupu cron events
Read-only inspection of event-triggered workflows. Prints each workflow's name, target event id, sources from [triggers].poll_sources, and the most recent persisted cursor across those sources.
rupu cron events [OPTIONS]
| Option | Description |
|---|
--no-color | Disable colored output |
rupu webhook
Webhook receiver for event-triggered workflows (GitHub / GitLab)
rupu webhook [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
serve | Run the webhook HTTP receiver in the foreground |
rupu webhook serve
Run the webhook HTTP receiver in the foreground
rupu webhook serve [OPTIONS]
| Option | Description |
|---|
--addr <ADDR> | Address to bind. Defaults to 127.0.0.1:8080. Use 0.0.0.0 to expose externally (only do this behind a reverse proxy that terminates TLS — rupu does not) [default: 127.0.0.1:8080] |
rupu cp
Control-plane HTTP server for the rupu web UI
rupu cp [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
serve | Start the control-plane HTTP server |
rupu cp serve
Start the control-plane HTTP server. Also runs three in-process background loops on a timer, not just the HTTP server: the autoflow reconciler, the cron/event-trigger tick, and the gate sweep (enforces gate on_timeout routing and reaps orphaned runs with a dead runner_pid). Each loop is gated by a [cp] config key and defaults to enabled at a 60s interval: autoflow_reconcile_enabled, cron_tick_enabled, gate_sweep_enabled (see rupu-config's CpConfig). Exits non-zero immediately if the bind address is already taken; when the occupant is another rupu control plane, the error names its PID.
rupu cp serve [OPTIONS]
| Option | Description |
|---|
--bind <BIND> | Address to bind. Defaults to 127.0.0.1:7878 [default: 127.0.0.1:7878] |
--token <TOKEN> | Optional access token. If set, every /api/* call needs it, as Authorization: Bearer <token> or the browser's token cookie. The printed (and auto-opened) URL carries ?token=<token>; opening it signs that browser in (cookie set, token dropped from the URL). /healthz and the page shell stay open; the UI shows no data until the browser is signed in |
--no-open | Do not open the served URL in a browser on startup. By default the URL is opened when running interactively (a terminal); the URL is always printed regardless |
--no-web | Serve no web UI or page shell: /api/*, /healthz and /mcp only. Implies --no-open |
--no-mcp | Do not serve the MCP endpoint (/mcp is a 404) |
--tools <TOOLS> | Narrow the MCP to these tools (exact names, ns.*, *; comma-separated). Default: every tool |
Serve modes. rupu cp serve serves the web UI,
/api and
/mcp;
--no-web serves
/api and
/mcp only (and implies
--no-open);
--no-mcp serves the web UI and
/api only.
--no-web --no-mcp is refused (nothing to serve), and so is
--tools with
--no-mcp; a bad
--tools grant fails before the socket is bound.
/mcp sits behind the same
--token as
/api. See
MCP & tools.
rupu usage
Aggregate token spend across persisted transcripts
rupu usage [OPTIONS] [COMMAND]
| Subcommand | Description |
|---|
runs | Show per-run usage rows |
backfill | Backfill metadata sidecars for older standalone transcripts |
| Option | Description |
|---|
--since <SINCE> | Only count runs whose started_at is at or after this timestamp. RFC-3339 / ISO-8601 (2026-05-01T00:00:00Z) or relative (7d, 24h, 30m) |
--until <UNTIL> | Only count runs whose started_at is at or before this timestamp |
--repo <REPO> | Filter to one repo ref, for example github:Section9Labs/rupu |
--issue <ISSUE> | Filter to one issue ref, for example github:Section9Labs/rupu/issues/42 |
--workflow <WORKFLOW> | Filter to one workflow name |
--agent <AGENT> | Filter to one agent name |
--provider <PROVIDER> | Filter to one provider id |
--model <MODEL> | Filter to one model id |
--worker <WORKER> | Filter to one worker id |
--backend <BACKEND> | Filter to one backend id |
--trigger <TRIGGER> | Filter to one trigger source (run_cli, workflow_cli, autoflow, ...) |
--group-by <GROUP_BY> | Group the main report by one dimension [default: composite] [possible values: composite, provider, model, agent, workflow, repo, day] |
rupu usage runs
Show per-run usage rows
rupu usage runs [OPTIONS]
| Option | Description |
|---|
--since <SINCE> | Only count runs whose started_at is at or after this timestamp. RFC-3339 / ISO-8601 (2026-05-01T00:00:00Z) or relative (7d, 24h, 30m) |
--until <UNTIL> | Only count runs whose started_at is at or before this timestamp |
--repo <REPO> | Filter to one repo ref, for example github:Section9Labs/rupu |
--issue <ISSUE> | Filter to one issue ref, for example github:Section9Labs/rupu/issues/42 |
--workflow <WORKFLOW> | Filter to one workflow name |
--agent <AGENT> | Filter to one agent name |
--provider <PROVIDER> | Filter to one provider id |
--model <MODEL> | Filter to one model id |
--worker <WORKER> | Filter to one worker id |
--backend <BACKEND> | Filter to one backend id |
--trigger <TRIGGER> | Filter to one trigger source (run_cli, workflow_cli, autoflow, ...) |
--failed | Only show failed runs |
--status <STATUS> | Filter to one run status |
--top-cost <TOP_COST> | Show only the N most expensive runs |
rupu usage backfill
Backfill metadata sidecars for older standalone transcripts
rupu usage backfill [OPTIONS]
| Option | Description |
|---|
--force | Rewrite existing standalone sidecars instead of skipping them |
rupu watch
Re-attach to an existing run
rupu watch [OPTIONS] <RUN_ID>
| Argument | Description |
|---|
<RUN_ID> | Run id (e.g. run_01HZ…) |
| Option | Description |
|---|
--replay | Replay a finished run instead of tailing live |
--pace <PACE> | Replay pace in events per second (only with --replay) [default: 10] |
--view <VIEW> | Live view density for retained watch screens [possible values: focused, compact, full] |
--follow | Follow a live run (tail mode). Re-scans the transcript dir every 250ms until the run reaches a terminal state |
rupu completions
Generate or install shell-completion scripts
rupu completions [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
print | Print a completion script for the given shell to stdout |
install | Write the completion script to the canonical location for the given shell. If --shell is omitted, auto-detect from $SHELL (best-effort) |
rupu completions print
Print a completion script for the given shell to stdout
rupu completions print [OPTIONS] <SHELL>
| Argument | Description |
|---|
<SHELL> | Target shell [possible values: bash, elvish, fish, powershell, zsh] |
| Option | Description |
|---|
--static | Emit a static, self-contained script (no runtime callbacks). Drops dynamic agent / workflow name completion in exchange for offline-installable output. Default: dynamic bootstrap |
rupu completions install
Write the completion script to the canonical location for the given shell. If --shell is omitted, auto-detect from $SHELL (best-effort)
rupu completions install [OPTIONS]
| Option | Description |
|---|
--shell <SHELL> | Target shell. Auto-detected from $SHELL when omitted [possible values: bash, elvish, fish, powershell, zsh] |
--path <PATH> | Install path override. Defaults to the conventional location for the target shell (printed at the end of the run) |
--static | Install the static script (see print --static). Default: dynamic bootstrap |
rupu host
Manage named rupu-cp hosts (add / list / remove)
rupu host [OPTIONS] <COMMAND>
| Subcommand | Description |
|---|
add | Register a remote rupu-cp host |
list | List configured hosts (local is always shown first) |
remove | Remove a host by id |
rupu host add
Register a remote rupu-cp host
rupu host add [OPTIONS] <NAME>
| Argument | Description |
|---|
<NAME> | Display name for the host |
| Option | Description |
|---|
--url <URL> | Base URL of the remote rupu-cp instance (e.g. https://rupu.example.com). Mutually exclusive with --ssh and --bucket |
--ssh <SSH> | SSH destination: user@host or an ~/.ssh/config alias. Selects the Ssh transport. Mutually exclusive with --url and --bucket |
--port <PORT> | SSH port override (default: 22). Only relevant with --ssh |
--identity <IDENTITY> | Path to an SSH identity file. Only relevant with --ssh |
--bucket <BUCKET> | Object-store URL for the bucket transport (s3://… / gs://… / file://…). Selects the Bucket transport. Mutually exclusive with --url and --ssh. Credentials come from the environment / cloud credential chain and are never stored |
--prefix <PREFIX> | Object-store key prefix (optional). Only relevant with --bucket |
--token <TOKEN> | API token. Mutually exclusive with --token-stdin. Only relevant with --url |
--token-stdin | Read the API token from stdin (one line). Mutually exclusive with --token |
rupu host list
List configured hosts (local is always shown first)
rupu host list [OPTIONS]
rupu host remove
Remove a host by id
rupu host remove [OPTIONS] <ID>
| Argument | Description |
|---|
<ID> | Id of the host to remove (e.g. host_01J...) |
rupu node
Dial-home tunnel agent + node enrollment
rupu node [OPTIONS] [COMMAND]
| Subcommand | Description |
|---|
enroll | Enroll a new tunnel node in the local host store and print the rupu node --cp-url ... --token ... command to run on the box. The token is shown ONCE and never persisted on disk |
pull | Poll a bucket dead-drop, atomically claim jobs, run them locally, write results back, and apply queued control messages |
| Option | Description |
|---|
--cp-url <CP_URL> | WebSocket URL of the control-plane node endpoint (e.g. ws://cp.example.com:7878/api/node/connect; the /api/node/connect path is appended automatically when omitted). wss:// requires a TLS-terminating proxy and a TLS-enabled build. Required in agent mode (when no subcommand is given) |
--token <TOKEN> | Authentication token. Mutually exclusive with --token-stdin |
--token-stdin | Read the authentication token from stdin (one line). Preferred over --token so the secret does not land in shell history. Mutually exclusive with --token |
--node-id <NODE_ID> | Override the node identity string. Default: a persistent node_<ULID> written to ~/.rupu/node_id on first run |
rupu node enroll
Enroll a new tunnel node in the local host store and print the rupu node --cp-url ... --token ... command to run on the box. The token is shown ONCE and never persisted on disk
rupu node enroll [OPTIONS] <NAME>
| Argument | Description |
|---|
<NAME> | Display name for the node (e.g. build-box-01) |
| Option | Description |
|---|
--cp-url <CP_URL> | CP URL to include in the printed command (e.g. ws://cp.example.com:7878; the /api/node/connect path is appended automatically when omitted). Default: this machine's detected routable IP on port 7878 |
rupu node pull
Poll a bucket dead-drop, atomically claim jobs, run them locally, write results back, and apply queued control messages
rupu node pull [OPTIONS] --bucket <BUCKET>
| Option | Description |
|---|
--bucket <BUCKET> | Bucket URL (e.g. s3://my-bucket, gs://my-bucket). Credentials are resolved via the environment credential chain |
--prefix <PREFIX> | Optional key prefix within the bucket (e.g. rupu/host-1) |
--host-id <HOST_ID> | Override the worker identity. Default: the stable node_<ULID> persisted at ~/.rupu/node_id (same as the tunnel node agent) |
--once | Claim all currently-available jobs, drain them to terminal (bounded), then exit. In loop mode (the default) the agent runs forever |
--interval <INTERVAL> | Poll interval between ticks in seconds (loop mode only) [default: 15] |
rupu update
Download and install the latest release for the configured channel
rupu update [OPTIONS]
| Option | Description |
|---|
--check | Only report whether an update is available; install nothing |
--force | Reinstall even if already up to date (or downgrade to the channel's latest if this build is ahead of it) |
-y, --yes | Deprecated no-op: rupu update no longer prompts, so there is nothing to skip. Still accepted so existing scripts and aliases that pass -y keep working |
--channel <beta|stable> | Override the configured channel for this run |
--rollback | Restore the previously-installed binary from the last backup |
--print-platform | Print this build's release-asset platform name (e.g. linux-x64) and exit. The release pipeline uses this to name assets from the binary itself, so the publisher and rupu update cannot drift |