---
name: remits-cli
description: Use remits-cli for fast branch-scoped component staging, test execution, embeddable token flows, and tool-based investigation.
---

# remits-cli

`remits-cli` is how a local agent talks to the Remits platform: it stages component source for
server-side execution, runs Test components, mints embeddable browser tokens, reconciles a repo into
the live component database, calls the server-side investigation tools, and carries the support-ticket
lifecycle.

This file is the **index and the rules**. It is deliberately short so it can be loaded in full every
session. Everything else — the mechanics, the failure modes, and the exact command and tool surface —
lives in the reference files listed below, which ship with the CLI and are read on demand.

## How to read this skill

**The reference files are here:**

`{{SKILL_REFERENCES_DIR}}`

Every reference named below is a file in that directory. Two mechanics make loading one cheap, and you
are expected to use both:

1. **Each reference opens with a table of contents carrying real line numbers** — `- L412  Diagnosing a
   variant`. The numbers are resolved when the CLI installs the file, so they are never stale, and each
   entry is the heading verbatim, so it also greps.
2. **Therefore: read the head of the reference, choose your sections, then offset-read only those.**
   `tool-reference.md` alone is around a thousand lines. Loading a whole file because you needed forty
   lines of it is the most common way an agent runs out of room to do the actual work.

**Naming a reference is not reading it.** These files exist because the behavior they describe is not
guessable from the command names. An agent that skips one does not fail loudly — it proceeds on a
plausible assumption and produces work that looks finished and is not. When a task is governed by a
reference below, load it before you act, not after something surprises you.

## Which reference, and when

| Load it before you | Reference | It owns |
|---|---|---|
| decide which account or repo work belongs in, or explain why a request resolved the way it did | `account-targeting.md` | the `resolution` block, repo selection, multi-parent edges, storage namespaces, test-data flags, the data-lane clamp |
| run `components sync` or `components commit` — **mandatory** | `component-integrity.md` | how a trunk sync reconciles repo→DB, why a filename's id prefix is load-bearing, the `auxiliary` trap, the pre-sync safety check, the repair procedure |
| build or change any component | `development-loop.md` | test vs prod mode, the golden rule of verification, the eight-step fast loop, `new_` components and sidecars, the temporary-experiment pattern |
| conclude "my change isn't working" | `component-resolution.md` | the staged → variant → trunk order, the staging key format, the compile signature that proves what ran, staging workspaces for parallel agents, the stale-compile-cache caveat |
| work from a non-trunk checkout, or promote a branch | `branch-variants.md` | what a variant is, which world your checkout resolves, `--as-account` vs `--variant-branch`, tombstones, the promotion loop and its phases, subscribe/retire |
| touch a support ticket | `support-tickets.md` | the ticket record and its verbs, routed vs claimed vs owned, autonomous workers, the repository edit lease, ask/answer/resume, delivery |
| register this session as an agent, or ask why a routed ticket never started | `agent-sessions.md` | `serve` vs `register`, what registration does, worker spawning per agent kind, routing order, the control center, multi-session auth |
| investigate live behavior | `investigation.md` | which tool reads which record, correlation keys, reading a record's `content`, HTTP audits, AI activity, node/`localMode`, the production support flows |
| call any `mcp_*` tool | `tool-reference.md` | every tool's parameters, semantics, and traps — read the tool's entry before building its input |
| run, describe, poll, or interrupt an Action from the CLI | `tool-reference.md` → `mcp_run_action` | Action execution through `remits-cli tool --name mcp_run_action`; there is no separate top-level `remits-cli action` / `run action` wrapper |
| reason about repo discovery, auth state, or what a command actually sent | `cli-state.md` | the global `~/.remits-cli/` control plane vs per-repo `./.remits-cli/`, and which file answers which question |
| need an exact flag, or the auth / host / async surface | `command-reference.md` | authentication, host vs data mode, the two async mechanisms, hierarchy-scoped reads, the full command list, prod banners |
| give up on something that misbehaved | `troubleshooting.md` | the symptom→fix table, the two kinds of escalation, and the escalation bundle |

## The rules that are cheaper to state than to look up

These are the ones that cost a session more to rediscover than to carry. Each is expanded in the
reference named after it.

- **edit → stage → run, every time.** The platform executes whatever is in the staging cache at the
  moment a run starts. Edit a file, run a test without `remits-cli components stage`, and the test runs
  the OLD code. This is the single most common mistake. (`development-loop.md`)
- **Staging and sync fail early on broken runtime-compiled Groovy.** Stage validates changed source in the
  active lane; sync validates changed/new compiled components before writing DB rows or branch variants.
  Agent files are Utility components internally. A stage refused BY COMPILE VALIDATION still wrote the
  lane — the compile has to resolve through the staged overlay to see the source it is judging — so fix and
  re-stage before running anything in that lane. (A policy or edit-lease refusal is the opposite: it
  returns before any write.) (`development-loop.md`, `component-integrity.md`, `branch-variants.md`)
