CLI commands

Run emendant <command> --help for the interface shipped with your installed version.

emendant scan

Run all four stages and report findings.

npx emendant scan [options]

Option	Effect
--json	Print stable machine-readable output.
--sarif	Print one SARIF 2.1.0 log for code-scanning tools.
--package <name>	Limit to one package; repeat for several packages.
--severity <list>	Comma-separated breaking, deprecation, and behaviour.
--adopted	Also report old call sites found after the release was adopted.
--package-manager <name>	npm, pnpm, yarn, uv, or poetry: which manager really installs this repository, where two managers’ lockfiles sit in one directory and nothing in the repository proves which is live.
--config <file>	Read a specific configuration file.
--cwd <dir>	Scan another directory.
--verbose	Print counts, source URLs, matcher kinds, provenance hops, and informational notes.
--no-color	Disable terminal colour. NO_COLOR is also respected.

--feed <dir> reads a feed directory instead, skipping the signed snapshot entirely, and is intended for feed development and diagnostics. --feed-snapshot <id> pins one exact published snapshot, and --offline makes no request at all.

emendant fix

Turn findings into patches, and prove each one before offering it:

npx emendant fix [options]

Patches are written to .emendant/patches/. Nothing in your working tree is modified, and Git history is never touched. Every patch is first applied in memory and the repository matched again, to prove the use it was written for is gone and that no new one appeared. It is then applied in a copy of your repository outside the working tree and moved to the release the patch describes. When the repository has checks to find, the copy is put through them. A patch that does not pass is not written.

Option	Effect
--dry-run	Print the candidate diffs, run no checks, and write nothing.
--no-verify	Write the patches without running this repository’s checks.
--allow-host-run	Run the found checks on this host, outside any sandbox.
--allow-registry-credential <name>	Pass one additional environment variable named by package-manager configuration when the release is fetched. Repeat for several names.
--keep-scratch	Leave the verification copies on disk and say where.
--model-provider <name>	codex, claude, openai, anthropic, or azure. Needed only by the changes no transform can rewrite. claude runs your signed-in Claude Code CLI; anthropic calls the API with ANTHROPIC_API_KEY.
--model-auth <kind>	local, api, or entra. claude defaults to local (your Claude subscription) and takes api only when you name it. azure reads the environment.
--model <name>	The model to use. For azure this is the deployment name, and it is required.
--model-endpoint <url>	The Azure resource, or a gateway speaking the same wire format for openai and anthropic.

scan’s --package, --severity, --adopted, --package-manager, --feed, --feed-snapshot, --offline, --config, --cwd, --json, --verbose, and --no-color all apply here too.

The checks are found, not configured

fix selects a typecheck and a test command from what the repository already has: a script its manifest declares, or a tool it installed. CI workflows are never read, and no command is invented. typecheckCommand and testCommand in emendant.json override what is found.

Those commands run behind the strongest boundary the machine has: a temporary home, a reduced environment, and, where the platform supports it, no network and writes confined to the copy. Reads are not confined, and credential files are hidden by name instead. Where the platform can do neither, a found command is not started until you allow it, here or with --allow-host-run.

The four grades

Every patch says what evidence it has, in the report and in the patch file itself.

Grade	What happened
test verified	The repository’s own tests passed against the patched copy, at the release the patch describes.
typechecked	Its typecheck passed there. No test command ran.
structurally checked	The edits were applied and the workspace matched again. Nothing compiled or ran the code.
unchecked	Even that could not be done.

A --dry-run preview, --no-verify, and a repository owning no checks all produce structurally checked. A withheld patch is either failed, meaning the baseline was green and the patched copy is red, which is a fact about the patch, or inconclusive, meaning the repository was already red, an install did not work, or a command timed out, which is a fact about the machine.

Patches a model wrote

Most patches are written on your machine by a transform, with no model and no network. A few changes have no mechanical rewrite, and fix can ask a model to write those. Only a provider you name is ever called: without --model-provider or a model entry in configuration, those findings are reported unfixed and nothing is sent anywhere. What is sent is the matched block, its surrounding lines, and the file’s import block, going from your machine to that provider and nowhere else. Every route out of fix says which of the two halves it is looking at, including the header inside the patch file. See Security and privacy.

emendant explain

Print the source and guidance behind a result:

npx emendant explain <change-id>
npx emendant explain <finding-id>

A finding ID adds the site and its provenance chain. Supported options are --cwd, --feed, --feed-snapshot, --offline, --config, --json, and --no-color.

emendant detect

Inspect the packages and versions found in manifests and lockfiles:

npx emendant detect --cwd .

Use --all to list transitive dependencies, --json for structured output, and --verbose for informational notes. Detection never produces findings, so it exits 0 when successful.

emendant prefilter

Show the files that survive the inexpensive source walk and candidate gate:

npx emendant prefilter --verbose

A candidate is not a finding. Comments and strings can make a file a candidate because no syntax tree has been checked yet. --all-packages searches every bundled feed entry and intentionally inflates the candidate set.

emendant match

Run structural matching without version placement:

npx emendant match

A match proves the code uses the changed API, regardless of what version is installed. Use scan for actionable repository findings. --all-packages and --feed are diagnostic options.

Exit codes

Code	Commands	Meaning
0	All	Completed; scan and fix found nothing.
1	scan, fix	Completed with findings.
2	All	Invalid input or a tool error prevented completion.

emendant feed update

Refresh the cached feed. This is the only command that makes a network request by default, and it is the explicit form of that decision:

npx emendant feed update

It fetches one whole signed snapshot from feed.emendant.com and verifies it against the trust root inside the installed package. It exits 2 if the refresh did not happen, and it rejects --offline, because a requested refresh is its entire job.

Every command that reads the feed also accepts --feed-snapshot <id> to pin one exact snapshot, and --offline to make no request at all.

emendant feed status

Print which feed a scan here would use, its source, and its age, without making a request:

npx emendant feed status

emendant feed contribute

Show what a failed patch says a release broke, and the identifier this machine’s contributions carry:

npx emendant feed contribute

When a patch fails its typecheck or tests against a new release, the errors say what that release broke that the feed did not describe. emendant fix writes that to .emendant/contribution.json and, where you answered yes at a terminal, sends it so the feed covers it next time. It holds the package, the two versions, the feed entries whose patches failed, which check went red, and the error codes with the names the new release’s own type declarations contain. No path, no line, no code and nothing naming your repository can be in it.

Flag	Effect
--send	Send the record this repository already holds, for a run that could not.
--enable	Send one whenever a patch fails, from now on.
--disable	Send nothing, from now on.

A machine that was never asked sends nothing, and --offline sends nothing in any mode. To have your records deleted, quote the identifier this command prints to privacy@emendant.com. The privacy notice states it in full.

emendant --version

Print the version of the installed tool. Quote it in a bug report or a security report:

npx emendant --version