Documentation

CLI

@chitmark/cli: the three verbs from the terminal, with an interactive TUI.

Install

Package: @chitmark/cli on npm. Auth via CHITMARK_API_KEY or --api-key; point at another environment with --env or --base-url. Subject PII is hashed client-side before the wire, matching the SDK default.

npm install -g @chitmark/cli
# or: npx @chitmark/cli

Interactive mode

On a terminal, running a verb without its required flags opens an interactive TUI: pick an action with the arrow keys, walk through subject fields, review, and run. The verdict renders as a colored panel: green ALLOW, yellow CHALLENGE, red DENY, with confidence bar, reasons, and a [v] toggle to inspect verdictToken claims.

In the verdict panel: enter/q done · r re-run · c copy eventId · v claims.

Scripting

Passing the required flags skips the TUI and prints one JSON verdict. Same on non-TTY (piped stdin) or with --json, which also forces JSON on a terminal.

Exit code	Meaning
0	`allow`: proceed
2	`challenge`: escalate
3	`deny`: block

Global options

Every command shares these flags. CHITMARK_API_KEY is read automatically if --api-key is omitted. CHITMARK_BASE_URL overrides --base-url and --env.

Flag	Default	Description
`-k, --api-key <key>`	`CHITMARK_API_KEY`	Bearer key for `Authorization`
`-u, --base-url <url>`	env default	Override base URL
`-e, --env <env>`	`production`	`production` `staging` `development`
`-t, --timeout <ms>`	`800`	Client timeout
`--pii-mode <mode>`	`hashed`	`hashed` `raw` `none` (raw requires tenant opt-in)
`-j, --json`	off	Force JSON output, disables TUI

Commands

Three commands, one per verb. Running a command without its required flags on a terminal opens the interactive TUI; with flags (or --json or non-TTY) it prints JSON and exits with the verdict code.

chitmark verify

Return an action decision (POST /v1/verify). Without --action on a terminal, opens the TUI.

Flag	Description
`-a, --action <action>`	`signup` `trial_activation` `api_key` `demo_request` `quote` `ticket` `custom` (required for JSON)
`-s, --session <session>`	Binding id you supply (prefer high-entropy, server-generated)
`--surface <surface>`	`app.acme.com/signup`
`--email <email>`	Subject email (hashed client-side by default)
`--ip <ip>`	Subject IP (truncated client-side by default)
`--user-agent <ua>`	`chitmark-cli` by default
`--idempotency-key <key>`	`Idempotency-Key` header (header takes precedence over body)
`--context <json>`	JSON context object, default `{}`

Prints a Verdict JSON. Exit 0 allow, 2 challenge, 3 deny.

chitmark verify --action signup --session sess_9f3a --surface app.acme.com/signup --email buyer@acme.com --ip 203.0.113.7
# JSON with degraded challenge on timeout: exit 2, never 0 on error

chitmark feedback

Report an outcome joined on eventId (POST /v1/feedback). Without --event-id or --outcome on a terminal, opens the TUI.

Flag	Description
`--event-id <id>`	From verify (required)
`-o, --outcome <outcome>`	`credit_burn` `multi_account_cluster` `abuse_confirmed` `converted` `chargeback` `churned` `false_positive` (required)
`-v, --value <number>`	Measured magnitude for this outcome (scale is `--unit`)
`--unit <unit>`	`usd` `credits` `count` (default `usd`, only sent with `--value`)
`--source <source>`	`billing` `usage_metering` `trust_queue` `manual_review` `customer_system` `automated_detector`
`--observed-at <iso>`	ISO-8601 timestamp
`--idempotency-key <key>`	`Idempotency-Key` header for exact retries (409 on mismatch)

Prints { ok, eventId } JSON. value/unit are only sent when --value is set.

chitmark feedback --event-id evt_2f9c --outcome credit_burn --value 87.4 --unit usd
chitmark feedback --event-id evt_2f9c --outcome converted

chitmark challenge

Issue a challenge (POST /v1/challenge). Without --event-id on a terminal, opens the TUI.

Flag	Description
`--event-id <id>`	From verify (required)
`-s, --session <session>`	Same binding as verify (required; prefer server-generated)
`--prefer <methods>`	Comma-separated: `payment_preauth,proof_of_work,device_attestation,web_bot_auth_stepup,email_otp`

Prints ChallengeResponse JSON (challengeId, method, instructions, boundTo, expiresAt). Completion is through POST /v1/challenge with proof; the CLI does not complete challenges directly.

chitmark challenge --event-id evt_2f9c --session sess_9f3a --prefer proof_of_work
chitmark challenge --event-id evt_2f9c --session sess_9f3a --prefer payment_preauth,proof_of_work

Help

chitmark --help lists global options. chitmark verify --help, feedback --help, challenge --help list per-command flags. chitmark --version prints the CLI version.