The rootsy command

This page covers rootsy, the helper command on every Rootsy computer, with each subcommand’s flags, output and exit codes. It’s installed at /usr/local/bin/rootsy. It acts only on the computer it runs on. There’s no flag for choosing another computer or account.

Summary

Command	What it does
rootsy status	Show this computer’s id, Claude Code sign-in, address and wake holds
rootsy domains	Print the computer’s address and custom domains
rootsy preview refresh [--focus]	Reload the workspace’s Preview window
rootsy preview open <path-or-url> [--focus]	Point the Preview at a page
rootsy preview focus	Bring the Preview window to the front
rootsy preview window [--reason signin|other]	Tell the workspace this app needs a real browser window
rootsy keep-awake -- <command> [args...]	Run a command and keep the computer awake until it exits
rootsy schedules <operation> ...	Manage this computer’s scheduled requests (JSON in and out)
rootsy welcome	Open the interactive guide
rootsy help	Print usage

rootsy status

rootsy status

Prints:

box:      <computer id>
protocol: <runtime version>
claude:   logged in
site:     https://<name>.rtsy.dev · ● live
guide:    rootsy · basics: help

claude: is logged in, not logged in, or unknown (sidecar unreachable). site: shows the computer’s address when Rootsy can look it up, and unknown (control plane unreachable) when it can’t. The ● live marker doesn’t test your app. Preview and testing shows how to do that.

While something is keeping the computer awake, a wake-hold: line lists it:

wake-hold: active — claude mid-turn; keep-awake: npm run build

After a restart, a last stop: line can say how the computer last stopped. If it contains NOT a deliberate release, the computer stopped while something was holding it awake. Report that to Rootsy with the time the line shows.

rootsy status always exits 0.

rootsy domains

rootsy domains

Prints the computer’s address, then each custom domain and its status:

site:     https://<name>.rtsy.dev
example.com  active
www.example.com  active

A custom domain’s status is its last saved status: pending_dns, issuing, active, error or expired. It doesn’t show detached, so a detached domain can still read active here. Check the Domains window or MCP get_domain. With no custom domains, the second line reads (no custom domains connected — the Domains window connects one). You add custom domains in the workspace’s Domains window, not with this command. See Domains.

If Rootsy can’t be reached, it prints domains unavailable right now (control plane unreachable) to stderr and exits 1.

rootsy preview

Controls the Preview window in any workspace that has this computer open.

rootsy preview refresh
rootsy preview refresh --focus
rootsy preview open /pricing
rootsy preview open /pricing --focus
rootsy preview focus
rootsy preview window
rootsy preview window --reason other

open takes a path starting with / or an https:// URL, up to 2048 characters. A path resolves against the computer’s address. The workspace follows a URL only if its host is the address or an active custom domain. --focus brings the Preview window to the front and works with refresh and open. --reason works only with window. It takes signin (the default) or other, and changes the message the workspace shows.

Output on success names how many open workspaces received it:

Command	Output
refresh	preview refreshed (1 viewer)
open	preview → /pricing (1 viewer)
focus	preview focused (1 viewer)
window	real-window suggestion shown (1 viewer)

With no workspace connected, nothing is shown. Every form prints no dashboard connected — the user will see the latest version when they next open it, except window. It prints no dashboard connected — tell the user to use 'Open in its own window' on the Preview.

Exit codes: 0 when sent, including the no-workspace case. 1 for preview command rejected or preview control unavailable on this box, both on stderr. 2 for wrong arguments, with a usage line on stderr. Preview and testing covers using these while you build.

rootsy keep-awake

rootsy keep-awake -- npm run build

Runs the command after -- and keeps the computer awake until it exits, whether or not it’s using CPU. The -- is required. Without it, or without a command, it prints usage: rootsy keep-awake -- <command> [args...] to stderr and exits 2.

It exits with the command’s own exit code. The command runs with no terminal input, so it can’t prompt for anything. While it runs, rootsy status shows wake-hold: active — keep-awake: <command>, and the computer spends Runtime Credits. See Sleep and wake and Jobs.

rootsy schedules

Manages this computer’s schedules, the requests Rootsy sends to a path on your app at set times. Every operation prints one JSON object on stdout. Scheduled tasks covers how schedules behave and how to build and verify the endpoint they call.

rootsy schedules list
rootsy schedules get <schedule-id>
rootsy schedules preview --timezone America/New_York --json '{"sourceText":"weekdays 9am"}'
rootsy schedules create --timezone UTC --json '{"name":"Report","sourceText":"daily at 2 am","method":"POST","path":"/jobs/report","payloadText":null,"enabled":true}'
rootsy schedules update <schedule-id> --if-match <version> --json '{"enabled":false}'
rootsy schedules pause <schedule-id> --if-match <version>
rootsy schedules resume <schedule-id> --if-match <version>
rootsy schedules run <schedule-id>
rootsy schedules history <schedule-id>
rootsy schedules delete <schedule-id>

Flags each operation accepts:

Operation	Flags
list, get, delete	none
preview	--json (required), --timezone
create	--json (required), --timezone (required), --request-id
update	--json (required), --if-match (required)
pause, resume	--if-match (required)
run	--request-id
history	--request-id, --occurrence-id, --cursor, --limit (1–100)

preview needs a timezone, from --timezone or a timezone field in its JSON. --file <path> or --stdin can replace --json, reading the JSON from a file or standard input. Use one of the three, not two. Input is limited to 512 KiB. --if-match takes the schedule’s current mutationVersion from get or list. The change is refused if the schedule changed since. --request-id takes a UUID.

The create body has these fields:

Field	Value
name	Up to 100 characters, not blank
sourceText	When to run, in plain English ("weekdays 9am") or cron. Up to 500 characters.
method	"GET" or "POST"
path	A path on your app starting with /, up to 512 characters. Letters, digits and ._~/- only, so no query string. No //, . or .. segments. /_iw and paths under it aren’t allowed.
payloadText	A JSON string up to 64 KiB sent as the body, or null. Must be null for GET.
enabled	true or false

The timezone comes from --timezone and must be UTC or an Area/City name such as Europe/Berlin. An update body has enabled, a full draft object (name, sourceText, timezone, method, path and payloadText), or both.

A successful operation prints {"ok":true,...,"status":<http status>,"result":{...}} and exits 0. A refusal from Rootsy prints {"ok":false,"error":"<code>",...,"status":<http status>} and exits 1. Arguments it can’t parse print {"ok":false,"error":"invalid_schedule_command"} and exit 2. If the computer can’t reach Rootsy, it prints "error":"schedule_proxy_unavailable" and exits 1.

Recovering a lost create or run

create and run write a recovery line to stderr before contacting Rootsy:

{"type":"schedule_recovery","requestId":"<uuid>","operation":"create"}

A run line also carries scheduleId. The same requestId appears in the JSON on stdout. If the connection drops before you see a result, repeat a create with identical input and --request-id <uuid>. It won’t create a second schedule. For a lost run, look it up instead of running again:

rootsy schedules history <schedule-id> --request-id <uuid>

rootsy welcome

Opens the interactive guide that greets you in a new terminal. It offers to set up or start Claude Code, a short terminal crash course, or a plain prompt.

rootsy help

rootsy help

Prints usage and exits 0. Bare rootsy opens the guide in an interactive terminal. Anywhere else, such as from a script or an agent, it prints usage. An unknown command prints usage to stderr and exits 2.