@credda/cli 0.1.6 → 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 +219 -279
  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 -74
  9. package/package.json +18 -17
  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,313 +1,253 @@
1
1
  <p align="center">
2
2
  <a href="https://credda.io">
3
- <picture>
4
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Credda-io/credda-cli/main/assets/creddalockuplongdarktransparent.png">
5
- <img alt="Credda" src="https://raw.githubusercontent.com/Credda-io/credda-cli/main/assets/creddalockuplonglighttransparent.png" width="360">
6
- </picture>
3
+ <img alt="Credda" width="96" height="96"
4
+ src="https://raw.githubusercontent.com/Credda-io/credda-cli/main/assets/credda-mark-spectrum.png">
7
5
  </a>
8
6
  </p>
9
7
 
10
- > 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.
11
-
12
8
  # @credda/cli
13
9
 
14
- The official Credda CLI: portable trust from the terminal. A thin client over
15
- [`@credda/js`](https://www.npmjs.com/package/@credda/js)'s headless export;
16
- **no scoring logic lives here** (the deterministic score is computed only by
17
- the API's `score.service`).
18
-
19
- ## Install
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:
20
13
 
21
14
  ```sh
22
- npm install -g @credda/cli # or: pnpm add -g @credda/cli
23
- credda help
15
+ npm install -g credda # the CLI itself
16
+ credda --help
24
17
  ```
25
18
 
26
- Node 20 or newer. Nothing else to configure for the public commands below.
27
-
28
- Prefer not to install globally? `npx @credda/cli help` works the same way.
29
-
30
- `credda help` always lists exactly what the version you installed can do, so
31
- treat it, not this file, as the authority on your copy. `credda --version`
32
- prints that version.
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.
33
97
 
34
- ## Commands
35
-
36
- Start here, if you hold a sandbox key (`CREDDA_API_KEY` of the `crd_test_`
37
- kind; a live key is refused before anything happens):
38
-
39
- ```sh
40
- credda quickstart # seed the sandbox with synthetic subjects, print
41
- # their real scores, then close the counterparty-
42
- # confirmation loop so you finish holding a real
43
- # VERIFIED event rather than a number you read
44
- --no-confirm # stop after the seed; skip the confirmation loop
45
98
  ```
46
-
47
- Public (no API key):
48
-
49
- ```sh
50
- credda lookup <token> # trust check for a share token (GET /verify/:token)
51
- credda export <token> # full self-verifying trust export bundle
52
- credda verify <file|-> # OFFLINE-verify a credential someone handed you:
53
- # a W3C VC-JWT, a compact Trust Credential, or a
54
- # saved trust-export bundle (auto-detected).
55
- # '-' reads stdin. Exit 0 valid / 2 invalid.
56
- credda registry # federated trust registry (/.well-known)
57
- credda did # issuer DID document
58
- credda benchmarks # cohort-benchmark catalog: the dimensions you can
59
- # benchmark on and the k-anonymity floor below
60
- # which no cohort is disclosed
61
- credda reason-codes # adverse-action reason-code catalog (ECOA / Reg B).
62
- # Credda supplies the attribution only: it is not
63
- # a creditor and issues no notice.
64
- credda badges list # the closed set of Open Badges 3.0 achievements
65
- credda badges get <badgeId> # this issuer will sign, and one definition
66
- credda outcome-templates [industry]
67
- # how a business maps its work to Credda events, and
68
- # WHO confirms each outcome. Guidance only.
69
- credda professional-record public <token>
70
- # the professional record behind a share token
71
- # (the token IS the subject's consent to present it)
72
- credda career-export --token <token>
73
- # the whole verified record as a JSON Resume document,
74
- # behind a share token (no API key sent)
99
+ credda investigate <repo-path> <description | @file | -> [options]
75
100
  ```
76
101
 
77
- Platform (set `CREDDA_API_KEY`, a `crd_live_…` platform key):
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
78
209
 
79
- ```sh
80
- credda score <userId> # current score
81
- credda explain <userId> # factor-level explanation
82
- credda components <userId> # six named 0-100 components
83
- credda risk <userId> # advisory risk signals
84
- credda trust-summary <userId> [--narrative]
85
- # deterministic, evidence-based summary + strengths
86
- # + risks. It explains; it is never a verdict.
87
- # --narrative adds an advisory AI retelling.
88
- credda benchmark <userId> [--dimension <d>]
89
- # where the subject sits in its cohort: percentile
90
- # + the cohort distribution. `available:false`
91
- # when the cohort is below the k-anonymity floor
92
- # (insufficient_data) or the subject has no score
93
- # yet (no_score).
94
- credda distribution [--dimension <d>] [--cohort <c>]
95
- # aggregate, k-anonymised cohort distribution.
96
- # Omit --cohort for every cohort on the dimension.
97
- credda users [--score-min <n>] [--score-max <n>] [--band <b>]
98
- [--subject-type <PERSON|AGENT|ORGANIZATION>]
99
- [--scored|--unscored] [--frozen]
100
- [--active-since <iso>] [--registered-since <iso>]
101
- [--registered-before <iso>] [--verified] [--min-verified <n>]
102
- [--sort <score|lastActivity|registered|externalId>]
103
- [--order <asc|desc>] [--cursor <c>] [--limit <n>]
104
- # query + export your book of subjects. The filter
105
- # set is closed and validated: no query DSL.
106
- # A subject with no score yet reports null, never
107
- # a placeholder; list those with --unscored.
108
- credda book-summary [same filters as "users"]
109
- # size a segment WITHOUT paging it: how many match,
110
- # how many are scored, band mix, median/mean.
111
- # Null (not 0) when nothing in it is scored.
112
- credda usage [days] # your platform's metered usage (trailing window)
113
- credda usage --from 2026-06-01 --to 2026-06-30
114
- # explicit statement range (mutually exclusive
115
- # with [days])
116
- credda usage --csv usage.csv
117
- # write the flat CSV statement to a file
118
- # (raw ?format=csv fetch; combines with either window)
119
- credda activity [--action <A>] [--from <t>] [--to <t>] [--cursor <c>] [--limit <n>]
120
- # your platform's own activity/audit log,
121
- # newest-first, cursor-paginated
122
- credda verified-profile <userId>
123
- # how much of a subject's CLAIMED record
124
- # (education/skills/certifications/employment) is
125
- # third-party verified. Counts WHETHER a claim is
126
- # verified, never how prestigious it is, and can
127
- # never move the Reliability Score.
128
- credda qualify <userId> --category <education|skill|certification|employment>
129
- [--label <l>] [--issuer <i>] [--verified-by <witness>]
130
- # record a qualification claim. Always recorded;
131
- # counts as VERIFIED only with a genuine
132
- # third-party --verified-by witness.
133
- credda professional-record get <userId>
134
- # résumé-shaped summary of a VERIFIED work record.
135
- # Describes a record. Not a hiring verdict, a
136
- # background check, or a consumer report.
137
- credda professional-record credential <userId> [--ttl <seconds>]
138
- # mint the signed, offline-verifiable credential
139
- # (+ an "Add to LinkedIn" certification link)
140
- credda reliability-report <userId> [--recent <n>] [--benchmark]
141
- # the consolidated worker reliability report a
142
- # staffing agency or employer weighs. EVIDENCE, not
143
- # a hire / place / rank verdict or a consumer report.
144
- # Use --token <token> for the public worker-consent
145
- # route (NO API key).
146
- credda career-export <userId>
147
- # the whole verified record as an open JSON Resume
148
- # document. Use --token <token> for the public route.
149
- credda mint <userId> # mint a share token
150
- credda revoke <userId> # revoke a share token
151
210
  ```
152
-
153
- Confirmation requests: the counterparty-confirmation primitive. You propose an
154
- outcome and deliver the one-time token yourself; the event is written, verified,
155
- only when that distinct party confirms:
156
-
157
- ```sh
158
- credda confirmations create --user worker_7 --type CONTRACT_FULFILLED \
159
- --counterparty client_42 --counterparty-name "Acme Ltd" \
160
- --description "Kitchen refit" [--stake HIGH] [--value 1200] \
161
- [--due <iso>] [--completed <iso>] [--return-url <url>] \
162
- [--expires-in 14] [--idempotency-key <k>]
163
- # needs CREDDA_API_KEY. The token is shown ONCE;
164
- # creating a request writes no event.
165
- credda confirmations batch <file.json> [--idempotency-key <k>]
166
- # the ACTIVATION ENGINE: bulk-create up to 100
167
- # requests from a JSON file (an array of request
168
- # bodies, or { "requests": [...] }), warming a cold
169
- # ledger from your book. Needs CREDDA_API_KEY; each
170
- # ok item's token is shown ONCE.
171
- credda confirmations list [--status PENDING] [--cursor <c>] [--limit <n>]
172
- credda confirmations get <id>
173
- credda confirmations cancel <id> # only while PENDING
174
-
175
- # ⚠️ These two are the COUNTERPARTY's calls and take NO API key (they hold a
176
- # token, not a Credda account):
177
- credda confirmations preview <id> --token <t>
178
- credda confirmations respond <id> --token <t> --confirm
179
- credda confirmations respond <id> --token <t> --decline
180
- # --confirm writes the verified event; --decline
181
- # writes nothing. Single-use either way, and
182
- # 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)
183
214
  ```
184
215
 
185
- Reference requests: the qualifications-half sibling of confirmations. A résumé
186
- claim (employment / education / certification / skill) becomes verified when the
187
- named third party who was there confirms it; a reference never moves the 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.
188
222
 
189
- ```sh
190
- credda references create --user worker_7 --category employment \
191
- --counterparty manager_42 --label "Senior Engineer" \
192
- --issuer "Acme Ltd" [--jurisdiction US-CA] [--reference EMP-9910] \
193
- [--counterparty-name "Dana Lee"] [--description <d>] \
194
- [--return-url <url>] [--expires-in 14] [--idempotency-key <k>]
195
- # needs CREDDA_API_KEY. The token is shown ONCE;
196
- # creating a request records no qualification.
197
- credda references list [--status PENDING] [--cursor <c>] [--limit <n>]
198
- credda references get <id>
199
- credda references cancel <id> # only while PENDING
200
-
201
- # ⚠️ These two are the REFERENCE's calls and take NO API key (they hold a
202
- # token, not a Credda account):
203
- credda references preview <id> --token <t>
204
- credda references respond <id> --token <t> --confirm
205
- credda references respond <id> --token <t> --decline
206
- # --confirm records the verified qualification;
207
- # --decline writes nothing. Single-use either way,
208
- # and there is no default: you must say which.
209
- ```
210
-
211
- Threshold policies: declarative "tell me when this line is crossed", delivered
212
- as `policy.threshold_crossed` through your webhooks. Config only: a policy never
213
- reads into, blocks, or changes a score:
223
+ So this package answers, offline, what `credda` accepts:
214
224
 
215
- ```sh
216
- credda policies create --name "Watch 60" --user worker_7 \
217
- --metric score --direction down --threshold 60
218
- credda policies create --name "Anyone entering At Risk" --all \
219
- --metric band --direction enter --band "At Risk"
220
- credda policies list [--cursor <c>] [--limit <n>]
221
- credda policies get <id>
222
- credda policies update <id> [--threshold <n>] [--direction <d>] [--band <b>]
223
- [--component <c>] [--name <n>] [--activate | --deactivate]
224
- # the metric is immutable: delete and recreate
225
- credda policies delete <id>
226
- ```
227
-
228
- Score monitors (set `CREDDA_API_KEY`). Edge-triggered threshold/band watches
229
- that deliver `monitor.triggered` through your subscribed webhooks;
230
- notification config only (a monitor never affects a score):
231
-
232
- ```sh
233
- credda monitors list [--cursor <c>] [--limit <n>]
234
- credda monitors get <id>
235
- credda monitors create --user <externalId> --below 40
236
- # at least one condition required:
237
- # --below <score> downward crossing (also fires
238
- # on a FIRST score already below)
239
- # --above <score> upward crossing
240
- # --band-change any band change
241
- credda monitors delete <id>
225
+ ```ts
226
+ import { COMMANDS, EXIT, rootUsage, parseArgs } from '@credda/cli';
242
227
  ```
243
228
 
244
- Bulk screenings (set `CREDDA_API_KEY`). Async batch score reads (up to
245
- 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:
246
233
 
247
234
  ```sh
248
- credda screen u1,u2 u3 # ids inline, comma/space separated
249
- credda screen --file roster.csv
250
- # one id per line, or a CSV whose FIRST column is
251
- # the id (a leading id/userId/externalId header
252
- # row is skipped; no quoted-CSV handling)
253
- credda screen u1,u2 --wait # poll until the job finishes, print the summary
254
- # (exit 1 if the job FAILED)
255
- credda screenings list [--cursor <c>] [--limit <n>]
256
- credda screenings get <id> # job status + summary
257
- credda screenings results <id> # per-user results as JSON
258
- credda screenings results <id> --csv out.csv
259
- # write the CSV attachment instead (raw fetch)
235
+ npm install && npm run build && npm run example
260
236
  ```
261
237
 
262
- 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.
263
240
 
264
- ```sh
265
- credda webhooks list
266
- credda webhooks create https://hooks.you/credda score.updated score.band_changed
267
- # signing secret shown ONCE
268
- credda webhooks delete <id>
269
- credda webhooks test <id> # synthetic signed delivery
270
- credda webhooks deliveries <id> # recent attempts, incl. retries
271
- ```
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.
272
244
 
273
- Local development:
245
+ ## Contributing
274
246
 
275
- ```sh
276
- CREDDA_WEBHOOK_SECRET=whsec_... credda listen 4141
277
- ```
278
-
279
- `credda listen` runs a local receiver that HMAC-verifies each delivery (the
280
- same check your production handler must do) and pretty-prints the payload.
281
- Credda delivers to public HTTPS only, so expose the port with your own tunnel
282
- (e.g. `cloudflared tunnel --url http://localhost:4141`) and register the
283
- tunnel URL as the webhook: the Stripe-CLI-style local loop without Credda
284
- running a tunneling service.
285
-
286
- Environment: `CREDDA_API_URL` overrides the API base (default
287
- `https://api.credda.io`); `CREDDA_WEBHOOK_SECRET` enables signature
288
- verification in `credda listen`.
289
-
290
- ## Design
291
-
292
- - `src/cli.ts` is the pure command router: no `process`, `fs`, or env access,
293
- so the whole surface is unit-tested with a mocked `CreddaClient` (same
294
- pattern as `packages/mcp`'s `tools.ts`).
295
- - `src/index.ts` only wires the real environment (env vars, stdin/file
296
- reading, exit codes).
297
- - `verify` uses the SDK's offline verifiers (WebCrypto Ed25519 + StatusList
298
- revocation). The point is that a received credential can be checked
299
- without trusting the wire it arrived on.
300
- - Every command is read-only against the score. `mint`/`revoke` manage a
301
- 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.
302
250
 
303
251
  ## License
304
252
 
305
253
  MIT © Credda. See [LICENSE](LICENSE).
306
-
307
- ---
308
-
309
- Part of the Credda SDK family:
310
- [`@credda/js`](https://github.com/Credda-io/credda-js) ·
311
- [`credda-go`](https://github.com/Credda-io/credda-go) ·
312
- [`@credda/cli`](https://github.com/Credda-io/credda-cli) ·
313
- [`@credda/mcp-server`](https://github.com/Credda-io/credda-mcp)