# The rootsy command

> Reference for rootsy, the helper command on every Rootsy computer: each subcommand with its flags, output and exit codes.

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

```sh
rootsy status
```

Prints:

```text
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](https://rootsy.io/docs/reference/preview-and-testing.md) shows how to do that.

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

```text
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

```sh
rootsy domains
```

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

```text
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](https://rootsy.io/docs/reference/domains.md).

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.

```sh
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](https://rootsy.io/docs/reference/preview-and-testing.md) covers using these while you build.

## rootsy keep-awake

```sh
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](https://rootsy.io/docs/reference/sleep.md) and [Jobs](https://rootsy.io/docs/reference/jobs.md).

## 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](https://rootsy.io/docs/reference/scheduled-tasks.md) covers how schedules behave and how to build and verify the endpoint they call.

```sh
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:

```text
{"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:

```sh
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

```sh
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.

---
Page: https://rootsy.io/docs/reference/cli/ · Updated: 2026-10-21 · All docs: https://rootsy.io/llms.txt