- **Stage your WORKSET, not the whole repo: `remits-cli components stage --workset`.** It uploads only
  the components git reports changed and makes the lane hold exactly them. A plain `components stage` is
  a FULL SNAPSHOT — it puts every component in the repo into the lane, so "115 staged" tells a human
  nothing about what you are working on, and every one of those entries shadows committed source until
  it expires. Keep the full stage for a deliberate complete snapshot or a "what is stale here?" reset.
  (`development-loop.md`)
- **`components commit` internally merge-stages for compile validation.** Its first phase uses changed-only
  merge semantics so the server can compile the changed runtime source before git writes. That does not
  reconcile or clean the lane, and its stage packet is not proof that the lane equals your workset. Use
  `components stage --workset` for behavioral verification before landing. (`component-integrity.md`,
  `component-resolution.md`)
- **Give each agent its own lane: `remits-cli workspace use --auto`.** Without a workspace you are in
  the SHARED lane, where a full stage replaces what another agent is testing rather than merging with
  it. Each agent works in its own **clone**, never a same-branch worktree: worktrees share the branch
  ref, so one agent's pull moves `HEAD` under the others, and `components commit` refuses there.
  A supervised `agent serve` ticket worker is the narrow exception: it may use a per-ticket worktree under
  one ticket, one lease, one staging workspace and an explicit freshness check. (`component-resolution.md`,
  `support-tickets.md`)
- **Use the full vocabulary in reports and handoffs.** Say **git branch** / `branchName` for the
  checkout and staging namespace, **staging lane** for the account+user+git branch+workspace Redis
  overlay, **component branch** / `variantBranch` for durable `ComponentVariant` overlays, **data lane**
  for test/prod records, and **source layer** for staged/variant/trunk. Do not collapse these to
  "branch" or "verified"; say what was actually proven: Test pass, browser journey, corpus measurement,
  sync mutation, or ticket lifecycle state. (`component-resolution.md`, `branch-variants.md`,
  `development-loop.md`, `support-tickets.md`)
- **Land only from trunk or a real variant branch.** A per-agent/feature branch (`components status` says
  `FEATURE BRANCH … [subscription-fallback]`) is safe to stage and run from — it resolves the same world
  as its target — but `components commit`/`sync` refuse it. Merge into the branch it resolves and land
  there; `--create-variant-branch` is only for deliberately creating a new variant branch.
  (`branch-variants.md`)
- **On a variant branch, sync with `remits-cli components sync --safe`.** It dry-runs first and refuses
  a plan that would write components this checkout did not change — which is what a branch that is
  behind trunk produces, because it still physically carries old copies of files nobody touched.
  (`component-integrity.md`, `branch-variants.md`)
- **`stage` is always safe. `components commit` on trunk is the most dangerous command in the CLI.**
  It is not a convenience wrapper: it merge-stages/compile-validates changed source, then `git add -A`,
  commits, pushes, and reconciles the whole pushed repo into the live component database — creating,
  updating, renaming, and **hard-deleting** rows. Prefer the observable
  `git commit → git push → components sync → git pull`. On trunk it refuses before any git write unless
  you pass `--yes`. (`component-integrity.md`)
- **After anyone lands, ask whether your lane is stale: `remits-cli components status`.** A landing clears
  only the lander's lane; yours keeps shadowing their new rows with content staged from the old base.
  `LANDED SINCE YOUR BASE` / `STALE OVERLAY` mean pull, re-stage, then verify — a pass against a stale
  lane proves nothing. (`component-resolution.md`)
- **A component filename's numeric id prefix is load-bearing.** Renumber it and the next trunk sync
  creates a duplicate at the new id and hard-deletes the original. A live component whose files are
  missing from the repo at trunk-sync time is hard-deleted. Never renumber, rename across ids, or
  remove component files as a side effect. (`component-integrity.md`)
- **`auxiliary: true` opts a component out of the repo in BOTH directions.** A `new_*` file marked
  auxiliary is never created, never gets an id, and never gets renamed — it looks exactly like the sync
  silently ignored your work. Use it only for genuinely throwaway components.
  (`component-integrity.md`)
- **Ask which world your checkout resolves before you run anything:** `remits-cli components status`.
  A trunk checkout and a variant-branch checkout differ on both ends of the loop — what a run resolves
  and what a sync writes. Do not infer it from the branch name. (`branch-variants.md`)
- **Start from a steady git baseline before the first edit.** Run `git fetch origin`; confirm
  `git log origin/<branch>..<branch>` and `git log <branch>..origin/<branch>` are both empty; then run
  `remits-cli components status`. On a variant branch also run `remits-cli components promotion --branch
  <branch>`. A workspace isolates staging, not the commit your files are based on. (`development-loop.md`,
  `branch-variants.md`)
