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 components stage
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
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

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 --overwrite true

How It Works

• components stage uploads the current working tree into the staging cache used by test-mode execution. It replaces the branch/user staging scope with the current manifest, so stale aliases from prior stages are removed.
• 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.
• 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, and components clear print concise summaries by default. Add --json or --verbose to print the full server response. components stage separates local working-tree component deltas from the full materialized staging cache count.
• 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 commit verifies that origin/<branch> and local HEAD both match that exact 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.
• --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 the machine for account-info.json files and rebuilds ~/.remits-cli/account-repos.json before bringing up the background service.
• 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/guides/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.
• During account-repo discovery, remits-cli also overwrites the installed remits-cli SKILL.md for claude, codex, and gemini so local agents stay on the latest packaged instructions.
• The platform repo's docs/guides/ 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.
• Avoid commas in individual test names. The --names filter is comma-delimited, so a single test case whose name contains commas cannot be targeted cleanly through remits-cli test run --names ....
• 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 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, WebSocket, and Tmux 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.
• remits-cli stop stops the background service, kills the shared tmux session, and clears pane tracking state.
• 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, tmux session/panes, the discovered account repo index, global state files, and per-repo remits-cli files.
• If websocket connections are disconnected or the tmux session is missing, the dashboard exposes actions to reconnect websockets or recreate the tmux session.
• 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 and recreates the shared tmux session if it disappears.
• 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.
• Incoming websocket messages of type remits-cli are dispatched into dedicated tmux windows so the selected agent can continue working interactively with a full terminal view.
• The listener creates a shared tmux session named remits-listener.
• 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/dispatch-panes.json Persistent map of support ticket routing key to the active tmux pane id for that ticket's dedicated window. ticketId is preferred, with legacy taskId fallback.
• ~/.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/tmux-activity.log Human-readable global activity log for listener and tmux lifecycle events.

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.

Tmux Activity Log

• ~/.remits-cli/tmux-activity.log is the quickest way to understand what the listener is doing.
• It records timestamped lifecycle events such as listener start/stop, websocket connect/disconnect, topic subscription, dispatch receipt, pane creation, follow-up delivery, pane replacement, and dispatch failures.
• Prompt bodies are not written verbatim to this log. The log stores summarized metadata such as accountId, ticketId, any legacy taskId, available keys, and prompt length.
• Typical inspection commands:

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

Operational Notes

• tmux must be installed for agent dispatch to work. Without it, websocket dispatch is received but agent panes cannot be created.
• 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 for testing, then git add/commit/push, then remits-cli components sync, then git pull --ff-only to confirm platform-generated files like account-info.json.
• 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.