CLI Reference

The humanauth CLI is a thin scriptable layer over the HumanAuth platform API plus the in-process @humanauth/verifier. Every command supports --json for pipelines.

Installation

# Run without installing
npx @humanauth/cli <command>

# Or install globally
npm install -g @humanauth/cli
humanauth <command>

Global flags

Flag	Default	Description
`--json`	`false`	Emit a single JSON document to stdout. Errors go to stderr as `{ "error": { "code", "message" } }`.
`--verbose`	`false`	Print HTTP request/response traces to stderr. Authorization headers are masked.

Authentication

`humanauth login`

Save your API key locally to ~/.humanauth/config.json (mode 600).

humanauth login --api-key ha_test_…
humanauth login --api-key ha_live_… --base-url https://api.humanauth.ai

`humanauth logout`

humanauth logout

`humanauth status`

humanauth status

Humans

humanauth humans list
humanauth humans invite alice@example.com --role admin
humanauth humans remove huid_abc123

Groups

humanauth groups list
humanauth groups create finance --members huid_a,huid_b,huid_c --quorum 2
humanauth groups delete grp_xyz

Devices

humanauth devices list huid_abc123

Output:

device_id     kind  paired_at                 last_active_at            receipts_signed
─────────────────────────────────────────────────────────────────────────────────────
dev_iphone_1  ios   2026-01-15T09:32:11Z      2026-06-02T14:01:02Z      37

humanauth devices revoke <device_id> ships as a stub today — the server endpoint hasn’t shipped yet.

Requests

humanauth requests get req_abc
humanauth requests cancel req_abc --yes

humanauth requests list is a stub pending the platform’s GET /v1/requests endpoint.

Receipts

humanauth receipts list --limit 20
humanauth receipts get rct_…
humanauth receipts get rct_… --decode
humanauth receipts get rct_… --verify \
  --audience ten_test \
  --action transfer:create \
  --plan-file ./plan.json

--decode prints the JWS header + payload (device signatures are masked as <redacted>). --verify runs the same pipeline as humanauth verify — useful when the JWS is stored server-side and you only have the receipt id.

Webhooks

List & inspect

humanauth webhooks list
humanauth webhooks get sub_…

humanauth webhooks subscribe \
  --url https://hooks.example.com/humanauth \
  --events request.decided,request.reported

The response prints the signing secret once inside a red box. The CLI cannot show it again — copy it into your secret manager before continuing.

Update

humanauth webhooks update sub_… --status paused
humanauth webhooks update sub_… --events request.decided
humanauth webhooks update sub_… --url https://new.example.com

Destructive ops

humanauth webhooks delete sub_… --yes
humanauth webhooks rotate-secret sub_… --yes

Without --yes, you’ll be prompted to retype the subscription id verbatim. rotate-secret keeps the old secret valid for 24h so consumers can roll over without dropped deliveries.

Test & deliveries

humanauth webhooks test sub_…
humanauth webhooks deliveries sub_… --status exhausted --limit 20
humanauth webhooks redeliver sub_… wdl_…

Verifier

The CLI bundles @humanauth/verifier so you can verify receipts and inspect platform metadata without writing any code.

`humanauth verify <jws>`

Runs the full verifier pipeline (signature → envelope → cosig → plan hash → action → replay-claim) and prints the verified subject.

humanauth verify "$JWS" \
  --audience ten_test \
  --action test:hello \
  --plan-file ./plan.json

Failure paths exit 1 with a typed error code: PLAN_HASH_MISMATCH, ACTION_MISMATCH, JWS_SIGNATURE, AUD_MISMATCH, etc. Pipe --json to consume them.

`humanauth keys` and `humanauth discover`

humanauth keys
humanauth discover --platform-url https://api.humanauth.ai

`humanauth fixtures mint`

Generates ephemeral platform + device keys, mints a signed v2 receipt, and prints both the JWS and the matching JWKS. Round-trip with humanauth verify for a hermetic test:

humanauth fixtures mint --action test:hello --json > /tmp/fix.json
JWS=$(jq -r .jws /tmp/fix.json)
echo "$(jq .plan /tmp/fix.json)" > /tmp/plan.json
# (verify here would need a JWKS server; use the verifier inline-jwks option in real tests)

Secret handling

The CLI is strict about credential PII:

API keys are masked in --verbose traces (Authorization: Bearer ha_live_ab****).
Webhook secrets only appear on the one response that returns them (webhooks subscribe, webhooks rotate-secret), inside a red “Save this now” box.
Receipt JWS bodies are safe to print, but --decode masks the per-approver device_sig fields as <redacted>.

Scripting with `--json`

Every command emits a single, parseable JSON document under --json:

# List every webhook URL
humanauth webhooks list --json | jq -r '.[].url'

# Filter exhausted deliveries to a CSV
humanauth webhooks deliveries sub_… --json --status exhausted \
  | jq -r '.deliveries[] | [.delivery_id,.event_type,.attempt_count] | @csv'

# Branch on verify failure
if ! humanauth verify "$JWS" --json \
  --audience ten_x --action transfer:create --plan-file ./plan.json > /tmp/ok.json 2>/tmp/err.json
then
  code=$(jq -r '.error.code' /tmp/err.json)
  echo "Receipt rejected: $code"
fi

Exit codes

Code	Meaning
`0`	Success
`1`	API error, validation error, verifier error, or user abort