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 stop
remits-cli install --skills
remits-cli tools
remits-cli tool --base-url http://localhost:8080 --name "My Tool" --input '{"foo":"bar"}'
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 token --path page/my-embeddable
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.
• 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 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 sync, the platform clears the branch/user staging scope so staged aliases cannot keep shadowing the newly synced DB rows.
• 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, then the active session. For remits-cli tool calls the server applies a further precedence — explicit --account-id > input.accountId > session/repo default — so a tool can execute against a different account than the surrounding repo.
• 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 ....
• 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.

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 and prints the dashboard URL when available.
• 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. Each ticket gets its own tmux window/workstream.
• The listener enables tmux mouse support, increases scrollback history, and keeps exited panes visible for inspection.
• Follow-up messages with the same ticketId are routed back to the existing pane when it is still alive.
• Legacy payloads that only include taskId are still supported as a fallback routing key.
• If a pane for a tracked ticket has exited or is dead, the listener removes that mapping and creates a replacement pane.
• Pane commands are launched through the user's login shell so the pane inherits the normal interactive PATH.
• The preferred agent 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 delivered over the remits-cli websocket channel and appear as local tmux workstreams.
• Think of this as a lightweight local support queue: the platform creates and updates tickets centrally, and local agents receive those tickets to investigate and resolve.
• accountId / accountName identify the account that owns the ticket.
• If present, implementationAccountId / implementationAccountName identify the platform or product context that owns the shared implementation.
• Listener repo dispatch prefers implementationAccountId when present, then falls back to accountId. If one of those repos is indexed locally in ~/.remits-cli/account-repos.json, it will be preferred as the tmux working 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 mcp_support_ticket to manage ticket state:

remits-cli tool --name "mcp_support_ticket" --input '{"action":"read","ticketId":"123"}' --data-mode prod
remits-cli tool --name "mcp_support_ticket" --input '{"action":"accept","ticketId":"123","assignee":"codex"}' --data-mode prod
remits-cli tool --name "mcp_support_ticket" --input '{"action":"update_status","ticketId":"123","status":"in_progress","notes":"Investigating logs"}' --data-mode prod
remits-cli tool --name "mcp_support_ticket" --input '{"action":"complete","ticketId":"123","resolution":"Fixed and verified"}' --data-mode prod

• Recommended ticket flow: read first, then accept, then update_status as work progresses, then complete 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.

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.