@commissionsight/cli

Command-line interface for the CommissionSight API — authentication, workspace selection, and statement uploads for any carrier, any period, in any workspace. A thin, faithful wrapper over @commissionsight/sdk.

It is designed to be driven by humans and by AI coding agents (Claude Code, Cursor, etc.) running locally: every command is fully non-interactive, supports machine-readable --json output, and returns deterministic exit codes.

npm install -g @commissionsight/cli
cs --version

Binaries: cs (and the alias commissionsight). Requires Node ≥ 20.

---

Quick start

# 1. Authenticate (token issued by CommissionSight; piped, never in argv)
printf '%s' "$COMMISSIONSIGHT_TOKEN" | cs auth login --token-stdin
cs auth status                                  # verifies via me()

# 2. Pick a workspace (only needed on multi-workspace accounts)
cs workspace list
cs workspace use "Main Book"

# 3. Upload a statement — any carrier, any period, any workspace
cs upload ./aetna-2026-05.xlsx --carrier aetna --period 2026-05 --wait --results --json

# 4. Bulk upload a folder (idempotent, resumable, mixed carriers/periods)
cs upload batch ./statements --workspace "Main Book" --wait --report ./ingest.json

---

Using this CLI from an AI agent (Claude Code, etc.)

This section is the contract an autonomous agent should rely on. Everything here is stable and machine-checkable. (Running cs with no arguments prints a condensed version of this guidance, so a harness that discovers the binary is onboarded immediately.)

1. Discover the surface programmatically — don't guess

cs schema --json

Returns the entire command/flag tree as JSON plus a conventions block (the envelope shape, exit-code table, error fields, auth, idempotency, and pagination rules) — so a single call fully onboards an agent. It contains every command, its positional args (with required/variadic), and every option (type, short, desc, choices, default). Parse this instead of memorizing commands. Shape:

{
  "ok": true,
  "data": {
    "name": "cs",
    "version": "0.1.0",
    "globalOptions": [ { "flag": "json", "type": "boolean", "desc": "…" }, … ],
    "commands": [
      {
        "command": "upload",
        "path": ["upload"],
        "summary": "Upload a statement for a carrier + period",
        "args": [ { "name": "file", "required": true, "variadic": false } ],
        "options": [ { "flag": "carrier", "type": "string", "desc": "…" }, … ]
      },
      …
    ]
  }
}

2. Always pass --json — parse only stdout

In --json mode, stdout carries exactly one JSON value: the envelope. All human chrome (spinners, progress, warnings) goes to stderr. So an agent can safely JSON.parse(stdout) without stripping anything.

• Success (exit 0):

  { "ok": true, "data": <command result> }

• Failure (nonzero exit):

  { "ok": false, "error": { "status": 409, "code": "period_exists", "message": "…", "body": { … } } }

error.code is a stable slug derived from the API's problem+json body (period_exists, already_retracted, …) or null. The error object also carries a machine-readable hint (the recovery action, e.g. "re-run with --replace") and retriable (true for rate-limits/timeouts/5xx) — so an agent can recover without parsing message text. Branch on error.code / error.status / error.retriable.

3. Use exit codes for control flow

Code	Meaning	Typical agent reaction
0	Success	continue
1	Unexpected/internal error (incl. a job that finished failed)	inspect error.message; surface to user
2	Usage error (bad flags/args)	fix the invocation
3	Auth error (401/403)	token missing/invalid/insufficient — re-auth
4	Not found (404)	the id/ref doesn't exist
5	Conflict (409), e.g. period_exists	retry with --replace
6	Validation (400/422)	inputs rejected; read error.body
7	Rate limited (429)	back off and retry
124	Timeout (--wait exceeded --timeout)	poll again or raise --timeout

4. Stay non-interactive

• Token: prefer COMMISSIONSIGHT_TOKEN in the environment, or --token-stdin (pipe it). Avoid --token <t> — it lands in process listings and shell history.
• Destructive ops (file retract|purge, team remove, rate delete, webhook delete, admin … purge-files, admin user delete) require --yes / -y when there's no TTY. Without it they exit 2 and perform nothing.
• Carrier refs accept an id, slug, or case-insensitive name; an ambiguous name exits 2 and lists candidates on stderr.
• Periods are --period YYYY-MM (or --year + --month).

5. Idempotency makes retries safe

cs upload derives an idempotency key per file (<context>-<carrierSlug>-<period>-<sha8(file)>). Re-running the same upload or the same upload batch is safe and resumable: already-ingested carrier+periods come back as skipped, not duplicated. Override with --idempotency-key if you need to.

