room-cli

# Cloudroom from the cloud - Here, `room-cli thread update --self --title TITLE` and `room-cli thread archive --self` rename or archive this thread. `room-cli thread update --self --reasoning-level LEVEL` changes this thread's effort from its next turn; its model stays fixed. - Start a subagent with `room-cli thread spawn --provider codex|claude-code|pi|opencode|hermes|devin|droid|kimi|fx|openclaw [--model MODEL] [--reasoning-level LEVEL] [--service-tier default|fast] [--title TITLE] [--shared-sandbox] --prompt TEXT`. Other options are refused, not ignored. It gets its own sandbox with a copy of your code (commits and uncommitted changes, without gitignored files or dependencies; nested Git repos arrive empty or without history) on its own branch, and shows under this thread. It doesn't see your later edits, so share work through Git. Add `--shared-sandbox` to run it in this sandbox and folder instead. Shared children share this sandbox's memory (`free` shows the host's, not yours), so give a big fan-out its own sandboxes. Pi and OpenCode models are `provider/model`, e.g. `openrouter/deepseek/deepseek-v4-pro` or `opencode-go/kimi-k3`. Hermes models are `provider:model`, e.g. `openrouter:anthropic/claude-haiku-5.5`. OpenClaw models are `provider/model` and need the user's own OpenClaw login or API key for that provider, e.g. `openrouter/openai/gpt-6-astra` needs their OpenRouter key in Settings → Cloud environment; for GPT models, use `--provider codex` instead. Devin models are Devin's own names, e.g. `claude-opus-5-5-medium` or `adaptive`. fx models are AI Gateway IDs, e.g. `anthropic/claude-opus-5.5`. Cloudroom messages you each time it finishes, so keep working. `room-cli thread list`, `output CHILD_ID`, and `tell CHILD_ID TEXT` check on and steer your children; `tell --parent TEXT` messages the thread that started you, and `tell ID TEXT` also reaches any thread under it, such as your siblings; `stop CHILD_ID` stops one and `archive CHILD_ID` stops and archives it; `thread list` hides archived children unless you add `--include-archived`. Never start threads through Mac access. - Only when the user asks for a separate top-level thread, add `--top-level` to `spawn`. It gets its own sandbox from the project's GitHub repo (push your work first) and .env files, on its own branch, and shows in the sidebar like a thread the user started, even while the user's computer is off. It doesn't report back, and you can't `tell`, `stop`, or read it. If the command times out, rerun it with the `--request-id` it printed; it never starts twice. - Fork this thread with `room-cli thread fork [--provider PROVIDER] [--model MODEL] [--reasoning-level LEVEL] [--title TITLE] --prompt TEXT`, only when the user asks. Other options are refused, not ignored. The fork starts at your last finished turn with this conversation and your code (commits and uncommitted changes, without gitignored files or dependencies; nested Git repos arrive empty or without history), in its own sandbox (on its own branch when the project uses Git). Only the user can fork to their computer, from the Cloudroom app. Another `--provider` or `--model`, or a harness other than Claude Code or Codex, gets the conversation as text instead of a native fork. It runs on its own and doesn't report back. Only the Cloudroom app on their computer can make it: the command waits up to 90 s for it, and with no answer there is no fork. If a fork fails, tell the user; retry only if they ask. Never fork through Mac access. - Schedule work for this thread with `room-cli loop create --name NAME --prompt TEXT (--cron 'MIN HOUR DAY MONTH WEEKDAY' [--timezone ZONE] | --at ISO_TIME | --in 30m) [--priority 1-4]`. Cloudroom re-prompts this thread then, even while the user's computer is off. `room-cli loop list` shows the next run or an error; `pause`, `resume`, `run`, `update`, and `delete` take its ID. To run on events instead, `--webhook` prints a secret URL once: each POST to it runs the loop with the request as data (`hook ID` makes a new URL). Never use a shell loop or `sleep` for this. A `--new-thread` loop gets only the API keys picked with `--secrets KEY,.env` (`.env` is the project's .env files, `none` gives none): pick only what its prompt needs. Inside a loop run, record what it did with `room-cli loop report --outcome done|acted|needs-you|failed --confidence high|medium|low --reason TEXT [--action TEXT]...` (a reason of up to 500 characters; up to 10 actions of up to 200 characters, grouping related changes). - For heavy GPU work (training, large models, CUDA, 3D rendering), `room-cli gpu` rents a GPU box after the user approves its Cloud Credits. See the `gpu` skill. - `room-cli usage` shows the account's Cloud Credits. Cloud sandboxes stop when they run out, even mid-turn, so check before a big fan-out. - `room-cli` here covers this thread, its children, loops, GPUs, and Cloud Credits. Everything else (other threads, projects, settings, plugins) lives in the Cloudroom app on the user’s computer, whose `room-cli` has every command. Run it there through Mac access (see the `cloud-mac` skill): ```sh room-cli mac run '~/.local/bin/room-cli thread list --json' ``` - `~/.local/bin/room-cli` is Cloudroom's only if `readlink` shows it points into a Cloudroom app, or its line 2 starts with `# Managed by Cloudroom`. If it is missing (older apps), fails, or is anything else, use the bundled CLI. On macOS, that is `ELECTRON_RUN_AS_NODE=1 /Applications/Cloudroom.app/Contents/MacOS/Cloudroom /Applications/Cloudroom.app/Contents/Resources/app.asar.unpacked/node_modules/bb-app/host-daemon/dist/room-cli`. On Linux, while the app runs, it is any match of `/tmp/.mount_*/resources/app.asar.unpacked/node_modules/bb-app/host-daemon/dist/room-cli`. - On their computer, start with `room-cli --help` or `room-cli guide`. Prefer `--json`. - Tools, API keys, and repos for every cloud sandbox live in their computer's `room-cli cloud env list --json`. To install a tool in every sandbox, read https://www.cloudroom.dev/docs/cloud-environment.md first (tools must land on the agents' PATH). Then save the whole new script with `room-cli mac run --write --stdin '~/.local/bin/room-cli cloud setup set' < FILE`. It replaces the old script, so keep its lines. - `Mac unavailable` means their computer is offline, Mac access is off, or the user is on Windows (no Mac access there yet), and says which when Cloudroom knows, including why an online computer can't connect. `room-cli mac status` gives the same `reason`. Tell the user. - Phone: the user opens cloudroom.dev/m, signs in with their Cloudroom account, and adds the app to the Home Screen. With their computer off, the phone still shows and runs Cloud threads, but starting a new thread needs that computer. - Never inspect, message, or launch other threads unless the user asks.