remits-cli

Local CLI for rapid Remits component testing without push/sync cycles.

Install

npm install -g @remits/remits-cli

On each command run, remits-cli checks the npm latest version for @remits/remits-cli. If a newer version exists, it installs it globally with npm and re-runs the original command. To skip this check for one run, pass --no-auto-update; to disable it for a process environment, set REMITS_CLI_AUTO_UPDATE=0.

Common Commands

remits-cli auth --base-url https://your-remits-host --account-id 123
remits-cli start
remits-cli status
remits-cli whoami
remits-cli stop
remits-cli install --skills
remits-cli tools
remits-cli tool --base-url http://localhost:8080 --name "My Tool" --input '{"foo":"bar"}'
remits-cli tool --name mcp_firestore_search --input '{"collection":"statements","documentId":"1234"}' --scope children
remits-cli workspace use --auto               # once per checkout: your own staging lane
remits-cli components stage --workset         # normal iteration: stage exactly what you changed
remits-cli components stage                   # FULL SNAPSHOT of the repo into the lane
remits-cli components status
remits-cli components clear
remits-cli test run --test 45
remits-cli test run --test "My New Test" --names "test case 1|test case 2"
git add -A
git commit -m "sync passing changes"
git push
remits-cli components sync --safe             # variant branch: gated, dry-runs first, refuses surprises
remits-cli components sync doctor             # read-only sync/promotion/staging diagnosis
remits-cli components sync
remits-cli components sync --branch feature_branch --dry-run
remits-cli components sync --branch feature_branch --dry-run --summary
remits-cli components sync --branch feature_branch --force-tombstones
remits-cli token --path page/my-embeddable    # returns tokenKey/embeddableUrl, plus embedTokenKey/embedSnippet for host embeds
remits-cli token --path page/my-embeddable --variant-branch feature_branch
remits-cli token inspect --token https://example.test/s/<tokenKey>/page/my-embeddable
remits-cli tool --name mcp_account_user_admin --data-mode prod --input '{"action":"account_create","parentAccountId":4,"name":"Freto","type":"PRODUCT","dryRun":true}'
remits-cli data-mode
remits-cli data-mode set prod
remits-cli sessions list
remits-cli config set --agent codex
remits-cli activity inspect --account-id 4 --scope children --data-mode test

Local AI inference

Run remits-cli ai serve --agent codex --account-id 123 --base-url http://localhost:8080 in a terminal, then opt in with ai(localAgent:true, ...). Claude, Gemini, and manual workers are also supported. The supervisor resumes one native conversation per Remits session; workflow tools continue executing on the server. The data lane defaults to test. See local inference commands and limits.

Skill Install

remits-cli install --skills

Optional:

remits-cli install --skills --target codex
remits-cli install --skills --target claude
remits-cli install --skills --target gemini
remits-cli install --skills --target antigravity
remits-cli install --skills --overwrite true

How It Works

• cli/index.js opens with a line-numbered code Table of Contents. Section entries are generated from the ## section marker comments in the file. Run npm run prepare:index-toc after moving sections; npm test checks that the prepared line numbers still point at the real headings.
• components stage has three modes, and the difference decides what a run in the lane resolves:
  • default (full snapshot) — uploads the whole repository manifest and reconciles the lane to it, so stale aliases from prior stages are removed. Correct as a complete snapshot and as a "what is stale here?" reset; a poor progress signal, because the lane then holds every component in the repo.
  • --workset — uploads only the components git reports changed and reconciles the lane to exactly those. The normal iteration mode. --changed-only --replace-lane is the explicit spelling.
  • --changed-only — uploads only the changed components and MERGES, leaving every other staged entry in place. It therefore cannot shrink a lane inherited from an earlier full snapshot; the command warns when it retains entries that way.