- **Resolution order is staged → variant → trunk, and each layers over the one beneath.** A populated
  staging cache makes a committed variant look broken through any tokenized entry point; clear it before
  verifying variant resolution. (`component-resolution.md`)
- **A lane's staged count is the OVERLAY, not your workset.** The overlay is every staged entry the lane
  holds — what a run resolves. The workset is what git says you changed. A full stage makes them differ
  by the size of the repo, and `--changed-only` merges, so it can never shrink an overlay it inherited.
  `components status` prints all three numbers; so does the console. (`component-resolution.md`)
- **Review other lanes with read-only commands, not SQL.** `components lanes` lists every indexed lane on
  the account, and `components entries --lane-id <id>` shows the actual staged files in one lane without
  changing your workspace or clearing anything. Use these when another agent's workstream is relevant.
  (`component-resolution.md`, `command-reference.md`)
- **Host and data mode are two independent decisions.** `--base-url` picks the Remits host,
  `--data-mode` picks the data segment on it. Neither implies the other. (`command-reference.md`)
- **`test run` ignores the stored session data lane.** It defaults to `test` even when `whoami` shows
  the session parked on prod; production Test runs require explicit prod provenance (`--data-mode prod`)
  or Test source declaring `dataMode 'prod'` / `[dataMode:'prod']`. Check returned `dataModeSource`
  when auditing a run. (`command-reference.md`)
- **A tool's `dataMode` input never widens the lane.** It may narrow `prod` → `test`, never escalate
  `test` → `prod`. The response's `dataMode` is the truth, not your input. To reach prod data, pass
  `--data-mode prod` on the command line. (`account-targeting.md`)
- **Never infer prod vs test from an account name, URL, or branch.** Read the explicit flags —
  `testAccount`, `testUser`, `testMode`, and the echoed `dataMode`. `mcp_sql_query` is lane-blind and
  returns both lanes mixed; filter it yourself. (`account-targeting.md`)
- **"Tool call succeeded" means DISPATCHED, not that the tool did what you asked.** A tool that runs and
  refuses returns HTTP 200 with its own `success: false`. For any mutating call, read `result.success`
  from `./.remits-cli/actors/<local-agent>/tool-responses/<callId>.json` (or the legacy flat fallback
  if `doctor local-state` says the response is there) before reporting the work as done.
  (`tool-reference.md`)
- **Workspace and local actor are different.** `workspace` is the server-side staging lane namespace;
  `local actor` is the repo-local filesystem namespace for session logs, tool responses, and verification
  mirrors. Use `REMITS_AGENT_ID=<name>` or `--local-agent <name>` when agents share a checkout, and run
  `remits-cli doctor local-state` when inheriting one. (`cli-state.md`, `component-resolution.md`)
- **Writing the code is not finishing the job.** A change is complete when it is verified — a Test
  component (preferred, because it becomes regression protection) or a browser flow through
  `remits-cli token`. "Just do it" and "that's fine, commit it" are not evidence. If you genuinely
  cannot verify, say what you would need and ask. (`development-loop.md`)
- **`remits-cli evidence` answers "what have I actually run, and in which world?"** Every stage, test,
  token, tool and sync appends one world-stamped line automatically, per actor. Nothing to start,
  nothing to satisfy. Read it before you re-run something, and quote it when you report what you
  proved. (`development-loop.md`)
- **Verification envelopes are OPTIONAL and exist for one job: a verdict someone else will rely on.**
  Start one when a ticket, a human, or a handoff needs a checkable "these specific things are true" —
  not as a routine step before editing. `remits-cli verify start --summary "..."` then
  `remits-cli verify claim <id> --text "..." [--test "<suite>"]` names what must be true; add
  `--claim <id>` to the command that proves it; `remits-cli verify report` gives the verdict. An
  envelope with no claims is simply an evidence log, which is a complete state — not something to
  chase. If you find yourself opening an envelope to answer a question about your own work, use
  `remits-cli evidence` instead. (`development-loop.md`, `component-resolution.md`)
- **Read the component's `.meta.yml` before changing behavior.** Sidecar descriptions can be dated
  decision records. Before changing a displayed value, helper, calculation, schema field, or prompt
  contract, check the sidecar and either preserve its decision or explicitly supersede it.
  (`development-loop.md`)
- **Read the account's `resolution` block before acting on it** — `role`, `type`,
  `resolvedDatabaseName`, `relationships`. More than one relationship means the account can legitimately
  resolve differently depending on the path a request travelled. Never infer an account's shape from its
  name. (`account-targeting.md`)
- **Investigate in prod mode; verify in test mode.** "It looks right in prod data inspection" is not
  proof that a code change works. And never copy live customer data into another account's test
  collection to get realistic verification. (`development-loop.md`)
