CLI

@rectsh/cli is the terminal surface for rect.sh — the same loop agents run over MCP, speakable from any shell, script, or CI job. It covers publishing templates (reusable views), issuing rects (live instances), injecting and reading back state — and driving the view you're still developing.

npm install -g @rectsh/cli
rect login        # authorize this machine via your browser (once)

Account plumbing: rect accounts lists the teams you can publish to, rect whoami shows who this machine is logged in as, and rect logout removes stored credentials. rect host prints the effective default host, and rect host set <url> stores a new default.

Templates — publish & explore

rect publish             # build, bundle, and deploy the view in this directory
rect check               # build + actionable project audit [--json]
rect publish --issue     # publish, then issue one live instance
rect search "project planning dashboard" # find matching templates [--account <slug>] [--limit <n>] [--json]
rect list                # your template catalog, across all your teams  [--json]
rect spec <ref>          # one template's spec — always JSON
rect remix <ref>         # download a template's source into a new folder

• rect publish is keyed by the project's slug (rect.json), so republishing updates the same template in place. See Compile & publish.
• Teams: everything belongs to a team. With nothing pinned, a single team resolves itself and multiple teams are prompted for; --account <slug> targets one explicitly (rect accounts lists them). The choice is remembered in rect.json.
• <ref> is a template slug or id. rect search ranks matching templates; rect list browses all your teams, and rect issue <slug> finds the template wherever it lives.

Audit before publishing

Run rect check from a bundle-based Rect project before handing it back or publishing it:

rect check
rect check --json
rect check --no-build --dir dist

The audit checks the build, stable project slug, source and embedded specs, rect.agent.md, Codex/Claude Code instruction files, action metadata and handler block, example size, entry file, and the 20 MB bundle limit. Problems are written for a coding agent to act on:

WARN  Action "approve" has no inputSchema.
      How to fix: Add an inputSchema for "approve" so agents can construct
      valid arguments and the host can reject malformed input before the
      handler runs.

--json returns stable check codes, statuses, messages, and fixes. Warnings do not fail the command; errors exit non-zero.

Rects — issue & drive

rect issue <ref>                             # issue a rect from a template
rect issue <ref> --state '{"title":"A"}'     # …with an initial view model
rect issue <ref> --state input.json --open   # …from a file, then open it

rect find                                    # issued rects, most recently touched first
rect find --template <ref> --status open

rect read <rect-id>                          # full state + revision — always JSON
rect patch <rect-id> '{"done":true}'         # RFC 7386 merge patch
rect patch <rect-id> --file patch.json --expected-revision 4
rect dispatch <rect-id> addTodo '{"title":"Ship it"}'  # run a named action
rect open <rect-id>                          # open in the browser

rect attachment upload <rect-id> ./report.pdf  # signed upload into $attachments

• read/patch/dispatch/open work by rect id alone (the capability URL's id) — no login needed.
• When the view declares actions, prefer dispatch over patch: the view's handler runs host-side and a rule violation comes back as its code (✖ Rejected (TODOS_OPEN): …) instead of corrupted state.
• --expected-revision gives optimistic concurrency: a stale patch fails with the current revision so you can re-read and retry.
• --state and patches accept inline JSON, a file path, or - (stdin).

The agent loop

rect search "sales report"                 # what best fits?
rect spec sales-report                     # what shape does it want?
rect issue sales-report --state '{...}'    # issue + inject
# … the human works in the view …
rect read <rect-id>                        # read their edits back
rect patch <rect-id> '{"note":"reviewed"}' # respond

Use rect list when you want to browse the catalog, or when keyword-based search is unavailable or does not return a useful candidate.

This is the same loop agents run over MCP (rect_issue / rect_patch / rect_dispatch / rect_get_result) and any program can run over the HTTP API — the CLI speaks it from any terminal or script.

Drive the view you're developing

While npm run dev is running, the @rectsh/rect/vite plugin plays the Rect host locally. The reserved id dev targets it — the CLI finds the dev server on its own (ports 5173–5180; --dev <port> for anything else):

rect spec dev                          # the spec of the view being developed
rect read dev                          # the dev store's current state
rect patch dev '{"title":"draft"}'     # applies live in the open /dev.html
rect dispatch dev stamp '{"text":"x"}' # runs src/actions.ts (hot-reloaded)

Changes land in the browser over Vite's HMR socket — no reload — and edits made in the page flow back, so rect read dev always sees the latest. It's a full rehearsal of the agent loop against your work-in-progress view, before any publish.

CI

Create an account API token in account settings and set RECT_API_TOKEN instead of rect login, then pass --account <slug> (or commit it in rect.json).

export RECT_API_TOKEN=rect_api_...
rect publish --account acme

In GitHub Actions, store the token as a repository secret and expose it only to the publish step:

- run: rect publish --account acme
  env:
    RECT_API_TOKEN: ${{ secrets.RECT_API_TOKEN }}

Host precedence is --host > RECT_HOST > rect host set <url> > https://rect.sh.