npm package: @remits/remits-cli
Description: Local CLI for auth, component sync, and live test execution against Remits
Latest version: 0.1.31

# remits-cli

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

## Install

```bash
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

```bash
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 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

```bash
remits-cli install --skills
```

Optional:

```bash
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.
- 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.
- `remits-cli start` scans the machine for `account-info.json` files and rebuilds `~/.remits-cli/account-repos.json` before bringing up the background service.
- During account-repo discovery, `remits-cli` also refreshes each repo's bundled `guides/*.md` files and `guides/features/*.md` feature docs.
- During account-repo discovery, `remits-cli` also refreshes root `CLAUDE.md`, `AGENTS.md`, and `GEMINI.md` from `docs/guides/remits-components-zip-readme.md`.
- The published CLI package stages those guide files from the platform repo's `docs/guides/` tree during `npm pack` / publish, so the source of truth stays in one place.
- 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.

## 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.
- `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:

```bash
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:

```bash
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.