• An empty workset never clears a lane: --workset on a clean working tree stages nothing and leaves the lane as it is. Pass --empty-workset clear to opt in, or use components clear --all.
• A deleted component file cannot be represented in Redis staging — clearing a staged entry falls back to the committed row, so the component still resolves. Those changes are reported as NOT REPRESENTABLE. On a non-trunk variant branch, prove a deletion through components sync --dry-run --summary --fail-on-errors; on trunk there is no dry-run plan, so use the full pre-sync safety check before any mutating reconcile.
• Schema .meta.yml sidecars can stage/sync the schema flags: enableTrigger, enableFullText, enableRAG, enableRevisions, enableBigQuerySync, enableRules, anchor, and auxiliary.
• components status shows the branch/user staging entries that can shadow DB components during CLI-scoped test-mode execution, plus the other live lanes on the account.
• components lanes lists every indexed staging lane on the account. components entries --lane-id <id> reads the authoritative staged files for one lane without switching your workspace, clearing anything, or using SQL.
• components clear clears staged entries. Scope it with --component-type and/or --component-id. Component ids are type-local, so an id alone clears that one component when the id is staged in only one family; if the same id is staged across multiple families it returns an ambiguity error asking you to add --component-type. With no filter it clears every staged entry for the current branch; pass --all to force the full-branch wipe explicitly.
• components stage, components status, components lanes, components entries, and components clear print concise summaries by default. Add --json or --verbose to print the full server response.
• activity inspect is a read-only workstream view for operator/agent review. It joins staging lanes, verification envelopes, Test runs, corpus measurements, live agent presence, and heuristic smell signals. Use --scope children from a platform/root account and --user-email or --user-id to focus on one CLI user.
• components stage and components status report three separate numbers, and they answer three different questions: the workset (components git reports this working tree changed), what was submitted, and the materialized overlay the lane now holds — which is what a run resolves. A number that could not be established prints as unknown, never as 0.
• components sync performs a server-side sync from the git remote into the Remits platform for the selected branch. It does not run local git commands. After a successful non-dry-run sync, the platform clears the branch/user staging scope so staged aliases cannot keep shadowing the newly synced DB rows.
• On trunk, components sync performs the full repo-to-DB reconcile. On a non-trunk branch, it writes ComponentVariant overlays only and may refresh branch-local account-info.json, account-hierarchy.json, and account-configurations.json for the subscribing account that initiated the sync. --dry-run is accepted only for non-trunk variant syncs and reports overrides/additions/tombstones without writing variants, caching the sync SHA, updating metadata, or clearing staging. Add --summary to dry-run output when you only need counts, removals/tombstones, errors, skipped items, and warnings. --force-tombstones is accepted only for non-trunk variant syncs and should be used only when missing trunk component files are intentional tombstone overrides.
• components commit is a convenience wrapper that performs local git commit/push, then components sync, then local git fetch/git pull --ff-only.
• components sync returns the post-sync branch SHA produced by the platform. components sync doctor is read-only and assembles local HEAD, origin HEAD, platform last-sync SHA, staging shadow risk, promotion freshness, repository mismatch, and the next safe action when sync state is confusing. components commit verifies that origin/<branch> and local HEAD both match the exact synced SHA after the final pull.
• components push is deprecated and currently behaves the same as components stage.
• accountId resolution for CLI commands: explicit --account-id flag wins, then the current repo's account-info.json (resolution.accountId, then the short-lived repoContext.accountInfoAccountId, then the legacy top-level id — legacy files are rooted at the hierarchy ROOT, so their top-level id may be an ancestor), then the active session.
• For remits-cli tool, read/discovery tools treat that resolved account as the scope root. You do not need the owning child account id for an exact document/record lookup: pass --scope children, or put scope:"children" in --input, and use the returned resolvedTargetAccountId for follow-up writes/runs. Use --target-account-id when you already know the exact owner, --account-ids for an explicit bounded owner list, and --anchor-account-id only to disambiguate multi-parent paths. Mutating tools still require an exact target.
• Auth sessions are stored per accountId + dataMode + baseUrl, so the same account can stay authenticated against both localhost and production without overwriting the other session.
• Active verification envelopes are scoped per baseUrl + accountId + branch + workspace + dataMode, so a localhost envelope does not silently capture evidence from a production command. Pass --verify-envelope <id> for an intentional cross-context attachment.
• --base-url and --data-mode are independent. --base-url chooses the Remits host (http://localhost:8080 vs deployed prod), while --data-mode chooses the data segment on that host (test vs prod). Do not assume --data-mode prod means the deployed prod host, or that --data-mode test means localhost.
• remits-cli start scans for account-info.json files and updates ~/.remits-cli/account-repos.json before bringing up the background service. While running, it rescans every five minutes using asynchronous directory reads, then reports the refreshed inventory to the platform. Repos cloned outside the CLI are discovered without a restart or a command run inside them. Both scans use REMITS_CLI_SCAN_ROOTS (default: the home directory), the same depth limit and directory exclusions. For immediate discovery, use remits-cli agent repos --rescan or Rescan Account Repos in the control center.
• Scans preserve manually selected repository directories and record competing checkouts as ambiguity. remits-cli agent repos --account-id <id> --forget suppresses rediscovery until an explicit registration (--directory <path>) or a CLI command run from that account repo restores it.
• Front-stage guides are not bundled with the CLI npm package. For account-work commands (components, test, token, tools, tool) and on auth, remits-cli downloads the latest guides from the authenticated /cli/guides endpoint and writes them into the current account repo: root platform-overview.md / development-guide.md, guides/*.md, guides/features/*.md, and the agent-guidance files CLAUDE.md / AGENTS.md / GEMINI.md (from docs/front-stage/remits-components-zip-readme.md).
• Guide sync requires authentication. If no valid session exists and the terminal is interactive, the CLI auto-authenticates first; in non-interactive contexts (CI, agent sandboxes) it skips silently so guides are only ever delivered to users who can authenticate to the platform.
• On every command, remits-cli refreshes the installed remits-cli SKILL.md and reference files for claude, codex, gemini, and antigravity so local agents stay on the latest packaged instructions.
• The platform repo's docs/front-stage/ tree remains the single source of truth; the platform serves it from the classpath, so published CLI versions never carry guide content.
• Authenticated users also get the core Remits platform repo locally. After guide sync (and on auth / discovery), remits-cli first reuses any existing local copy it already knows about, can detect directly (REMITS_PLATFORM_DIR, the running CLI source in dev, ~/remits), or can discover under the configured scan roots; only if none is found does it clone [email protected]:tmillhouse/remits.git (default ~/remits, override with REMITS_PLATFORM_DIR; cloning only runs in an interactive terminal). On each authenticated run it also fast-forwards the repo (git pull --ff-only, once per process) so back-stage analysis runs against current code — skipped automatically if the working tree is dirty, so local work is never clobbered. The repo is tracked in ~/.remits-cli/account-repos.json under the reserved platform entry so agents can analyze back-stage seams and open a fix PR when a front-stage failure turns out to be platform brittleness.
• Branch defaults to the current local git branch.
• Data mode defaults to test. For remits-cli test run, that default is now enforced even if the most-recent authenticated session for the account is prod; a production test run therefore requires an explicit --data-mode prod on the command line. Use remits-cli data-mode set prod only for production investigation.
• If the same account is authenticated against more than one host and you omit --base-url, the CLI auto-resolves the best matching session and now prints the resolved host. Pass --base-url explicitly whenever the target host matters.
• --names is |-delimited and may be repeated. A comma is part of the selector, so comma-bearing case names can be passed literally.
• Nested help is available before required-argument validation, including remits-cli test run --help, remits-cli components sync --help, and remits-cli tool --help.
• components sync --safe is the recommended agent path on a variant branch. It expands to --summary --changed-only --fail-on-errors --fail-on-removed, resolves --changed-since from the branch's merge base with trunk when you did not name one (local refs only; it never runs an implicit git fetch), and prints the planned writes before mutating unless --yes is passed. On trunk there is no plan to gate, so it states what a trunk reconcile does and requires --yes.
• components sync has fail-closed safety gates for unattended/agent use. Each exits non-zero instead of printing a wall of JSON: --changed-only (fail unless every planned write is a component this checkout edited), --names-only (print only BUCKET type:id name lines), --fail-on-removed, --fail-on-errors, and --expected-removed <type:id> (repeatable or comma-delimited; implies --fail-on-removed, so any removal you did not name fails). --changed-only also fails closed when the checkout is not a git working tree, because "git could not answer" must never be read as "nothing changed".
• Any command that can touch production prints a PROD DATA banner naming the operation, the resolved account, and the host, and distinguishes a live write from a live read (and from a dry run). This covers tool, test run, and components sync.
• When a tool call fails inside the platform runtime rather than inside the tool — Groovy reflective dispatch of a runtime-compiled component, an empty connection pool, a Redis reconnect, a lock-wait timeout — the server returns 503 with failureClass: "transient_infrastructure" and retryable: true, and the CLI prints TRANSIENT INFRASTRUCTURE FAILURE (retryable). A genuine tool error stays a 500 with failureClass: "tool_error". Retry the first; do not retry the second.
• Test activity is streamed from websocket TestSuite events while final status is also polled from /cli/test.
• Tool execution writes the full response to a separate file so large payloads do not bloat the session log.
• --variant-branch <name|none> is available on test run, token, tools, and tool. Use it to probe a committed branch variant from any checkout; omit it to resolve the execution account's normal subscription, or pass none/trunk to force subscription semantics from a variant checkout.
• On test run, --branch <name> is only the Redis staging namespace. Pair an unused value with --variant-branch none when existing staged entries on the real git branch would shadow committed trunk/variant rows. Do not apply that shortcut to components sync or components commit, where --branch names the GitHub branch to reconcile.

Service, Dashboard, and WebSocket Lifecycle

• The primary lifecycle commands are remits-cli start, remits-cli stop, and remits-cli status.
• remits-cli listen, remits-cli listen stop, and remits-cli listen status still work as compatibility aliases.
• Most non-lifecycle commands auto-start the background service if authenticated sessions already exist and no service is running.
• Successful remits-cli auth also attempts to auto-start the background service.
• remits-cli start starts a detached background process by default. Use remits-cli start --foreground true only when you want to run the daemon in the current terminal.
• remits-cli status reports whether the background service is alive, prints the dashboard URL when available, and prints the resolved session tuple: Account ID, User ID, current git branch, and active data mode.
• remits-cli whoami prints only the resolved session tuple. Use --base-url, --account-id, and --data-mode to prove the exact host/account/lane before running a tool or test.
• Both print two data modes. "Data mode" governs tool / tools / token and falls back to the stored session lane; "Data mode (test run)" governs test run, which ignores the session and defaults to test unless --data-mode prod is passed. The test-run line also reports its source, such as cliDefault or explicitFlag.
• remits-cli stop stops the background service.
• The service starts a localhost dashboard that acts as a control center for remits-cli integration state.
• The dashboard shows websocket connection health, topic subscriptions, registered agents, live and recent worker runs, the discovered account repo index, global state files, and per-repo remits-cli files.
• If websocket connections are disconnected, the dashboard exposes an action to reconnect them.
• The service groups sessions by baseUrl so one websocket connection can service multiple authenticated accounts on the same Remits environment.
• Websocket subscriptions are deduplicated by user topic. If multiple authenticated accounts share the same websocket topic, the listener subscribes once and maps that topic back to all related accounts.
• The daemon keeps STOMP heartbeats enabled and runs a maintenance watchdog that recreates unhealthy websocket connections.
• Terminal server authentication/authorization errors suspend WebSocket retries and show authentication_required. Reauthenticate to replace the managed client's credentials; the watchdog does not revive rejected credentials. Transient failures use jittered exponential backoff up to 60 seconds. Test watchers keep HTTP polling; restart local-AI workers after reauthentication.
• If the machine sleeps, the network drops, or auth sessions change while the daemon is already running, the service now attempts to reconnect and resubscribe automatically once connectivity returns.
• Support tickets are the primary unit of dispatched work. A serving agent launches one fresh worker process per routed ticket.
• Agent sessions register themselves with remits-cli agent register or remits-cli agent serve; serve also starts the local supervisor.
• Tickets are delivered by durable routing on the ticket record, then the agent asks for routed work with remits-cli agent work.
• The preferred worker comes from remits-cli config set --agent claude|codex|gemini. The default is claude.

Support Tickets

• Support tickets are stored as documents in the support_tickets collection.
• New tickets and ticket updates are recorded centrally; local agents receive work by polling for tickets routed to their registered session.
• Think of this as a lightweight local support queue: the platform owns the record and lifecycle verbs, while account components can layer their own helpdesk workflow on top.
• accountId / accountName identify the account that owns the ticket.
• If present, implementationAccountId / implementationAccountName identify the platform or product context that owns the shared implementation.
• Worker repo resolution prefers implementationAccountId when present, then falls back to accountId. If one of those repos is indexed locally in ~/.remits-cli/account-repos.json, it is used as the worker's directory.
• Agents must resolve account type (PLATFORM, PRODUCT, CLIENT) before deciding which local repo to use. A CLIENT ticket may still require code changes in a parent PLATFORM or PRODUCT repo.
• Use remits-cli ticket to manage the generic platform ticket lifecycle:

remits-cli ticket read --ticket 123 --data-mode prod
remits-cli ticket accept --ticket 123 --data-mode prod
remits-cli ticket status --ticket 123 --status in_progress --notes "Investigating logs" --data-mode prod
remits-cli ticket complete --ticket 123 --resolution "Fixed and verified" --data-mode prod

• Recommended ticket flow: read first, then accept, then status as work progresses, then complete, ask, or release.

Logging and State Files

There are two separate state areas:

• Repo-local state in ./.remits-cli/ for request/response artifacts tied to the current working tree.
• Global state in ~/.remits-cli/ for authentication, listener lifecycle, and cross-repo account mapping.

Repo-local state

• ./.remits-cli/sessions/<current-session>.jsonl Records all /cli/* HTTP requests made from the current repo session.
• ./.remits-cli/tool-responses/<callId>.json Stores full tool responses for remits-cli tool.
• ./.remits-cli/tools/tools.json Cached tool definitions for the current repo.
• ./.remits-cli/current-session.txt Tracks the active local session log name.

Global state

• ~/.remits-cli/sessions.json Auth sessions keyed by account ID, base URL, and data mode so local and production sessions can coexist safely.
• ~/.remits-cli/config.json CLI config such as the preferred agent.
• ~/.remits-cli/listener.pid PID for the background remits-cli service process.
• ~/.remits-cli/service-state.json Dashboard URL, repo scan summary, and websocket state snapshot for the running service.
• ~/.remits-cli/account-repos.json Index of known account repositories on this machine, rebuilt by remits-cli start via account-info discovery and also refreshed when commands run inside an account repo.
• ~/.remits-cli/agents.json Agent sessions registered from this machine, including the process each one is anchored to.
• ~/.remits-cli/workers.json Active and recent ticket worker state for serving agents.
• ~/.remits-cli/activity.log Human-readable global activity log for service lifecycle, websocket events, agent registration, and ticket routing.

Control Center

• remits-cli start prints or records a localhost dashboard URL such as http://127.0.0.1:8787/.
• Open that page in a browser to inspect the full local remits-cli integration state without manually opening JSON files.
• The page refreshes automatically and includes the latest global state files plus per-repo account-info.json, local tools snapshot, and current session log tail for every indexed account repo. Large account configuration fields live in account-configurations.json and should be opened only when needed.

Activity Log

• ~/.remits-cli/activity.log is the quickest way to understand what the service, websocket clients, and local agents are doing.
• It records timestamped lifecycle events such as service start/stop, websocket connect/disconnect, topic subscription, agent registration/heartbeat, ticket routing, worker launch, and worker completion.
• Prompt bodies are not written verbatim to this log. The log stores summarized metadata such as accountId, ticketId, available keys, and prompt length.
• Typical inspection commands:

tail -f ~/.remits-cli/activity.log
tail -n 200 ~/.remits-cli/activity.log

Operational Notes

• In sandboxed local agent environments, remits-cli network calls may fail with ENOTFOUND, EAI_AGAIN, ECONNREFUSED, EPERM, or similar errors even when dispatch worked correctly. That means the command needs escalated permissions or must be run outside the sandbox.
• If the platform returns a 500 or other unexpected server-side failure, stop normal task execution and escalate to a Remits system admin. Agents should not invent workarounds for platform faults.
• Recommended durable update flow for agents: components stage --workset for testing, then git add/commit/push, then remits-cli components sync --safe, then git pull --ff-only to confirm platform-generated files like account-info.json. To verify the COMMITTED variant rather than your staging, run components clear --all first — staged entries still win for CLI-scoped runs.
• In sandboxed agent environments, local git writes may require a single approval step. If you want to minimize approval churn, remits-cli components commit consolidates the local git and sync phases into one CLI command.
• If account repo discovery fails for a websocket message, dispatch is skipped because the listener does not know which local directory to open for that account.
• If you authenticate a new account while the listener is already running, the listener now refreshes its websocket clients automatically instead of requiring a manual restart.
• Session logs redact token fields and replace large component content fields with length summaries.