6. Recipes

# Upload and block until scored, get rows back as JSON in one call
cs upload ./uhc-2026-05.csv --carrier uhc --period 2026-05 \
  --wait --results --json
# → data.upload.{jobId,fileId}, data.results[] (scored ResultRows)

# Handle "period already exists" deterministically
cs upload ./aetna-2026-05.xlsx --carrier aetna --period 2026-05 --json
# exit 5 + error.code=period_exists  → re-run with --replace:
cs upload ./aetna-2026-05.xlsx --carrier aetna --period 2026-05 --replace --json

# Bulk ingest a directory, keep going past failures, write a machine report
cs upload batch ./statements --continue-on-error --report ./out.json --json
# data.{total,uploaded,replaced,skipped,failed,unmatched,outcomes[]}

# Pull a full month rollup as JSON, or export rows as CSV
cs report rollup --period 2026-05 --json
cs job results <jobId> --all --csv -o ./scored.csv

# Export exception (rejected) rows for a job
cs job exceptions <jobId> -o ./exceptions.csv      # exit 4 if none/purged

# Audit a single member across every period
cs member journey <memberRefId> --json

7. Multiple environments

Contexts bundle a base URL + token + default workspace. Switch with --context <name> on any command, or set the active one:

cs context add staging --base-url https://staging.api.commissionsight.com/v1
printf '%s' "$STAGING_TOKEN" | cs context add staging --token-stdin
cs context use staging

---

Authentication & config

Auth is a per-account API bearer token issued by CommissionSight (there is no email/password login in the API). Token resolution precedence (highest first):

1. --token <t> (discouraged — visible in shell history)
2. --token-file <path> / --token-stdin (preferred for scripts)
3. COMMISSIONSIGHT_TOKEN env var
4. active context token in the config file

Config lives at ${XDG_CONFIG_HOME:-~/.config}/commissionsight/config.json (dir 0700, file 0600). The token is never printed — auth status shows a masked suffix (…a1b2). --base-url / COMMISSIONSIGHT_BASE_URL override the API base (default https://api.commissionsight.com/v1).

---

Global flags

Flag	Purpose
--json (or CS_OUTPUT=json)	Emit only the envelope on stdout
--quiet / -q	Suppress human chrome
--no-color (or NO_COLOR)	Disable ANSI color
--yes / -y	Assume "yes" for destructive confirmations
--token / --token-file / --token-stdin	Token sources
--base-url <url>	Override API base URL
--context <name>	Use a named config context
--help / -h, --version / -V	Help / version

---

Command reference

100 commands across these groups (run cs <group> --help, or cs schema --json for the full machine-readable tree).

Group	Commands
Session	whoami · health · version · schema · completion bash|zsh|fish
Auth	auth login · auth status · auth logout · auth token issue
Context	context list|current|use|add|remove
Workspace	workspace list · workspace create <name> · workspace use <name|id>
Carrier	carrier list · carrier get · carrier config list|get|create|test|infer
Upload	upload <file> · upload batch <target>
File	file list|get|rescore|retract|purge|rescore-stale
Job	job list|get|wait|results|deltas|exceptions|retry
Member / Policy	member list|get|timeline|journey|last-seen · policy journey
Team / Audit	team list|invite|remove · audit list
Reports	report rollup|compare|attrition|attrition-series|data-quality|chargebacks
Rates	rate list|set|delete
Webhooks	webhook list|create|delete
Billing	billing get|preview|update
Admin	admin account * · admin token * · admin carrier * · admin user * · admin job * · admin allowlist add · admin metrics|logs|revenue|cron-runs

List commands accept --limit, --all (auto-paginate), and --offset or --cursor as appropriate; result/report commands accept --csv (with -o to write a file). Reports take --period/--carrier/--from/--to as listed in --help.

Notes & limitations

• Workspace creation (cs workspace create <name>) requires @commissionsight/sdk ≥ 2.3.0 (createWorkspace → POST /workspaces). The command is capability-gated: on an older SDK it fails with a clear, actionable message instead of silently no-opping.
• Report workspace scoping: the API documents an optional ?workspaceId on reports, but the SDK's report methods do not yet accept it, so cs report * omits --workspace. As a thin wrapper the CLI never bypasses the SDK; this lands when the SDK exposes the parameter.
• Stripe payment-method / setup-intent flows are web-app only and out of scope; use cs billing get/preview/update for billing details.

---

License

MIT © CommissionSight