credda

Hand it a bug report. It reproduces the failure, diagnoses the cause, writes the patch, and proves it with a test that fails before the fix and passes after. What comes back is a diff carrying its own evidence. Credda proposes and never merges: no path in this CLI, and no method on the engine's forge contract, asks a forge to merge anything, and a test in this repository fails if one appears.

This is apps/cli, the command-line entry point to the engine. It runs the engine in process against a local store on a checkout you name — it is not an HTTP client and it talks to no Credda service.

Status, plainly

This package is not on npm. npm view credda returned E404 on 2026-08-30, as it did when the name was checked on 2026-08-27. Publishing is a decision a human has not yet taken, and it is gated on an NPM_TOKEN secret that the release workflow reads: with no token, nothing here publishes. Until then the CLI is built and run from this repository, or installed from a tarball:

node scripts/bundle.mjs   # writes dist/credda.mjs
npm pack                  # a tarball that installs on a machine with only Node 24

How far a run goes is decided by the configured provider, never by a flag. Against a model-backed provider, investigate prepares an environment, reproduces the failure, captures its signature as evidence, diagnoses a cause where the evidence supports one, writes a patch and verifies it. Against the deterministic heuristic provider it reaches diagnosis and stops. It then reports the stages it did not enter as not attempted — never as a measured zero. A heuristic patch is worse than none, which is why there is no flag that turns the fix stage on.

Requires Node 24 (node:sqlite).

The verbs

credda investigate <repo-path> <description | @file | -> [options]

| Command | What it does | | --- | --- | | investigate | Reproduce a reported failure, diagnose it, and fix it where the provider allows | | triage | Say what Credda could not use in a report, or say nothing | | discover | Read a checkout and write the bug reports nobody filed. Starts nothing | | doctor | Check that this environment can reproduce a bug | | reap | Remove sandbox containers left behind by an interrupted run | | init | Write a credda.config.json with documented defaults | | status | List recent investigations | | report | Show what an investigation established, and what it did not | | inspect | Show everything one run recorded, in full | | events | Show the event timeline for an investigation | | cancel | Stop a running investigation, or say why it cannot be stopped | | validations | List change-scoped validation runs | | validation | Show one validation: its checks, and the findings they raised |

fix and resolve are permanent aliases for investigate; resolution is an alias for report. They parse identically, and each one's --help prints what the command actually produces, so an old name is never read as a promise about the output.

credda --help and credda <command> --help are generated from src/commands.ts, which is the authority on the copy you have. Every flag in that table is read by the implementation.

What discover is, and what it is not

credda discover <repo-path> walks a checkout you name, reads its JavaScript and TypeScript source, runs both rule sets over it, and writes ordinary bug reports about the shapes it saw. It opens no store, creates no investigation and starts no run; turning a candidate into a run is a second command you type.

It has confirmed nothing. Measured against 160 cases from 50 real repositories — each at a commit where a defect is present and again at the maintainer's fix — the rules emitted 103 candidates, none of them fell silent at the fix, and on no case did a rule name the defect the case pins (ADR 0024, amendment). Read a candidate as a report worth a reproduction, never as a defect this found. Zero candidates is not a clean bill of health either: the output says how many classes were looked for and whether the walk stopped short, because "we did not see it" and "it cannot happen" are different claims.

A run you can actually do

doctor executes nothing in your repository and reaches no network without --deep. It is the honest first command:

credda doctor ./my-app

It reports pass / warn / fail for the Node version, git, the active provider, the selected sandbox and CREDDA_HOME, and — given a repository — the package manager, the exact install command a run would use, and the test, build and typecheck commands it would find. That is a plan read off the repository, not a run of it.

Exit codes

| Code | Meaning | | --- | --- | | 0 | The answer was reached and nothing failed. Abstention is a success: NO_CHANGE_REQUIRED and INCONCLUSIVE both exit 0. | | 1 | Internal error. Credda failed; no verdict. | | 2 | Usage error. Nothing was run. | | 3 | PATCH_REJECTED: a change was written and independent verification rejected it, so it was discarded and the workspace restored. The diagnosis still stands. | | 4 | Cancelled by the operator. | | 5 | NO_RUNNABLE_CHECK: nothing runnable could be derived from the report. A fact about the report, not about your code. | | 6 | COMMENT_READY, from triage only: there is a comment and it is on stdout. | | 7 | CANCELLATION_REQUESTED, from cancel only: a run was asked to stop and has not stopped. Follow it with credda events <id> --follow. |

Triage's silence is 0 and its comment is 6, that way round on purpose: about half of real inbound issues produce nothing worth saying, so every way of misreading the code fails toward not posting. Do not write credda triage issue.md > c.md && post c.md — it posts on the silent path and stays quiet on the speaking one.

Configuration

CREDDA_HOME, CREDDA_PROVIDER, CREDDA_MODEL, CREDDA_SANDBOX, CREDDA_LOG_LEVEL, NO_COLOR, plus ANTHROPIC_API_KEY, CREDDA_OPENAI_API_KEY (NVIDIA_API_KEY accepted as a second name), CREDDA_OPENAI_BASE_URL, CREDDA_OPENAI_MODEL and CREDDA_OPENAI_RPM.

Precedence, highest first: the flag, the environment variable, credda.config.json searched upward from the working directory then $CREDDA_HOME/credda.config.json, the built-in default.

The mirrored surface

src/args.ts and src/commands.ts are copied byte-for-byte into the public @credda/cli package, whose CI compares each to its original by hash. commands.ts may import nothing but ./args.js: that package depends on nothing, so any other import compiles here and breaks it there. Edit either file and mirror it in the same round.

Tests

pnpm exec vitest run apps/cli

The suite covers the parser, the command table, the exit-code contract, and the delivery path against a real engine-produced patch on a real git checkout — including that no path asks a forge to merge.