@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