- **`remits-cli agent serve` is the whole answer to "work support tickets".** No flags, no setup, no need
  to be in an account repo. `agent register` makes the session routable and starts nothing.
  (`support-tickets.md`)
- **`remits-cli ticket` is the platform's own ticket surface** and works on every Remits platform.
  `mcp_support_ticket` is one System Account's convention and refuses tickets it does not own.
  (`support-tickets.md`)
- **Reading and investigating are parallel-safe; editing one account's repository is exclusive**, via a
  lease. A refusal is not an error — carry on read-only and hand off with `ticket progress --next-step`.
  Never wait or poll for a lease. (`support-tickets.md`)
- **A brief's `## Rules you will be held to` section is ENFORCED, not requested.** The platform refuses
  the verb and the message says what to do instead — act on that sentence rather than retrying or
  looking for another door. A `[require]` rule needs a person; hand off. (`support-tickets.md`)
- **`components commit` takes a short landing lease on `(account, branch)`.** Refused means somebody else
  is landing right now — keep staging and iterating, which is lane-isolated, and retry in a minute.
  Never loop on it. (`development-loop.md`)
- **If something looks wrong, stop — do not paper over it.** Unexpected deletes, creates, renames,
  uniqueness errors, id drift, or a 500 from the platform: stop, preserve the session log and tool
  responses, and escalate. Never create replacement components to make ids line up, and never discover
  behavior by running unsupported mutating command variants. (`troubleshooting.md`)

## Orientation: the first four things to establish

```bash
remits-cli whoami                 # account, user, branch, data mode, host for the NEXT tool call
remits-cli workspace use --auto   # your own staging lane, named after this checkout
remits-cli doctor local-state     # active local actor, state dir, tracked .remits-cli, legacy state
remits-cli components status      # trunk or variant checkout, staging lane, workset vs overlay, who else is staging
remits-cli tools                  # which tools this account actually has (tools are per-account)
```

plus the repo's `account-info.json` → `resolution` block for the account's shape.
For a workflow-shaped request, rely on the automatic `remits-cli evidence` trail unless someone else needs
a checkable verdict. Only then start `remits-cli verify start --summary "..."`, declare claims, and keep
that envelope active through stage/test/token/sync.

If any command returns 401, run `remits-cli auth` (with the same `--base-url` if you were targeting a
non-default host).

**Files that are decision inputs — read the one that governs the decision, do not rely on memory:**
`~/.remits-cli/account-repos.json` (every local repo, plus the reserved `platform` entry for the core
platform clone), `~/.remits-cli/sessions.json` (auth state and lanes), `~/.remits-cli/agents.json`
(agents registered here), `./.remits-cli/actors/<local-agent>/tool-responses/<callId>.json` (the full
tool payload), and the repo's `account-info.json`. `cli-state.md` maps every remaining question to its
file, including legacy flat `.remits-cli/` fallbacks.
Repo-local session JSONL is intentionally a bounded audit log: request payloads and ordinary response
bodies are summarized with keys, sizes, hashes, and redaction markers. Open actor-scoped tool response
files when you need the full tool result.

## Efficiency rules

Keep support and development sessions lean:

- Prefer local repo files over remote component tools whenever the target account repo exists locally.
  `mcp_component_view` / `mcp_component_grep` are fallback surfaces for agents without that checkout,
  or for confirming what the live DB has stored after you already understand the files. For a ticket
  with `implementationAccountId`, resolve that account's indexed repo first, pull the appropriate
  branch when the checkout is clean, and inspect `account-info.json` + `components/` there.
- Do not read entire `.remits-cli/actors/<local-agent>/sessions/*.jsonl` (or legacy flat session logs) or
  large tool response files unless you first narrow to the relevant request, endpoint, tool, or ticket.
- Prefer targeted Firestore queries: use `documentId`, tight `filters`, narrow `fields`, and low `limit`
  values instead of broad collection scans.
- Do not call `mcp_account_view` repeatedly once you already have the needed account/component context.
- For investigations, follow the shortest path: identify the exact document/ticket/object first, then
  drill in. Avoid exploratory "maybe this" queries across large collections.
- For ticket replies, read the current ticket state and the new reply, then continue from existing
  context instead of re-loading broad account state from scratch.
- Verification should be decisive. Avoid repeated identical test/status/tool calls when no new
  information is likely.

## When something doesn't work

All `remits-cli` capabilities are known to work. The most common cause is an operational mistake, above
all forgetting to stage before running a test. If you have followed **edit → stage → run** and something
still misbehaves after two or three attempts, stop trying workarounds and open `troubleshooting.md`: it
carries the symptom table, separates a CLI/tooling issue from a back-stage platform defect, and owns the
escalation bundle for each.