@credda/cli 0.1.4 → 0.1.6

package/README.md

@@ -1,3 +1,12 @@
+<p align="center">
+  <a href="https://credda.io">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Credda-io/credda-cli/main/assets/creddalockuplongdarktransparent.png">
+      <img alt="Credda" src="https://raw.githubusercontent.com/Credda-io/credda-cli/main/assets/creddalockuplonglighttransparent.png" width="360">
+    </picture>
+  </a>
+</p>
+
 > Source mirror for [`@credda/cli`](https://www.npmjs.com/package/@credda/cli). Install from npm: `npm install -g @credda/cli`. Canonical development happens in Credda internal tooling; this repo is for source and issues.
 
 # @credda/cli
@@ -35,14 +44,14 @@ credda quickstart           # seed the sandbox with synthetic subjects, print
              --no-confirm   # stop after the seed; skip the confirmation loop
 ```
 
-Public — no API key:
+Public (no API key):
 
 ```sh
 credda lookup <token>       # trust check for a share token (GET /verify/:token)
 credda export <token>       # full self-verifying trust export bundle
 credda verify <file|->      # OFFLINE-verify a credential someone handed you:
                             #   a W3C VC-JWT, a compact Trust Credential, or a
-                            #   saved trust-export bundle — auto-detected.
+                            #   saved trust-export bundle (auto-detected).
                             #   '-' reads stdin. Exit 0 valid / 2 invalid.
 credda registry             # federated trust registry (/.well-known)
 credda did                  # issuer DID document
@@ -50,7 +59,7 @@ credda benchmarks           # cohort-benchmark catalog: the dimensions you can
                             #   benchmark on and the k-anonymity floor below
                             #   which no cohort is disclosed
 credda reason-codes         # adverse-action reason-code catalog (ECOA / Reg B).
-                            #   Credda supplies the attribution only — it is not
+                            #   Credda supplies the attribution only: it is not
                             #   a creditor and issues no notice.
 credda badges list          # the closed set of Open Badges 3.0 achievements
 credda badges get <badgeId> #   this issuer will sign, and one definition
@@ -58,14 +67,14 @@ credda outcome-templates [industry]
                             # how a business maps its work to Credda events, and
                             #   WHO confirms each outcome. Guidance only.
 credda professional-record public <token>
-                            # the professional record behind a share token —
-                            #   the token IS the subject's consent to present it
+                            # the professional record behind a share token
+                            #   (the token IS the subject's consent to present it)
 credda career-export --token <token>
                             # the whole verified record as a JSON Resume document,
                             #   behind a share token (no API key sent)
 ```
 
-Platform — set `CREDDA_API_KEY` (a `crd_live_…` platform key):
+Platform (set `CREDDA_API_KEY`, a `crd_live_…` platform key):
 
 ```sh
 credda score <userId>       # current score
@@ -93,7 +102,7 @@ credda users [--score-min <n>] [--score-max <n>] [--band <b>]
              [--sort <score|lastActivity|registered|externalId>]
              [--order <asc|desc>] [--cursor <c>] [--limit <n>]
                             # query + export your book of subjects. The filter
-                            #   set is closed and validated — no query DSL.
+                            #   set is closed and validated: no query DSL.
                             #   A subject with no score yet reports null, never
                             #   a placeholder; list those with --unscored.
 credda book-summary [same filters as "users"]
@@ -114,7 +123,7 @@ credda verified-profile <userId>
                             # how much of a subject's CLAIMED record
                             #   (education/skills/certifications/employment) is
                             #   third-party verified. Counts WHETHER a claim is
-                            #   verified, never how prestigious it is — and can
+                            #   verified, never how prestigious it is, and can
                             #   never move the Reliability Score.
 credda qualify <userId> --category <education|skill|certification|employment>
         [--label <l>] [--issuer <i>] [--verified-by <witness>]
@@ -123,7 +132,7 @@ credda qualify <userId> --category <education|skill|certification|employment>
                             #   third-party --verified-by witness.
 credda professional-record get <userId>
                             # résumé-shaped summary of a VERIFIED work record.
-                            #   Describes a record — not a hiring verdict, a
+                            #   Describes a record. Not a hiring verdict, a
                             #   background check, or a consumer report.
 credda professional-record credential <userId> [--ttl <seconds>]
                             # mint the signed, offline-verifiable credential
@@ -141,7 +150,7 @@ credda mint <userId>        # mint a share token
 credda revoke <userId>      # revoke a share token
 ```
 
-Confirmation requests — the counterparty-confirmation primitive. You propose an
+Confirmation requests: the counterparty-confirmation primitive. You propose an
 outcome and deliver the one-time token yourself; the event is written, verified,
 only when that distinct party confirms:
 
@@ -154,7 +163,7 @@ credda confirmations create --user worker_7 --type CONTRACT_FULFILLED \
                             # needs CREDDA_API_KEY. The token is shown ONCE;
                             #   creating a request writes no event.
 credda confirmations batch <file.json> [--idempotency-key <k>]
-                            # the ACTIVATION ENGINE — bulk-create up to 100
+                            # the ACTIVATION ENGINE: bulk-create up to 100
                             #   requests from a JSON file (an array of request
                             #   bodies, or { "requests": [...] }), warming a cold
                             #   ledger from your book. Needs CREDDA_API_KEY; each
@@ -163,8 +172,8 @@ credda confirmations list [--status PENDING] [--cursor <c>] [--limit <n>]
 credda confirmations get <id>
 credda confirmations cancel <id>          # only while PENDING
 
-# ⚠️ These two are the COUNTERPARTY's calls and take NO API key — they hold a
-# token, not a Credda account:
+# ⚠️ These two are the COUNTERPARTY's calls and take NO API key (they hold a
+# token, not a Credda account):
 credda confirmations preview <id> --token <t>
 credda confirmations respond <id> --token <t> --confirm
 credda confirmations respond <id> --token <t> --decline
@@ -173,7 +182,7 @@ credda confirmations respond <id> --token <t> --decline
                             #   there is no default: you must say which.
 ```
 
-Reference requests — the qualifications-half sibling of confirmations. A résumé
+Reference requests: the qualifications-half sibling of confirmations. A résumé
 claim (employment / education / certification / skill) becomes verified when the
 named third party who was there confirms it; a reference never moves the score:
 
@@ -189,8 +198,8 @@ credda references list [--status PENDING] [--cursor <c>] [--limit <n>]
 credda references get <id>
 credda references cancel <id>             # only while PENDING
 
-# ⚠️ These two are the REFERENCE's calls and take NO API key — they hold a
-# token, not a Credda account:
+# ⚠️ These two are the REFERENCE's calls and take NO API key (they hold a
+# token, not a Credda account):
 credda references preview <id> --token <t>
 credda references respond <id> --token <t> --confirm
 credda references respond <id> --token <t> --decline
@@ -199,26 +208,26 @@ credda references respond <id> --token <t> --decline
                             #   and there is no default: you must say which.
 ```
 
-Threshold policies — declarative "tell me when this line is crossed", delivered
+Threshold policies: declarative "tell me when this line is crossed", delivered
 as `policy.threshold_crossed` through your webhooks. Config only: a policy never
 reads into, blocks, or changes a score:
 
 ```sh
 credda policies create --name "Watch 60" --user worker_7 \
         --metric score --direction down --threshold 60
-credda policies create --name "Anyone entering High Risk" --all \
-        --metric band --direction enter --band "High Risk"
+credda policies create --name "Anyone entering At Risk" --all \
+        --metric band --direction enter --band "At Risk"
 credda policies list [--cursor <c>] [--limit <n>]
 credda policies get <id>
 credda policies update <id> [--threshold <n>] [--direction <d>] [--band <b>]
         [--component <c>] [--name <n>] [--activate | --deactivate]
-                            # the metric is immutable — delete and recreate
+                            # the metric is immutable: delete and recreate
 credda policies delete <id>
 ```
 
-Score monitors — set `CREDDA_API_KEY`. Edge-triggered threshold/band watches
+Score monitors (set `CREDDA_API_KEY`). Edge-triggered threshold/band watches
 that deliver `monitor.triggered` through your subscribed webhooks;
-notification config only — a monitor never affects a score:
+notification config only (a monitor never affects a score):
 
 ```sh
 credda monitors list [--cursor <c>] [--limit <n>]
@@ -232,7 +241,7 @@ credda monitors create --user <externalId> --below 40
 credda monitors delete <id>
 ```
 
-Bulk screenings — set `CREDDA_API_KEY`. Async batch score reads (up to
+Bulk screenings (set `CREDDA_API_KEY`). Async batch score reads (up to
 10,000 ids per job), strictly read-only:
 
 ```sh
@@ -250,7 +259,7 @@ credda screenings results <id> --csv out.csv
                             # write the CSV attachment instead (raw fetch)
 ```
 
-Webhooks — set `CREDDA_API_KEY`:
+Webhooks (set `CREDDA_API_KEY`):
 
 ```sh
 credda webhooks list
@@ -271,7 +280,7 @@ CREDDA_WEBHOOK_SECRET=whsec_... credda listen 4141
 same check your production handler must do) and pretty-prints the payload.
 Credda delivers to public HTTPS only, so expose the port with your own tunnel
 (e.g. `cloudflared tunnel --url http://localhost:4141`) and register the
