remits-cli

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

Install

npm install -g @remits/remits-cli

Common Commands

remits-cli auth --base-url https://your-remits-host --account-id 123
remits-cli install --skills
remits-cli tools
remits-cli tool --name "My Tool" --input '{"foo":"bar"}'
remits-cli components stage
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 listen
remits-cli listen status
remits-cli listen stop
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.
• 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.
• 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.
• account-info.json is used to infer accountId when not supplied.
• Branch defaults to the current local git branch.
• Data mode defaults to test. Use remits-cli data-mode set prod only for production investigation.
• 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.

Listener, WebSocket, and Tmux Lifecycle

• The listener is a persistent background process started with remits-cli listen.
• Most non-listen commands will auto-start the listener in the background if authenticated sessions already exist and no listener is running.
• Successful remits-cli auth also attempts to auto-start the listener in the background.
• remits-cli listen starts a detached background process by default. Use remits-cli listen --foreground true only when you want to run the daemon in the current terminal.
• remits-cli listen status reports whether the background listener process is still alive.
• remits-cli listen stop stops the background listener, kills the shared tmux session, and clears pane tracking state.
• The listener 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.
• 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.
• targetAccountId / targetAccountName identify the directly affected account. If present, targetAccountPlatformId / targetAccountPlatformName identify the platform or product context that owns the shared implementation.
• Listener repo dispatch prefers targetAccountPlatformId when present, then falls back to targetAccountId, then the payload account ID. 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.
• ~/.remits-cli/config.json CLI config such as the preferred agent.
• ~/.remits-cli/listener.pid PID for the background websocket listener process.
• ~/.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.
• ~/.remits-cli/tmux-activity.log Human-readable global activity log for listener and tmux lifecycle events.

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, 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.
• 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 will log that new sessions were detected and should be restarted to pick up new websocket topics.
• Session logs redact token fields and replace large component content fields with length summaries.