@credda/cli 0.1.5 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/CHANGELOG.md +71 -0
  2. package/README.md +223 -274
  3. package/dist/args.d.ts +99 -0
  4. package/dist/args.js +222 -0
  5. package/dist/commands.d.ts +153 -0
  6. package/dist/commands.js +1192 -0
  7. package/dist/index.d.ts +41 -4
  8. package/dist/index.js +41 -55
  9. package/package.json +25 -12
  10. package/dist/cli.d.ts +0 -108
  11. package/dist/cli.js +0 -1303
  12. package/dist/listener.d.ts +0 -17
  13. package/dist/listener.js +0 -73
package/CHANGELOG.md ADDED
@@ -0,0 +1,71 @@
1
+ # Changelog
2
+
3
+ ## 1.0.0 — 2026-09-08 — BREAKING: this package no longer installs a `credda` command
4
+
5
+ **If you installed `@credda/cli` at 0.1.6 or earlier, upgrading removes a binary
6
+ you may be using. Read this before upgrading, and pin `0.1.6` if you need the
7
+ old behaviour while you migrate.**
8
+
9
+ ### What changed
10
+
11
+ Every version up to and including 0.1.6 published a different product under this
12
+ name: a command-line client for a 0–100 reliability score and portable
13
+ trust credentials, a thin client over `@credda/js`. Credda no longer builds that
14
+ product. All of its commands — `score`, `explain`, `components`, `risk`,
15
+ `verify`, `lookup`, `export`, `mint`, `revoke`, `confirmations`, `references`,
16
+ `policies`, `monitors`, `screen`, `webhooks`, `listen` and the rest — are gone,
17
+ along with the `@credda/js` dependency they ran on.
18
+
19
+ Credda is now a system that investigates defects and vulnerabilities in a
20
+ customer's production and QA environments. Its CLI is published to npm as the
21
+ **unscoped `credda` package**, and that package owns the `credda` executable.
22
+
23
+ ### Why the executable was removed rather than replaced
24
+
25
+ Both packages installed a binary called `credda`. On a machine with both, the
26
+ one installed second wins and the other silently stops working. This package
27
+ gives the name up: `@credda/cli` 1.0.0 declares no `bin` at all.
28
+
29
+ ### What this package is now
30
+
31
+ The public source mirror and issue tracker for the `credda` CLI's command
32
+ surface — the role this repository's README already claimed. It exports the
33
+ command table and argument parser, copied byte for byte from the engine
34
+ repository, so tooling can ask offline what `credda` accepts. It runs nothing.
35
+
36
+ ### Migration
37
+
38
+ | You were doing | Do this now |
39
+ | --- | --- |
40
+ | `npm i -g @credda/cli` for the `credda` binary | `npm i -g credda` — a different product; read its README first |
41
+ | Using the trust-score commands | Nothing here replaces them. Pin `@credda/cli@0.1.6`; it is unchanged and still installable. |
42
+ | Importing from `@credda/cli` | There was no supported import surface before 1.0.0. There is one now: `import { COMMANDS } from '@credda/cli'`. |
43
+
44
+ Nothing has been unpublished. `0.1.6` remains on the registry exactly as it was.
45
+
46
+ ### The command surface gained `credda cancel`, and a seventh exit code
47
+
48
+ Mirrored from the engine on 2026-08-29. `credda cancel <id>` stops a run started
49
+ in another terminal on the same machine, and it reports what stopping actually
50
+ achieved rather than reporting success either way.
51
+
52
+ The two answers are kept apart in the exit code because they are two different
53
+ claims about the reader's own machine and their own bill:
54
+
55
+ | Code | Claim |
56
+ | --- | --- |
57
+ | `0` | Nothing is running. The run had not started, its process is gone, or it was already cancelled. |
58
+ | `7` | `CANCELLATION_REQUESTED`. A process is **still inside the run**, holding a sandbox and possibly a model call. It was signalled and it stops at its next checkpoint, writing its own terminal state. |
59
+ | `2` | It already finished, or it is executing somewhere unreachable — in which case nothing was written to it. |
60
+
61
+ `7` is new and is not a renumbering: `0` through `6` mean exactly what they meant
62
+ in 1.0.0. It is separate from `4`, which is `credda investigate` reporting that a
63
+ run it was executing ended; `7` is a different process reporting that it asked
64
+ one to, without knowing whether it did.
65
+
66
+ The statuses are the ones `POST /api/investigations/:id/cancel` returns, spelled
67
+ identically.
68
+
69
+ Also mirrored: `credda validations` and `credda validation <id>`, which were
70
+ copied into `src/commands.ts` before this changelog recorded them, and are now
71
+ listed in the README's command table.
package/README.md CHANGED
@@ -1,304 +1,253 @@
1
- > 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.
1
+ <p align="center">
2
+ <a href="https://credda.io">
3
+ <img alt="Credda" width="96" height="96"
4
+ src="https://raw.githubusercontent.com/Credda-io/credda-cli/main/assets/credda-mark-spectrum.png">
5
+ </a>
6
+ </p>
2
7
 