-tunnel URL as the webhook — the Stripe-CLI-style local loop without Credda
+tunnel URL as the webhook: the Stripe-CLI-style local loop without Credda
 running a tunneling service.
 
 Environment: `CREDDA_API_URL` overrides the API base (default
@@ -280,16 +289,16 @@ verification in `credda listen`.
 
 ## Design
 
-- `src/cli.ts` is the pure command router — no `process`, `fs`, or env access,
+- `src/cli.ts` is the pure command router: no `process`, `fs`, or env access,
   so the whole surface is unit-tested with a mocked `CreddaClient` (same
   pattern as `packages/mcp`'s `tools.ts`).
 - `src/index.ts` only wires the real environment (env vars, stdin/file
   reading, exit codes).
 - `verify` uses the SDK's offline verifiers (WebCrypto Ed25519 + StatusList
-  revocation) — the point is that a received credential can be checked
+  revocation). The point is that a received credential can be checked
   without trusting the wire it arrived on.
 - Every command is read-only against the score. `mint`/`revoke` manage a
-  share token — a capability, not a score write.
+  share token (a capability, not a score write).
 
 ## License
 

package/dist/cli.d.ts

@@ -1,16 +1,16 @@
 /**
- * Command router — pure of process/env/fs so it's testable with a mocked
+ * Command router: pure of process/env/fs so it's testable with a mocked
  * context (same pattern as packages/mcp's tools.ts).
  *
  * Every command is READ-ONLY against Credda's deterministic score. Nothing
- * here writes an Event, adjusts a score, or makes a trust decision — the CLI
+ * here writes an Event, adjusts a score, or makes a trust decision: the CLI
  * looks up and offline-verifies EXISTING, already-computed trust facts.
  * `mint`/`revoke` manage a share token (a capability, not a score write).
  */
 import type { CreddaClient, VerifiedCredential, VerifiedVc, VerifiedTrustExport, TrustExport } from '@credda/js/headless';
 export interface CliContext {
     client: CreddaClient;
-    /** Platform API key from CREDDA_API_KEY — only needed for keyed commands. */
+    /** Platform API key from CREDDA_API_KEY, only needed for keyed commands. */
     apiKey?: string;
     out: (line: string) => void;
     err: (line: string) => void;
@@ -21,7 +21,7 @@ export interface CliContext {
         verifiableCredential: (vcJwt: string) => Promise<VerifiedVc>;
         trustExport: (bundle: TrustExport) => Promise<VerifiedTrustExport>;
     };
-    /** whsec_… signing secret from CREDDA_WEBHOOK_SECRET — used by `listen`. */
+    /** whsec_… signing secret from CREDDA_WEBHOOK_SECRET, used by `listen`. */
     webhookSecret?: string;
     /**
      * Starts the local webhook receiver (`credda listen`). Injected so the pure
@@ -32,7 +32,7 @@ export interface CliContext {
         secret?: string;
     }) => Promise<void>;
     /**
-     * Raw authenticated GET returning the response body as text — for the CSV
+     * Raw authenticated GET returning the response body as text, for the CSV
      * endpoints (`?format=csv`), which the typed SDK deliberately leaves to raw
      * fetch. `path` is relative to the `/api/v1` prefix.
      */
@@ -44,7 +44,7 @@ export interface CliContext {
     /** Poll interval for `screen --wait` (default 2000ms). */
     pollIntervalMs?: number;
 }
-export declare const VERSION = "0.1.3";
+export declare const VERSION = "0.1.6";
 export declare const HELP = "credda: portable trust from the terminal\n\nStart here (needs a sandbox CREDDA_API_KEY, the crd_test_ kind):\n  credda quickstart              Seed your sandbox with synthetic subjects, print\n                                 their real scores, read one back, and then close\n                                 the counterparty-confirmation loop end to end so\n                                 you finish holding a real VERIFIED event, not\n                                 just a number you read. One command, nothing\n                                 written outside the sandbox.\n       --no-confirm              Stop after the seed; skip the confirmation loop.\n\nSandbox (crd_test_ keys only; a live key is refused before anything happens):\n  credda sandbox seed            Populate the sandbox with synthetic subjects.\n                                 Idempotent: an already-seeded subject is left\n                                 alone, never doubled.\n  credda sandbox reset           Wipe the sandbox and start over.\n\nPublic (no API key):\n  credda lookup <token>          Trust check for a share token\n  credda export <token>          Full self-verifying trust export bundle\n  credda verify <file|->         Offline-verify a credential: a W3C VC-JWT,\n                                 a compact Trust Credential, or a saved trust\n                                 export bundle (auto-detected). '-' = stdin.\n  credda registry                Federated trust registry\n  credda did                     Issuer DID document\n  credda benchmarks              Cohort-benchmark catalog (dimensions + k-anonymity)\n  credda reason-codes            Adverse-action reason-code catalog (ECOA / Reg B)\n  credda outcome-templates [industry]\n                                 How a real-world business maps its work to\n                                 Credda events, and WHO confirms each outcome.\n                                 Guidance only. Optional industry slug filters.\n  credda badges list             Open Badges 3.0 achievements this issuer signs\n  credda badges get <badgeId>    One achievement definition\n  credda professional-record public <token>\n                                 The professional record behind a share token\n                                 (the subject's own consent to present it)\n  credda career-export --token <token>\n                                 The subject's whole verified record as a JSON\n                                 Resume document, behind a share token (the\n                                 subject's own consent, no API key sent)\n\nPlatform (needs CREDDA_API_KEY):\n  credda score <userId>          Current score\n  credda explain <userId>        Factor-level score explanation\n  credda components <userId>     Six named 0-100 score components\n  credda risk <userId>           Advisory risk signals\n  credda trust-summary <userId> [--narrative]\n                                 Deterministic, evidence-based trust summary\n                                 (explains; never a verdict). --narrative adds an\n                                 advisory AI retelling when the server has AI on.\n  credda benchmark <userId> [--dimension <d>]\n                                 Where a subject sits within its cohort:\n                                 percentile + the cohort distribution\n  credda distribution [--dimension <d>] [--cohort <c>]\n                                 Aggregate, k-anonymised cohort distribution.\n                                 Omit --cohort for every cohort on the dimension.\n  credda users [--score-min <n>] [--score-max <n>] [--band <b>]\n        [--subject-type <PERSON|AGENT|ORGANIZATION>] [--scored|--unscored] [--frozen]\n        [--active-since <iso>] [--registered-since <iso>] [--registered-before <iso>]\n        [--verified] [--min-verified <n>]\n        [--sort <score|lastActivity|registered|externalId>] [--order <asc|desc>]\n        [--cursor <c>] [--limit <n>]\n                                 Query + export your book of subjects.\n                                 A subject with no score yet reports null,\n                                 never a placeholder; list those with\n                                 --unscored.\n  credda book-summary [same filters as \"users\"]\n                                 Size a segment WITHOUT paging it: how many\n                                 match, how many are scored, band mix and\n                                 median/mean. Null (not 0) when nothing in the\n                                 segment is scored.\n  credda usage [days] [--from <date> --to <date>] [--csv <outfile>]\n                                 Your platform's metered API usage. Either a\n                                 trailing [days] window OR an inclusive\n                                 --from/--to date range (YYYY-MM-DD), not both.\n                                 --csv writes the flat CSV statement to a file.\n  credda activity [--action <A>] [--from <t> --to <t>] [--cursor <c>] [--limit <n>]\n                                 Your platform's own activity/audit log,\n                                 newest-first, cursor-paginated\n  credda verified-profile <userId>\n                                 How much of a subject's CLAIMED record\n                                 (education/skills/certifications/employment) is\n                                 third-party verified. Counts whether a claim is\n                                 verified, never how prestigious it is, and it\n                                 can never move the Reliability Score.\n  credda qualify <userId> --category <education|skill|certification|employment>\n        [--label <l>] [--issuer <i>] [--verified-by <witness>]\n                                 Record a qualification claim. Always recorded;\n                                 counts as VERIFIED only with a genuine\n                                 third-party --verified-by witness.\n  credda professional-record get <userId>\n                                 R\u00E9sum\u00E9-shaped summary of a VERIFIED work record.\n                                 Describes a record, not a hiring verdict, a\n                                 background check, or a consumer report.\n  credda professional-record credential <userId> [--ttl <seconds>]\n                                 Mint the signed, offline-verifiable Professional\n                                 Record Credential (+ an \"Add to LinkedIn\" link)\n  credda reliability-report <userId> [--recent <n>] [--benchmark]\n                                 The consolidated worker reliability report a\n                                 staffing agency or employer weighs: reliability,\n                                 metrics, verified experience, tenure, ranked\n                                 drivers, recent outcomes. EVIDENCE, not a hire /\n                                 place / rank verdict, a background check, or a\n                                 consumer report. Use --token <token> for the\n                                 public worker-consent route (NO API key).\n  credda career-export <userId>  The subject's whole verified record as an open\n                                 JSON Resume document (jsonresume.org). Describes\n                                 a record, not a hiring verdict or a consumer\n                                 report. Use --token <token> for the public route.\n  credda mint <userId>           Mint a share token for a user\n  credda revoke <userId>         Revoke a user's share token\n\nConfirmation requests: the counterparty-confirmation primitive. You PROPOSE an\noutcome and deliver the one-time token to the counterparty over YOUR OWN channel;\nthe event is written, verified, only when that distinct party confirms:\n  credda confirmations create --user <externalId> --type <eventType>\n        --counterparty <ref> [--counterparty-name <n>] [--description <d>]\n        [--stake <HIGH|MEDIUM|LOW>] [--value <n>] [--due <iso>] [--completed <iso>]\n        [--return-url <url>] [--expires-in <days>] [--idempotency-key <k>]\n                                 Needs CREDDA_API_KEY. Token shown ONCE.\n  credda confirmations batch <file.json> [--idempotency-key <k>]\n                                 The ACTIVATION ENGINE: bulk-create up to 100\n                                 requests from a JSON file (an array of request\n                                 bodies, or { \"requests\": [...] }). Warms a cold\n                                 ledger from your book. Needs CREDDA_API_KEY;\n                                 each ok item's token is shown ONCE.\n  credda confirmations list [--status <s>] [--cursor <c>] [--limit <n>]\n  credda confirmations get <id>\n  credda confirmations cancel <id>\n  credda confirmations preview <id> --token <t>\n                                 What the counterparty is asked to confirm.\n                                 NO API key; the token is the capability.\n  credda confirmations respond <id> --token <t> (--confirm | --decline)\n                                 The counterparty's decision. NO API key.\n                                 --confirm writes the event; --decline writes\n                                 nothing. Single-use either way.\n\nReference requests: the qualifications-half sibling of confirmations. A r\u00E9sum\u00E9\nclaim (employment / education / certification / skill) becomes VERIFIED when the\nnamed third party who was there confirms it. Records no qualification and never\nmoves the reliability score:\n  credda references create --user <externalId>\n        --category <employment|education|certification|skill>\n        --counterparty <ref> [--label <l>] [--issuer <i>] [--jurisdiction <j>]\n        [--reference <r>] [--counterparty-name <n>] [--description <d>]\n        [--return-url <url>] [--expires-in <days>] [--idempotency-key <k>]\n                                 Needs CREDDA_API_KEY. Token shown ONCE.\n  credda references list [--status <s>] [--cursor <c>] [--limit <n>]\n  credda references get <id>\n  credda references cancel <id>\n  credda references preview <id> --token <t>\n                                 What the reference is asked to confirm.\n                                 NO API key; the token is the capability.\n  credda references respond <id> --token <t> (--confirm | --decline)\n                                 The reference's decision. NO API key.\n                                 --confirm records the qualification; --decline\n                                 writes nothing. Single-use either way.\n\nThreshold policies (needs CREDDA_API_KEY): declarative \"tell me when this line\nis crossed\"; delivers policy.threshold_crossed through your webhooks. Config\nonly: a policy never reads into, blocks, or changes a score:\n  credda policies list [--cursor <c>] [--limit <n>]\n  credda policies get <id>\n  credda policies create --name <n> (--user <externalId> | --all)\n        --metric <score|component|band|verified_events>\n        [--direction <up|down|enter|leave>] [--threshold <n>]\n        [--component <reliability|timeliness|trustworthiness|verification|consistency|momentum>]\n        [--band <b>]\n  credda policies update <id> [--name <n>] [--direction <d>] [--threshold <n>]\n        [--component <c>] [--band <b>] [--activate | --deactivate]\n                                 The metric is immutable; delete + recreate.\n  credda policies delete <id>\n\nScore monitors (needs CREDDA_API_KEY): edge-triggered watches that deliver\n\"monitor.triggered\" through your webhooks; notification config only, a\nmonitor never affects a score:\n  credda monitors list [--cursor <c>] [--limit <n>]\n  credda monitors get <id>\n  credda monitors create --user <externalId> [--below <score>] [--above <score>] [--band-change]\n                                 At least one condition required. --below fires\n                                 on a downward crossing (and on a first score\n                                 already below it), --above on an upward\n                                 crossing, --band-change on any band change.\n  credda monitors delete <id>\n\nBulk screenings (needs CREDDA_API_KEY): async batch score reads, up to\n10,000 ids per job, strictly read-only:\n  credda screen <ids...>         Submit ids (comma/space separated), or:\n  credda screen --file <path>    One id per line, or a CSV whose FIRST column\n                                 is the id (a leading \"id\"/\"userId\"/\n                                 \"externalId\" header row is skipped).\n         [--wait]                Poll until the job finishes, then print the\n                                 summary (exit 1 if the job FAILED).\n  credda screenings list [--cursor <c>] [--limit <n>]\n  credda screenings get <id>     Job status + summary\n  credda screenings results <id> [--csv <outfile>]\n                                 Per-user results (JSON; --csv writes the CSV\n                                 attachment to a file instead)\n\nWebhooks (needs CREDDA_API_KEY):\n  credda webhooks list                     Your webhook subscriptions\n  credda webhooks create <url> <event..>   Subscribe (secret shown ONCE)\n  credda webhooks delete <id>              Remove a webhook\n  credda webhooks test <id>                Send a synthetic signed delivery\n  credda webhooks deliveries <id>          Recent delivery attempts (incl. retries)\n  credda webhooks recent [event..]         Recent events across ALL your endpoints\n                                           (sample data for automation platforms;\n                                           falls back to catalog examples, flagged\n                                           isExample, when nothing has fired yet)\n\nLocal development:\n  credda listen [port]           Local webhook receiver: verifies each delivery's\n                                 HMAC signature (CREDDA_WEBHOOK_SECRET) and\n                                 pretty-prints the payload. Default port 4141.\n                                 Credda delivers to public HTTPS only; expose\n                                 this port with your own tunnel (e.g. cloudflared).\n\nEnvironment:\n  CREDDA_API_URL                 API base (default https://api.credda.io)\n  CREDDA_API_KEY                 Platform API key for keyed commands\n  CREDDA_WEBHOOK_SECRET          whsec_\u2026 signing secret for \"credda listen\"\n\nExit codes: 0 ok/valid \u00B7 1 error \u00B7 2 credential failed verification";
 /** Raw-key prefix the API stamps on a sandbox key (lib/testMode.ts). */
 export declare const TEST_KEY_PREFIX = "crd_test_";
@@ -52,7 +52,7 @@ export declare const TEST_KEY_PREFIX = "crd_test_";
  * A sandbox key, or an error that says exactly what to do next.
  *
  * The server refuses a live key anyway (`403 TEST_MODE_ONLY`), but a first-run
- * user does not deserve a 403 to interpret — the prefix is visible locally, so
+ * user does not deserve a 403 to interpret: the prefix is visible locally, so
  * the actionable message costs one string comparison. This is the "better
  * first-run errors" rule applied to the single most likely first mistake.
  */
@@ -65,7 +65,7 @@ export declare function requireSandboxKey(ctx: CliContext): string;
  * Also surfaces the machine code (so it can be looked up in
  * `GET /api/v1/errors`) and any `Retry-After` the server asked for.
  *
- * Duck-typed rather than `instanceof CreddaError` on purpose — the router
+ * Duck-typed rather than `instanceof CreddaError` on purpose: the router
  * imports only TYPES from the SDK, so it stays pure and trivially mockable.
  * Pure and exported for testing.
  */
@@ -84,10 +84,10 @@ export declare function parseFlags(args: string[], spec?: {
 };
 /**
  * Parse the ids for `credda screen`. Inline args may be comma- and/or
- * space-separated. A file is one id per line — or a CSV, in which case only
+ * space-separated. A file is one id per line, or a CSV, in which case only
  * the FIRST column is read (a leading header row named id/userId/externalId
  * is skipped). Deduped, order-preserving. Deliberately simple: no quoted-CSV
- * handling — an id containing a comma isn't a valid external id anyway.
+ * handling (an id containing a comma isn't a valid external id anyway).
  */
 export declare function parseIdList(input: {
     inline?: string[];

package/dist/cli.js

@@ -1,13 +1,13 @@
 /**
- * Command router — pure of process/env/fs so it's testable with a mocked
+ * Command router: pure of process/env/fs so it's testable with a mocked
  * context (same pattern as packages/mcp's tools.ts).
  *
  * Every command is READ-ONLY against Credda's deterministic score. Nothing
- * here writes an Event, adjusts a score, or makes a trust decision — the CLI
+ * here writes an Event, adjusts a score, or makes a trust decision: the CLI
  * looks up and offline-verifies EXISTING, already-computed trust facts.
  * `mint`/`revoke` manage a share token (a capability, not a score write).
  */
-export const VERSION = '0.1.3';
+export const VERSION = '0.1.6';
 export const HELP = `credda: portable trust from the terminal
 
 Start here (needs a sandbox CREDDA_API_KEY, the crd_test_ kind):
@@ -243,7 +243,7 @@ export const TEST_KEY_PREFIX = 'crd_test_';
  * A sandbox key, or an error that says exactly what to do next.
  *
  * The server refuses a live key anyway (`403 TEST_MODE_ONLY`), but a first-run
- * user does not deserve a 403 to interpret — the prefix is visible locally, so
+ * user does not deserve a 403 to interpret: the prefix is visible locally, so
  * the actionable message costs one string comparison. This is the "better
  * first-run errors" rule applied to the single most likely first mistake.
  */
@@ -278,7 +278,7 @@ function show(ctx, value) {
  * Also surfaces the machine code (so it can be looked up in
  * `GET /api/v1/errors`) and any `Retry-After` the server asked for.
  *
- * Duck-typed rather than `instanceof CreddaError` on purpose — the router
+ * Duck-typed rather than `instanceof CreddaError` on purpose: the router
  * imports only TYPES from the SDK, so it stays pure and trivially mockable.
  * Pure and exported for testing.
  */
@@ -391,10 +391,10 @@ function bookFilterFlags(flags) {
 const ID_HEADER_NAMES = /^(id|userid|user_id|externalid|external_id)$/i;
 /**
  * Parse the ids for `credda screen`. Inline args may be comma- and/or
- * space-separated. A file is one id per line — or a CSV, in which case only
+ * space-separated. A file is one id per line, or a CSV, in which case only
  * the FIRST column is read (a leading header row named id/userId/externalId
  * is skipped). Deduped, order-preserving. Deliberately simple: no quoted-CSV
- * handling — an id containing a comma isn't a valid external id anyway.
+ * handling (an id containing a comma isn't a valid external id anyway).
  */
 export function parseIdList(input) {
     const raw = [];
@@ -440,7 +440,7 @@ export function classifyCredentialInput(raw) {
         }
     }
     catch {
-        // not JSON — fall through to string formats
+        // not JSON: fall through to string formats
     }
     if (/^eyJ[\w-]*\.[\w-]+\.[\w-]+$/.test(trimmed)) {
         return { kind: 'vc-jwt', jwt: trimmed };
@@ -486,13 +486,13 @@ export async function runCli(argv, ctx) {
                 const idWidth = Math.max(...seed.subjects.map((s) => s.userId.length), 7);
                 ctx.out(`${pad('SUBJECT', idWidth)}  SCORE  BAND`);
                 for (const s of seed.subjects) {
-                    const score = s.finalScore === null ? '—' : String(s.finalScore);
-                    ctx.out(`${pad(s.userId, idWidth)}  ${pad(score, 5)}  ${s.scoreBand ?? '—'}`);
+                    const score = s.finalScore === null ? 'none' : String(s.finalScore);
+                    ctx.out(`${pad(s.userId, idWidth)}  ${pad(score, 5)}  ${s.scoreBand ?? 'none'}`);
                 }
                 ctx.out('');
                 for (const s of seed.subjects)
                     ctx.out(`${s.userId}: ${s.record}`);
-                // Prove a plain read works — this is the call their integration makes.
+                // Prove a plain read works: this is the call their integration makes.
                 const first = seed.subjects[0];
                 if (first) {
                     ctx.out('');
@@ -505,7 +505,7 @@ export async function runCli(argv, ctx) {
                 // counterparty-CONFIRMED evidence, and a developer used to be able to
                 // finish the entire on-ramp without meeting POST /confirmations. So
                 // the quickstart now closes the loop for real: propose an outcome,
-                // then respond as the counterparty (legitimate here — the create
+                // then respond as the counterparty (legitimate here: the create
                 // response hands the raw token to whoever made the request, and this
                 // is their own disposable sandbox), and print the verified event id.
                 //
@@ -542,7 +542,7 @@ export async function runCli(argv, ctx) {
                     ctx.out('');
                     ctx.out('  3. POST /api/v1/confirmations/{id}/respond   (NO api key, token only)');
                     const decided = await ctx.client.respondToConfirmation(created.confirmation.id, created.confirmationToken, 'confirm');
-                    ctx.out(`     → ${decided.status}, ledger event ${decided.eventId ?? '—'}`);
+                    ctx.out(`     → ${decided.status}, ledger event ${decided.eventId ?? '(none)'}`);
                     ctx.out('     isVerified: true, earned, because a distinct token-holder acted. Declining');
                     ctx.out('     would have written nothing at all: no confirmation is never read as a bad outcome.');
                     ctx.out('');
@@ -614,13 +614,13 @@ export async function runCli(argv, ctx) {
                 return 0;
             case 'reason-codes':
                 // Public adverse-action reason-code catalog (ECOA / Reg B). Credda
-                // supplies the attribution only — it is not a creditor.
+                // supplies the attribution only: it is not a creditor.
                 show(ctx, await ctx.client.getReasonCodes());
                 return 0;
             case 'outcome-templates': {
                 // Public catalog: how a real-world business maps its work to Credda
                 // events, and WHO the third-party witness is for each outcome. Guidance
-                // only — nothing here scores, writes, or ranks anyone. Optional
+                // only: nothing here scores, writes, or ranks anyone. Optional
                 // positional industry slug filters to one set.
                 const [industry] = args;
                 show(ctx, await ctx.client.getOutcomeTemplates(industry));
@@ -663,7 +663,7 @@ export async function runCli(argv, ctx) {
                 return 0;
             }
             case 'benchmark': {
-                // Where one subject sits within a cohort — percentile + distribution.
+                // Where one subject sits within a cohort: percentile + distribution.
                 const { positional, flags } = parseFlags(args, { valued: ['dimension'] });
                 const userId = requireArg(positional, 'userId');
                 show(ctx, await ctx.client.getUserBenchmark(userId, requireKey(ctx), {
@@ -706,7 +706,7 @@ export async function runCli(argv, ctx) {
                 return 0;
             }
             case 'book-summary': {
-                // Size a segment of the book without paging it — same closed filter set.
+                // Size a segment of the book without paging it (same closed filter set).
                 const { positional, flags } = parseFlags(args, {
                     valued: [
                         'score-min', 'score-max', 'band', 'subject-type', 'active-since',
@@ -766,12 +766,12 @@ export async function runCli(argv, ctx) {
                 return 0;
             }
             case 'verified-profile':
-                // A SECOND measure over the same ledger — it can never move a score.
+                // A SECOND measure over the same ledger (it can never move a score).
                 show(ctx, await ctx.client.getVerifiedProfile(requireArg(args, 'userId'), requireKey(ctx)));
                 return 0;
             case 'qualify': {
                 // The claim is ALWAYS recorded; --verified-by decides whether it counts
-                // as verified. Never assert it yourself — name the witness.
+                // as verified. Never assert it yourself: name the witness.
                 const { positional, flags } = parseFlags(args, {
                     valued: ['category', 'label', 'issuer', 'verified-by'],
                 });
@@ -887,8 +887,8 @@ export async function runCli(argv, ctx) {
                         return 0;
                     }
                     case 'batch': {
-                        // The ACTIVATION ENGINE — bulk-create up to 100 requests from a
-                        // JSON file: either an array of request bodies, or { requests: [...] }.
+                        // The ACTIVATION ENGINE: bulk-create up to 100 requests from a
+                        // JSON file (either an array of request bodies, or { requests: [...] }).
                         const { positional, flags } = parseFlags(rest, { valued: ['idempotency-key'] });
                         const file = requireArg(positional, 'file');
                         const parsed = JSON.parse(await ctx.readInput(file));
@@ -918,7 +918,7 @@ export async function runCli(argv, ctx) {
                         show(ctx, await ctx.client.cancelConfirmation(requireArg(rest, 'id'), requireKey(ctx)));
                         return 0;
                     case 'preview': {
-                        // KEYLESS on purpose — the counterparty holds a token, not a key.
+                        // KEYLESS on purpose: the counterparty holds a token, not a key.
                         const { positional, flags } = parseFlags(rest, { valued: ['token'] });
                         const id = requireArg(positional, 'id');
                         const token = strFlag(flags, 'token');
@@ -1005,7 +1005,7 @@ export async function runCli(argv, ctx) {
                         show(ctx, await ctx.client.cancelReference(requireArg(rest, 'id'), requireKey(ctx)));
                         return 0;
                     case 'preview': {
-                        // KEYLESS on purpose — the reference holds a token, not a key.
+                        // KEYLESS on purpose: the reference holds a token, not a key.
                         const { positional, flags } = parseFlags(rest, { valued: ['token'] });
                         const id = requireArg(positional, 'id');
                         const token = strFlag(flags, 'token');
@@ -1261,7 +1261,7 @@ export async function runCli(argv, ctx) {
                         show(ctx, await ctx.client.getWebhookDeliveries(requireArg(rest, 'id'), key, 25));
                         return 0;
                     case 'recent': {
-                        // Sample data across ALL endpoints — falls back to the event
+                        // Sample data across ALL endpoints: falls back to the event
                         // catalog's examples (isExample:true) when nothing has fired yet.
                         const eventType = rest.length > 0 ? rest : undefined;
                         show(ctx, await ctx.client.getRecentWebhookEvents(key, { limit: 25, eventType }));
@@ -1294,7 +1294,7 @@ export async function runCli(argv, ctx) {
     }
     catch (e) {
         const message = e instanceof Error ? e.message : String(e);
-        // SDK errors already carry a "credda:" prefix — don't double it.
+        // SDK errors already carry a "credda:" prefix. Don't double it.
         ctx.err(message.startsWith('credda:') ? message : `credda: ${message}`);
         for (const line of errorHints(e))
             ctx.err(line);

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * `credda` — entry point. All logic lives in cli.ts (testable); this file only
+ * `credda`: entry point. All logic lives in cli.ts (testable); this file only
  * wires the real environment: env vars, stdin/file reading, process exit.
  */
 export {};

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * `credda` — entry point. All logic lives in cli.ts (testable); this file only
+ * `credda`: entry point. All logic lives in cli.ts (testable); this file only
  * wires the real environment: env vars, stdin/file reading, process exit.
  */
 import { readFile, writeFile } from 'node:fs/promises';
@@ -16,10 +16,16 @@ async function readInput(pathOrDash) {
     }
     return readFile(pathOrDash, 'utf8');
 }
-// Raw authenticated GET for the CSV endpoints (?format=csv) — the typed SDK
+// Raw authenticated GET for the CSV endpoints (?format=csv): the typed SDK
 // returns parsed JSON only and documents CSV as a raw-fetch use case. Built
 // from the same base URL the client is configured with.
 const API_BASE = (process.env.CREDDA_API_URL ?? 'https://api.credda.io').replace(/\/+$/, '');
+/**
+ * The did:web identity of the API this CLI talks to, and the issuer every
+ * verification expects. `https://api.credda.io` is `did:web:api.credda.io`;
+ * point CREDDA_API_URL at staging and the expectation follows it.
+ */
+const ISSUER_DID = `did:web:${new URL(API_BASE).host.toLowerCase()}`;
 async function fetchCsv(path, apiKey) {
     const res = await fetch(`${API_BASE}/api/v1${path}`, {
         headers: { Authorization: `Bearer ${apiKey}` },
@@ -37,7 +43,7 @@ async function fetchCsv(path, apiKey) {
     }
     return res.text();
 }
-// process.exitCode (not process.exit()) — a hard exit right after a fetch
+// process.exitCode (not process.exit()): a hard exit right after a fetch
 // trips a libuv assertion on Windows Node while handles are still closing.
 process.exitCode = await runCli(process.argv.slice(2), {
     client: new CreddaClient({ apiBase: process.env.CREDDA_API_URL }),
@@ -49,9 +55,22 @@ process.exitCode = await runCli(process.argv.slice(2), {
     out: (line) => console.log(line),
     err: (line) => console.error(line),
     readInput,
+    // ⚠️ EVERY VERIFIER IS TOLD WHICH ISSUER IT EXPECTS.
+    //
+    // `credda verify` reads a credential handed over by somebody else, which is
+    // the whole point of it. did:web resolution proves the credential was signed
+    // by whoever controls the DID's host; it does NOT prove that host is Credda.
+    // Without an expected issuer, a credential minted by anyone with a domain
+    // verifies clean and the CLI prints it as valid.
+    //
+    // Stated explicitly rather than left to the SDK default, because this CLI
+    // pins an SDK line that does not have that default, and because a call site
+    // that says what it expects keeps saying it after the dependency moves.
+    // ISSUER_DID follows CREDDA_API_URL, so a CLI pointed at staging expects
+    // staging's issuer rather than production's.
     verifiers: {
         trustCredential: (credential) => verifyTrustCredential(credential),
-        verifiableCredential: (vcJwt) => verifyVerifiableCredential(vcJwt),
-        trustExport: (bundle) => verifyTrustExport(bundle),
+        verifiableCredential: (vcJwt) => verifyVerifiableCredential(vcJwt, { apiBase: API_BASE, issuer: ISSUER_DID }),
+        trustExport: (bundle) => verifyTrustExport(bundle, { apiBase: API_BASE, issuer: ISSUER_DID }),
     },
 });

package/dist/listener.d.ts

@@ -1,12 +1,12 @@
 /**
- * `credda listen` — a local webhook receiver for development.
+ * `credda listen`: a local webhook receiver for development.
  *
  * Accepts POSTs on a local port, verifies each delivery's HMAC signature with
  * the webhook's signing secret (when provided), and pretty-prints the payload.
  * Responds 200 so a tunneled Credda delivery counts as delivered.
  *
  * Honest scope: Credda only delivers to public HTTPS endpoints, so this does
- * NOT tunnel by itself — put your own tunnel in front (cloudflared, ngrok, …)
+ * NOT tunnel by itself: put your own tunnel in front (cloudflared, ngrok, …)
  * and register the tunnel URL as the webhook. What this gives you is the
  * Stripe-CLI-style local loop: see every delivery, verify its signature the
  * same way your production handler must, and iterate without redeploying.

package/dist/listener.js

@@ -1,12 +1,12 @@
 /**
- * `credda listen` — a local webhook receiver for development.
+ * `credda listen`: a local webhook receiver for development.
  *
  * Accepts POSTs on a local port, verifies each delivery's HMAC signature with
  * the webhook's signing secret (when provided), and pretty-prints the payload.
  * Responds 200 so a tunneled Credda delivery counts as delivered.
  *
  * Honest scope: Credda only delivers to public HTTPS endpoints, so this does
- * NOT tunnel by itself — put your own tunnel in front (cloudflared, ngrok, …)
+ * NOT tunnel by itself: put your own tunnel in front (cloudflared, ngrok, …)
  * and register the tunnel URL as the webhook. What this gives you is the
  * Stripe-CLI-style local loop: see every delivery, verify its signature the
  * same way your production handler must, and iterate without redeploying.
@@ -46,7 +46,7 @@ export function startListener(opts) {
                         pretty = JSON.stringify(parsed, null, 2);
                     }
                     catch {
-                        // non-JSON body — print raw
+                        // non-JSON body: print raw
                     }
                     console.log(`\n── ${time} · ${req.method} ${req.url} · ${String(eventType)} · ${verdict}`);
                     console.log(pretty);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@credda/cli",
-  "version": "0.1.4",
-  "description": "Official Credda CLI — look up and offline-verify portable trust from the terminal: public trust checks, credential verification, platform score reads, share-token minting. A thin client over @credda/js; no scoring logic lives here.",
+  "version": "0.1.6",
+  "description": "Official Credda CLI: look up and offline-verify portable trust from the terminal. Public trust checks, credential verification, platform score reads, share-token minting. A thin client over @credda/js; no scoring logic lives here.",
   "license": "MIT",
   "homepage": "https://github.com/Credda-io/credda-cli#readme",
   "bugs": {
@@ -25,7 +25,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@credda/js": "^0.6.0"
+    "@credda/js": "^0.8.0"
   },
   "devDependencies": {
     "@types/node": "^20.14.2",
@@ -39,5 +39,17 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Credda-io/credda-cli.git"
+  },
+  "keywords": [
+    "credda",
+    "cli",
+    "command-line",
+    "trust",
+    "reliability-score",
+    "verifiable-credentials",
+    "sdk"
+  ],
+  "engines": {
+    "node": ">=18"
   }
 }