Command Reference
Remoroo CLI commands, flags, and environment variables (aligned with the shipped client).
Remoroo CLI reference
This page mirrors the latest CLI (remoroo_cli/remoroo/cli.py). Run remoroo --help or remoroo run --help for the live text on your machine.
Installation
pip install remoroo
Requires Python 3.10+. Default execution uses Docker; you can use --engine venv instead.
Authentication
remoroo login # browser device flow
remoroo whoami
remoroo logout
Credentials are stored at ~/.config/remoroo/credentials. You can also set REMOROO_API_KEY for non-interactive use.
remoroo run
Starts a local run (default). Execution happens on your machine; the hosted Brain handles model calls and run bookkeeping.
remoroo run [OPTIONS]
Common options
| Option | Description |
|---|---|
--local | Run on this machine (default behavior; use to override if you also pass other mode flags). |
--remote | Not available in this CLI release. Prints how to contact sales for Enterprise hosted execution and exits with code 2. |
--repo PATH | Repository root (default: current directory). |
--out PATH | Base directory for cached/synced run outputs (see also .remoroo/runs/ in the repo). |
--goal "..." | Goal string (optional; otherwise prompted in the TUI). |
--metrics "a, b" | Comma-separated metric constraints (optional; otherwise prompted). |
--yes / -y | Skip confirmation prompts. |
--verbose / -v | Verbose logging. |
--no-patch | Do not prompt to apply final_patch.diff. |
--engine docker | --engine venv | Execution sandbox (default: docker, or REMOROO_DEFAULT_ENGINE). |
--cache-env / --no-cache-env | Docker layer caching (default: cache on). |
--in-place / --no-in-place | Edit repo directly vs isolated working copy (default: in place). |
--agentic / --no-agentic | Agentic loop vs legacy pipeline (default: agentic). |
--v2 / --v1 | v2 agent loop (default) vs legacy v1. |
--model ID | v2 LLM model id (e.g. provider-specific id). |
--pick-model / --no-pick-model | Full-screen model picker before TUI (default: on; not used when --resume). |
--budget HOURS | Wall-clock / cost budget in hours (default: 10). |
--allow-overage | Allow run to exceed credit balance (billed as overage per your plan). |
--resume RUN_ID | Attach worker to an existing run instead of creating a new one. |
--brain-url URL | Override Brain / API base URL (default from config / REMOROO_API_URL). |
Exit codes (remoroo run)
| Code | Meaning |
|---|---|
0 | Success. |
1 | Failure, error, or run did not complete successfully. |
2 | Either partial success (outcome reported as partial by the session) or you passed --remote while hosted execution is unavailable—check the message printed to the terminal. |
remoroo attach
Attach a local worker to an existing run (goal/metrics loaded from the server; no model picker).
remoroo attach --id RUN_ID [OPTIONS]
| Option | Description |
|---|---|
--id / -i RUN_ID | Required. From remoroo list. |
--repo PATH | Local checkout (optional). |
--out PATH | Output base directory. |
--brain-url URL | API base URL. |
--engine | docker or venv. |
--cache-env / --no-cache-env | Same as run. |
--in-place / --no-in-place | Same as run. |
--agentic / --no-agentic | Same as run. |
--v2 / --v1 | Same as run. |
--yes / -y | Skip attach/patch confirmations. |
--no-patch | Never apply patch after run. |
--verbose / -v | Verbose logging. |
remoroo list
List runs ( statuses for attach/resume).
remoroo list [OPTIONS]
| Option | Description |
|---|---|
--limit / -n | Max runs (server caps at 100). |
--attachable / -a | Only PENDING / RUNNING / PAUSED. |
--status / -s | Filter by one status (ignored if --attachable). |
--json | Print raw JSON. |
--brain-url | API base URL. |
remoroo abort
Abort a run on the control plane (sets status failed; clears pause/detach flags). Does not SIGKILL a remote worker process—see CLI help text for caveats.
remoroo abort RUN_ID [OPTIONS]
| Option | Description |
|---|---|
--yes / -y | Skip confirmation. |
--brain-url | API base URL. |
remoroo worker
Long-lived worker that polls the Brain for jobs (dedicated machine / advanced setups).
remoroo worker --repo PATH [OPTIONS]
| Option | Description |
|---|---|
--repo | Repository path (required). |
--server | Brain server URL (default from config). |
--interval | Poll interval in seconds (default 1.0). |
Environment variables
| Variable | Purpose |
|---|---|
REMOROO_API_KEY | Bearer token (skip interactive login). |
REMOROO_API_URL | Default API / Brain base URL (overridable with --brain-url). |
REMOROO_DEFAULT_ENGINE | docker or venv. |
Artifact layout
Authoritative run outputs for a repo are typically under:
<repo>/.remoroo/runs/<run-id>/
See the first experiment guide for files such as final_report.md, final_patch.diff, and trace.jsonl.