3
8
  # @credda/cli
4
9
 
5
- The official Credda CLI: portable trust from the terminal. A thin client over
6
- [`@credda/js`](https://www.npmjs.com/package/@credda/js)'s headless export;
7
- **no scoring logic lives here** (the deterministic score is computed only by
8
- the API's `score.service`).
9
-
10
- ## Install
11
-
12
- ```sh
13
- npm install -g @credda/cli # or: pnpm add -g @credda/cli
14
- credda help
15
- ```
16
-
17
- Node 20 or newer. Nothing else to configure for the public commands below.
18
-
19
- Prefer not to install globally? `npx @credda/cli help` works the same way.
20
-
21
- `credda help` always lists exactly what the version you installed can do, so
22
- treat it, not this file, as the authority on your copy. `credda --version`
23
- prints that version.
24
-
25
- ## Commands
26
-
27
- Start here, if you hold a sandbox key (`CREDDA_API_KEY` of the `crd_test_`
28
- kind; a live key is refused before anything happens):
10
+ **This package installs no command.** It is the public source mirror and issue
11
+ tracker for the command surface of the Credda CLI, which is published to npm
12
+ under its own, unscoped name:
29
13
 
30
14
  ```sh
31
- credda quickstart # seed the sandbox with synthetic subjects, print
32
- # their real scores, then close the counterparty-
33
- # confirmation loop so you finish holding a real
34
- # VERIFIED event rather than a number you read
35
- --no-confirm # stop after the seed; skip the confirmation loop
15
+ npm install -g credda # the CLI itself
16
+ credda --help
36
17
  ```
37
18
 
38
- Public — no API key:
19
+ Node 24 or newer for `credda`. This mirror package needs Node 18 and is a
20
+ library, not a tool.
21
+
22
+ > **Not installable yet — re-checked 2026-08-30.** The `credda` package is not on
23
+ > the public npm registry (`https://registry.npmjs.org/credda` returns 404), so
24
+ > the command above fails today. The latest `@credda/cli` on npm is still
25
+ > **0.1.6**, the retired 0.x described below; the `1.0.0` in this repository's
26
+ > `package.json` is unpublished on purpose — see [RELEASE.md](RELEASE.md), which
27
+ > holds publication until a human has agreed to redefine a live package name.
28
+ > Treat this block as what the install *will* be, not as a command that works
29
+ > now.
30
+
31
+ > ### The 0.1.6 break
32
+ >
33
+ > Up to and including **0.1.6**, `npm i -g @credda/cli` installed something
34
+ > else entirely: a client for a 0–100 reliability score and portable trust
35
+ > credentials. Credda no longer builds that product, and every one of those
36
+ > commands is gone from **1.0.0**.
37
+ >
38
+ > 0.1.6 also installed a binary named `credda`. So does the `credda` package.
39
+ > Two packages cannot own one executable name, so this one gives it up: 1.0.0
40
+ > declares no `bin`. If you depend on the old behaviour, **pin
41
+ > `@credda/cli@0.1.6`** — it is untouched and still on the registry, nothing has
42
+ > been unpublished — and read [CHANGELOG.md](CHANGELOG.md) for the migration.
43
+
44
+ ## What Credda is
45
+
46
+ A customer labels a bug report or a security vulnerability. Credda reproduces
47
+ the failure, diagnoses the cause, writes the patch, proves it with a test that
48
+ fails before and passes after, and hands back a diff. Whether that diff becomes a
49
+ pull request depends on which mechanism delivered it, and the two answer
50
+ differently: the **GitHub App** path opens one with no flag and no switch, for a
51
+ run that reaches `READY_FOR_REVIEW` with a proven verdict; the **GitHub Action**
52
+ opens none unless you set its `open-pull-request` input, which defaults to
53
+ `false` -- and that input is declared on no version a caller can reach: it is
54
+ absent from `action.yml` at the `v1` tag and on the action's default branch
55
+ alike, so setting it today parses, runs green and delivers nothing. How often a
56
+ run reaches a proven fix at all has not been measured. It proposes. It never merges.
57
+
58
+ The developer surface is [api.credda.io](https://api.credda.io) — the
59
+ [API reference](https://api.credda.io/reference) and
60
+ [`openapi.json`](https://api.credda.io/openapi.json).
61
+
62
+ **Status of the fix path, as of 2026-08-23 — superseded, kept because it is the
63
+ measurement:** the Fixer, the Verifier and pull-request authoring were built and
64
+ tested and off the shipped path. The gate was a model-backed run: across all
65
+ seven engine databases in the tree there were **468 investigations, 0 patches
66
+ and 0 verification runs**, and every `model_usage` row carried
67
+ `provider='heuristic'` with zero tokens (`docs/strategy/v41-gates.md`). There was
68
+ deliberately **no flag that turns it on**, because a flag would have put an
69
+ unevidenced claim one environment variable away from a customer.
70
+
71
+ **What changed, 2026-08-27 and 2026-08-28.** A model-backed run happened, which
72
+ was the condition the paragraph above named. ADR 0019 superseded ADR 0015's
73
+ scoping decision and put the Fixer and the Verifier back on the investigation
74
+ path; the following day the engine's forge delivery path was wired to open a
75
+ pull request for a run that reaches a proven verdict. That path takes no flag
76
+ and no opt-in switch; the `open-pull-request` input that defaults to `false` is
77
+ the **GitHub Action**'s, a separate mechanism that runs on the caller's own
78
+ runner. The gate that replaced the absent flag is not a flag either: it is
79
+ `provider.isGenerative` in the orchestrator, so the stage is entered when a
80
+ model-backed provider is configured and skipped when one is not. A heuristic patch is worse than none. See ADR 0018,
81
+ *The product is the fix*, and ADR 0019.
82
+
83
+ What the shipped CLI therefore does today: prepare an environment, reproduce the
84
+ reported failure, capture its failure signature as evidence, diagnose a cause
85
+ where the evidence supports one, and — where a model-backed provider is
86
+ configured — write a patch and prove it. Against the deterministic heuristic
87
+ provider it reaches diagnosis and stops there, and reports the stages it did not
88
+ enter as not attempted rather than as a measured zero. That rule is older than
89
+ this change and survives it: nothing may report a stage that did not run as a
90
+ zero.
91
+
92
+ ## The command surface
93
+
94
+ Read off `src/commands.ts`, which is a byte-for-byte copy of the engine's own
95
+ command table. `credda --help` is generated from that same table, so it is the
96
+ authority on the copy you installed.
39
97
 
40
- ```sh
41
- credda lookup <token> # trust check for a share token (GET /verify/:token)
42
- credda export <token> # full self-verifying trust export bundle
43
- credda verify <file|-> # OFFLINE-verify a credential someone handed you:
44
- # a W3C VC-JWT, a compact Trust Credential, or a
45
- # saved trust-export bundle — auto-detected.
46
- # '-' reads stdin. Exit 0 valid / 2 invalid.
47
- credda registry # federated trust registry (/.well-known)
48
- credda did # issuer DID document
49
- credda benchmarks # cohort-benchmark catalog: the dimensions you can
50
- # benchmark on and the k-anonymity floor below
51
- # which no cohort is disclosed
52
- credda reason-codes # adverse-action reason-code catalog (ECOA / Reg B).
53
- # Credda supplies the attribution only — it is not
54
- # a creditor and issues no notice.
55
- credda badges list # the closed set of Open Badges 3.0 achievements
56
- credda badges get <badgeId> # this issuer will sign, and one definition
57
- credda outcome-templates [industry]
58
- # how a business maps its work to Credda events, and
59
- # WHO confirms each outcome. Guidance only.
60
- credda professional-record public <token>
61
- # the professional record behind a share token —
62
- # the token IS the subject's consent to present it
63
- credda career-export --token <token>
64
- # the whole verified record as a JSON Resume document,
65
- # behind a share token (no API key sent)
66
98
  ```
67
-
68
- Platform — set `CREDDA_API_KEY` (a `crd_live_…` platform key):
69
-
70
- ```sh
71
- credda score <userId> # current score
72
- credda explain <userId> # factor-level explanation
73
- credda components <userId> # six named 0-100 components
74
- credda risk <userId> # advisory risk signals
75
- credda trust-summary <userId> [--narrative]
76
- # deterministic, evidence-based summary + strengths
77
- # + risks. It explains; it is never a verdict.
78
- # --narrative adds an advisory AI retelling.
79
- credda benchmark <userId> [--dimension <d>]
80
- # where the subject sits in its cohort: percentile
81
- # + the cohort distribution. `available:false`
82
- # when the cohort is below the k-anonymity floor
83
- # (insufficient_data) or the subject has no score
84
- # yet (no_score).
85
- credda distribution [--dimension <d>] [--cohort <c>]
86
- # aggregate, k-anonymised cohort distribution.
87
- # Omit --cohort for every cohort on the dimension.
88
- credda users [--score-min <n>] [--score-max <n>] [--band <b>]
89
- [--subject-type <PERSON|AGENT|ORGANIZATION>]
90
- [--scored|--unscored] [--frozen]
91
- [--active-since <iso>] [--registered-since <iso>]
92
- [--registered-before <iso>] [--verified] [--min-verified <n>]
93
- [--sort <score|lastActivity|registered|externalId>]
94
- [--order <asc|desc>] [--cursor <c>] [--limit <n>]
95
- # query + export your book of subjects. The filter
96
- # set is closed and validated — no query DSL.
97
- # A subject with no score yet reports null, never
98
- # a placeholder; list those with --unscored.
99
- credda book-summary [same filters as "users"]
100
- # size a segment WITHOUT paging it: how many match,
101
- # how many are scored, band mix, median/mean.
102
- # Null (not 0) when nothing in it is scored.
103
- credda usage [days] # your platform's metered usage (trailing window)
104
- credda usage --from 2026-06-01 --to 2026-06-30
105
- # explicit statement range (mutually exclusive
106
- # with [days])
107
- credda usage --csv usage.csv
108
- # write the flat CSV statement to a file
109
- # (raw ?format=csv fetch; combines with either window)
110
- credda activity [--action <A>] [--from <t>] [--to <t>] [--cursor <c>] [--limit <n>]
111
- # your platform's own activity/audit log,
112
- # newest-first, cursor-paginated
113
- credda verified-profile <userId>
114
- # how much of a subject's CLAIMED record
115
- # (education/skills/certifications/employment) is
116
- # third-party verified. Counts WHETHER a claim is
117
- # verified, never how prestigious it is — and can
118
- # never move the Reliability Score.
119
- credda qualify <userId> --category <education|skill|certification|employment>
120
- [--label <l>] [--issuer <i>] [--verified-by <witness>]
121
- # record a qualification claim. Always recorded;
122
- # counts as VERIFIED only with a genuine
123
- # third-party --verified-by witness.
124
- credda professional-record get <userId>
125
- # résumé-shaped summary of a VERIFIED work record.
126
- # Describes a record — not a hiring verdict, a
127
- # background check, or a consumer report.
128
- credda professional-record credential <userId> [--ttl <seconds>]
129
- # mint the signed, offline-verifiable credential
130
- # (+ an "Add to LinkedIn" certification link)
131
- credda reliability-report <userId> [--recent <n>] [--benchmark]
132
- # the consolidated worker reliability report a
133
- # staffing agency or employer weighs. EVIDENCE, not
134
- # a hire / place / rank verdict or a consumer report.
135
- # Use --token <token> for the public worker-consent
136
- # route (NO API key).
137
- credda career-export <userId>
138
- # the whole verified record as an open JSON Resume
139
- # document. Use --token <token> for the public route.
140
- credda mint <userId> # mint a share token
141
- credda revoke <userId> # revoke a share token
99
+ credda investigate <repo-path> <description | @file | -> [options]
142
100
  ```
143
101
 
144
- Confirmation requests — the counterparty-confirmation primitive. You propose an
145
- outcome and deliver the one-time token yourself; the event is written, verified,
146
- only when that distinct party confirms:
102
+ | Command | What it does |
103
+ | --- | --- |
104
+ | `investigate` | Reproduce a reported failure, diagnose it, and fix it where the provider allows |
105
+ | `triage` | Say what Credda could not use in a report, or say nothing |
106
+ | `discover` | Read a checkout and write the bug reports nobody filed. Starts nothing |
107
+ | `doctor` | Check that this environment can reproduce a bug |
108
+ | `reap` | Remove sandbox containers left behind by an interrupted run |
109
+ | `init` | Write a `credda.config.json` with documented defaults |
110
+ | `status` | List recent investigations, filtered by repository, state or outcome |
111
+ | `report` | Show what an investigation established, and what it did not |
112
+ | `inspect` | Show everything one run recorded, in full |
113
+ | `events` | Show the event timeline for an investigation |
114
+ | `cancel` | Stop a running investigation, or say why it cannot be stopped |
115
+ | `validations` | List change-scoped validation runs |
116
+ | `validation` | Show one validation: its checks, and the findings they raised |
117
+
118
+ Aliases, kept permanently because docs, scripts and the external benchmark
119
+ harness use them: **`fix`** and **`resolve`** are `investigate`; **`resolution`**
120
+ is `report`. They parse identically. Their `--help` prints what the command
121
+ actually produces, so an old name is never read as a promise about the output.
122
+
123
+ ### Flags
124
+
125
+ `investigate` (and its aliases):
126
+
127
+ | Flag | Value | Default |
128
+ | --- | --- | --- |
129
+ | `--sandbox` | `local` \| `native` \| `docker` | `local` |
130
+ | `--provider` | `auto` \| `heuristic` \| `openai-compatible` | `auto` |
131
+ | `--budget-minutes` | `<n>` wall-clock budget | `20` |
132
+ | `--max-turns` | `<n>` model calls across all agent roles | `120` |
133
+ | `--out` | `<file>` also write this run's machine-readable result as JSON | — |
134
+ | `--ref` | `<ref>` record where this report came from; stored on the run | — |
135
+
136
+ Other commands: `triage --repo <path>`; `discover --out <dir>` and
137
+ `--max-files <n>`; `report`/`resolution` `--markdown` and
138
+ `--patch`; `doctor --deep`; `reap --dry-run --max-age-hours <n>`;
139
+ `init --global --force`; `status --repository <path-or-id> --state <state>
140
+ --outcome <outcome> --ref <ref> --limit <n> --offset <n>`; `events --since <n>` and
141
+ `--follow` (`-f`); `cancel --reason <text>`; `validations --repository <path-or-id>
142
+ --state <state> --outcome <outcome> --limit <n> --offset <n>`; `validation
143
+ --severity <s> --status <s> --limit <n> --offset <n>`.
144
+
145
+ `report --patch` writes the unified diff the run recorded on stdout and nothing
146
+ else, and exits non-zero when the run recorded no patch, so a script cannot read
147
+ an empty document as an empty change. It only reads a finished run: it applies
148
+ nothing, delivers nothing, and whether that diff may be proposed to anyone is a
149
+ separate question answered by the delivery block that `credda investigate --out`
150
+ writes.
151
+
152
+ `discover` is the narrowest verb on this table and the one most likely to be
153
+ read as more than it is. It walks a checkout an operator names, reads its
154
+ JavaScript and TypeScript source, and writes ordinary bug reports about the
155
+ shapes it saw. It opens no store, creates no investigation and starts no run.
156
+ **It has confirmed nothing**: measured against 160 cases from 50 real
157
+ repositories, each at a commit where a defect is present and again at the
158
+ maintainer's fix, the rules emitted 103 candidates, none of them fell silent at
159
+ the fix, and on no case did a rule name the defect the case pins. A candidate is
160
+ a report worth a reproduction, never a defect Credda found — and zero candidates
161
+ is not a clean bill of health.
162
+
163
+ Global: `--help` (`-h`), `--version`, `--json`, `--quiet`, `--verbose`,
164
+ `--no-color`.
165
+
166
+ A description is given inline, as `@file`, or as `-` for stdin. `credda triage`
167
+ takes a file and never an inline string, because the body is text a stranger
168
+ typed and a file name does not go through a shell.
169
+
170
+ ### Exit codes
171
+
172
+ | Code | Meaning |
173
+ | --- | --- |
174
+ | 0 | The answer was reached and nothing failed. Abstention is a success: `NO_CHANGE_REQUIRED` and `INCONCLUSIVE` both exit 0. For `triage`, 0 means it correctly had nothing to say. |
175
+ | 1 | Internal error. Credda failed; no verdict. |
176
+ | 2 | Usage error. Nothing was run. |
177
+ | 3 | `PATCH_REJECTED`: Credda wrote a change and independent verification rejected it, so the change was discarded and the workspace restored. Nothing is on offer; the diagnosis still stands. Held open and unreused while ADR 0015 was in force, and returned again since ADR 0019 (2026-08-27), so the scripts written against the original table still read it correctly. |
178
+ | 4 | Cancelled by the operator. |
179
+ | 5 | `NO_RUNNABLE_CHECK`: nothing runnable could be derived from the report. A fact about the report, not about your code, kept separate from 0 so `credda … && deploy` cannot read it as a pass. |
180
+ | 6 | `COMMENT_READY`, from `triage` only: there is a comment and it is on stdout. |
181
+ | 7 | `CANCELLATION_REQUESTED`, from `cancel` only: a run is still executing and has been asked to stop. **It has not stopped.** It tears its sandbox down and writes its own terminal state at its next checkpoint; follow it with `credda events <id> --follow`. |
182
+
183
+ `credda cancel` exits 0 only when nothing is running, and 7 when a run was
184
+ merely asked to stop. They are two codes because they are two claims: 0 says the
185
+ machine is quiet, so `credda cancel $id && deploy` is safe, and 7 does not
186
+ satisfy it. 7 is also not 4 — 4 is a run reporting that it ended, 7 is a
187
+ different process reporting that it asked one to, without knowing whether it
188
+ did. A run this machine cannot reach exits 2 and **nothing is written to it**,
189
+ because marking it cancelled would be a state the still-running engine
190
+ overwrites minutes later, having spent the whole budget you thought you stopped.
191
+
192
+ Triage's silence is exit 0 and its comment is exit 6, that way round on purpose:
193
+ about half of real inbound issues produce nothing worth saying, and every way of
194
+ misreading the code then fails toward not posting. Do **not** write
195
+ `credda triage issue.md > c.md && post c.md` — it posts on the silent path and
196
+ stays quiet on the speaking one.
197
+
198
+ ### Environment
199
+
200
+ `CREDDA_HOME`, `CREDDA_PROVIDER`, `CREDDA_MODEL`, `CREDDA_SANDBOX`,
201
+ `CREDDA_LOG_LEVEL`, `NO_COLOR`, plus `ANTHROPIC_API_KEY`,
202
+ `CREDDA_OPENAI_API_KEY` (`NVIDIA_API_KEY` accepted as a second name),
203
+ `CREDDA_OPENAI_BASE_URL`, `CREDDA_OPENAI_MODEL` and `CREDDA_OPENAI_RPM`.
204
+ `credda --help` documents each. Configuration precedence, highest first: the
205
+ flag, the environment variable, `credda.config.json` searched upward from the
206
+ working directory then `$CREDDA_HOME/credda.config.json`, the built-in default.
207
+
208
+ ## What is in this repository
147
209
 
148
- ```sh
149
- credda confirmations create --user worker_7 --type CONTRACT_FULFILLED \
150
- --counterparty client_42 --counterparty-name "Acme Ltd" \
151
- --description "Kitchen refit" [--stake HIGH] [--value 1200] \
152
- [--due <iso>] [--completed <iso>] [--return-url <url>] \
153
- [--expires-in 14] [--idempotency-key <k>]
154
- # needs CREDDA_API_KEY. The token is shown ONCE;
155
- # creating a request writes no event.
156
- credda confirmations batch <file.json> [--idempotency-key <k>]
157
- # the ACTIVATION ENGINE — bulk-create up to 100
158
- # requests from a JSON file (an array of request
159
- # bodies, or { "requests": [...] }), warming a cold
160
- # ledger from your book. Needs CREDDA_API_KEY; each
161
- # ok item's token is shown ONCE.
162
- credda confirmations list [--status PENDING] [--cursor <c>] [--limit <n>]
163
- credda confirmations get <id>
164
- credda confirmations cancel <id> # only while PENDING
165
-
166
- # ⚠️ These two are the COUNTERPARTY's calls and take NO API key — they hold a
167
- # token, not a Credda account:
168
- credda confirmations preview <id> --token <t>
169
- credda confirmations respond <id> --token <t> --confirm
170
- credda confirmations respond <id> --token <t> --decline
171
- # --confirm writes the verified event; --decline
172
- # writes nothing. Single-use either way, and
173
- # there is no default: you must say which.
174
210
  ```
175
-
176
- Reference requests — the qualifications-half sibling of confirmations. A résumé
177
- claim (employment / education / certification / skill) becomes verified when the
178
- named third party who was there confirms it; a reference never moves the score:
179
-
180
- ```sh
181
- credda references create --user worker_7 --category employment \
182
- --counterparty manager_42 --label "Senior Engineer" \
183
- --issuer "Acme Ltd" [--jurisdiction US-CA] [--reference EMP-9910] \
184
- [--counterparty-name "Dana Lee"] [--description <d>] \
185
- [--return-url <url>] [--expires-in 14] [--idempotency-key <k>]
186
- # needs CREDDA_API_KEY. The token is shown ONCE;
187
- # creating a request records no qualification.
188
- credda references list [--status PENDING] [--cursor <c>] [--limit <n>]
189
- credda references get <id>
190
- credda references cancel <id> # only while PENDING
191
-
192
- # ⚠️ These two are the REFERENCE's calls and take NO API key — they hold a
193
- # token, not a Credda account:
194
- credda references preview <id> --token <t>
195
- credda references respond <id> --token <t> --confirm
196
- credda references respond <id> --token <t> --decline
197
- # --confirm records the verified qualification;
198
- # --decline writes nothing. Single-use either way,
199
- # and there is no default: you must say which.
211
+ src/args.ts copied verbatim from the engine's apps/cli/src/args.ts
212
+ src/commands.ts copied verbatim from the engine's apps/cli/src/commands.ts
213
+ src/index.ts this package's export surface (mirror-only, written here)
200
214
  ```
201
215
 
202
- Threshold policies — declarative "tell me when this line is crossed", delivered
203
- as `policy.threshold_crossed` through your webhooks. Config only: a policy never
204
- reads into, blocks, or changes a score:
216
+ Those two files are copied rather than summarised because they are
217
+ dependency-free in the engine by construction — the parser is hand-rolled and
218
+ the table is plain data — so a faithful copy is possible and CI can compare each
219
+ to its original by hash. **Do not hand-edit them**; change the engine and copy
220
+ across. Everything else in that CLI reaches into the engine, the database and
221
+ the sandbox, and is not mirrored.
205
222
 
206
- ```sh
207
- credda policies create --name "Watch 60" --user worker_7 \
208
- --metric score --direction down --threshold 60
209
- credda policies create --name "Anyone entering High Risk" --all \
210
- --metric band --direction enter --band "High Risk"
211
- credda policies list [--cursor <c>] [--limit <n>]
212
- credda policies get <id>
213
- credda policies update <id> [--threshold <n>] [--direction <d>] [--band <b>]
214
- [--component <c>] [--name <n>] [--activate | --deactivate]
215
- # the metric is immutable — delete and recreate
216
- credda policies delete <id>
217
- ```
218
-
219
- Score monitors — set `CREDDA_API_KEY`. Edge-triggered threshold/band watches
220
- that deliver `monitor.triggered` through your subscribed webhooks;
221
- notification config only — a monitor never affects a score:
223
+ So this package answers, offline, what `credda` accepts:
222
224
 
223
- ```sh
224
- credda monitors list [--cursor <c>] [--limit <n>]
225
- credda monitors get <id>
226
- credda monitors create --user <externalId> --below 40
227
- # at least one condition required:
228
- # --below <score> downward crossing (also fires
229
- # on a FIRST score already below)
230
- # --above <score> upward crossing
231
- # --band-change any band change
232
- credda monitors delete <id>
225
+ ```ts
226
+ import { COMMANDS, EXIT, rootUsage, parseArgs } from '@credda/cli';
233
227
  ```
234
228
 
235
- Bulk screenings — set `CREDDA_API_KEY`. Async batch score reads (up to
236
- 10,000 ids per job), strictly read-only:
229
+ [`examples/surface.mjs`](examples/surface.mjs) is that, worked through end to
230
+ end — reading the verbs, resolving an alias, parsing a command line, watching a
231
+ bad flag value be refused, and checking the exit-code contract a calling script
232
+ branches on. Run it:
237
233
 
238
234
  ```sh
239
- credda screen u1,u2 u3 # ids inline, comma/space separated
240
- credda screen --file roster.csv
241
- # one id per line, or a CSV whose FIRST column is
242
- # the id (a leading id/userId/externalId header
243
- # row is skipped; no quoted-CSV handling)
244
- credda screen u1,u2 --wait # poll until the job finishes, print the summary
245
- # (exit 1 if the job FAILED)
246
- credda screenings list [--cursor <c>] [--limit <n>]
247
- credda screenings get <id> # job status + summary
248
- credda screenings results <id> # per-user results as JSON
249
- credda screenings results <id> --csv out.csv
250
- # write the CSV attachment instead (raw fetch)
235
+ npm install && npm run build && npm run example
251
236
  ```
252
237
 
253
- Webhooks — set `CREDDA_API_KEY`:
238
+ It asserts with `node:assert/strict` and CI runs it on every push, so it exits
239
+ non-zero the moment any of that stops being true.
254
240
 
255
- ```sh
256
- credda webhooks list
257
- credda webhooks create https://hooks.you/credda score.updated score.band_changed
258
- # signing secret shown ONCE
259
- credda webhooks delete <id>
260
- credda webhooks test <id> # synthetic signed delivery
261
- credda webhooks deliveries <id> # recent attempts, incl. retries
262
- ```
241
+ It cannot run an investigation, and it does not pretend to. Canonical
242
+ development happens in the engine repository; this repo carries the source and
243
+ the issues.
263
244
 
264
- Local development:
245
+ ## Contributing
265
246
 
266
- ```sh
267
- CREDDA_WEBHOOK_SECRET=whsec_... credda listen 4141
268
- ```
269
-
270
- `credda listen` runs a local receiver that HMAC-verifies each delivery (the
271
- same check your production handler must do) and pretty-prints the payload.
272
- Credda delivers to public HTTPS only, so expose the port with your own tunnel
273
- (e.g. `cloudflared tunnel --url http://localhost:4141`) and register the
274
- tunnel URL as the webhook — the Stripe-CLI-style local loop without Credda
275
- running a tunneling service.
276
-
277
- Environment: `CREDDA_API_URL` overrides the API base (default
278
- `https://api.credda.io`); `CREDDA_WEBHOOK_SECRET` enables signature
279
- verification in `credda listen`.
280
-
281
- ## Design
282
-
283
- - `src/cli.ts` is the pure command router — no `process`, `fs`, or env access,
284
- so the whole surface is unit-tested with a mocked `CreddaClient` (same
285
- pattern as `packages/mcp`'s `tools.ts`).
286
- - `src/index.ts` only wires the real environment (env vars, stdin/file
287
- reading, exit codes).
288
- - `verify` uses the SDK's offline verifiers (WebCrypto Ed25519 + StatusList
289
- revocation) — the point is that a received credential can be checked
290
- without trusting the wire it arrived on.
291
- - Every command is read-only against the score. `mint`/`revoke` manage a
292
- share token — a capability, not a score write.
247
+ Issues here are read. Pull requests against `src/args.ts` and `src/commands.ts`
248
+ cannot be merged here — they would be overwritten by the next copy — so open an
249
+ issue describing the change to the surface instead.
293
250
 
294
251
  ## License
295
252
 
296
253
  MIT © Credda. See [LICENSE](LICENSE).
297
-
298
- ---
299
-
300
- Part of the Credda SDK family:
301
- [`@credda/js`](https://github.com/Credda-io/credda-js) ·
302
- [`credda-go`](https://github.com/Credda-io/credda-go) ·
303
- [`@credda/cli`](https://github.com/Credda-io/credda-cli) ·
304
- [`@credda/mcp-server`](https://github.com/Credda-io/credda-mcp)