@ingotai/scan — CLI for the Ingot model scanner

Scan Hugging Face models for the failure modes that cause business problems. Ingot runs three batteries — the static battery (metadata & packaging: serialization risk, license/template/tokenizer drift vs. the claimed parent), the weights battery (forensics on the safetensors: glitch-token surface, lineage verification), and the behavioral battery (GPU live-inference confirmation of glitch-token corruption; more probes rolling out). Gate CI on the combined verdict. It also runs deployment release gates — static checks of a declared deployment configuration (below).

npx @ingotai/scan scan Qwen/Qwen3.8-27B --fail-on warn

Setup

npx @ingotai/scan login

This prints a link — open it (Enter opens your browser; on a headless box, open it from any device), click Authorize, and the CLI saves an API key to ~/.config/ingot/config.json. Running scan without a key starts the same flow automatically on an interactive terminal.

For CI, create a key at the Ingot dashboard and export it: export INGOT_API_KEY=ingot_… (an explicit key always wins over the saved login).

Commands

ingot login                  # authorize this machine in your browser
ingot logout                 # remove the saved key for this instance
ingot usage                  # plan + scans used in the last 24h (--json for CI)
ingot scan <owner/model>     # run a scan; exits 1 if the verdict hits --fail-on
ingot scan --dir <path>      # offline static checks on a local checkpoint dir
ingot report <owner/model>   # read the published analysis — no API key needed
ingot patch <owner/model>    # apply the metadata-level fixes locally — no API key needed
ingot check all --manifest <file>   # deployment release gates — no API key needed

(npx @ingotai/scan … runs the same ingot binary without installing.)

Options: --fail-on fail|warn (default fail), --json, --timeout <min>, --dir <path>, --manifest <file>, --key <ingot_…>, --api-url <url> (or INGOT_URL).

Deployment release gates (beta)

ingot check validates a declared deployment configuration against failure modes measured in Ingot's research: duplicate side effects from stream-interrupt + retry (stream-conservation), reasoning exposure / token-budget truncation / transport-contract divergence (api-integrity), and tool schemas that break a runtime's grammar converter (tool-schema-compat).

Write one canonical manifest (schema) and run every applicable gate from it:

ingot check all --manifest .ingot/deployment.json
ingot check api-integrity --manifest .ingot/deployment.json --json

# persist the run (needs an API key): creates/updates the deployment, records
# durable evidence pinned to the manifest revision, applies active waivers
INGOT_API_KEY=ingot_… ingot check all --manifest .ingot/deployment.json --save

Saved runs appear on your dashboard with run-to-run diffs. Risk acceptance on saved deployments goes through waivers (explicit records with reason, actor, and manifest revision — created from the deployment page or POST /api/v1/deployments/:id/waivers); the manifest's acceptedRisks booleans are ignored for durable runs, and a waived finding keeps its gate at warn, never pass. In GitHub Actions, pass manifest: to the Ember-Sovereignty/ingot/ci@v1 action to run the same gates and upload the evidence JSON as a workflow artifact.

Scope: these are static checks of what the manifest declares — the CLI never calls your endpoint, so they can't prove the runtime honors the declaration. Runtime-specific findings (e.g. the llama.cpp grammar-converter failure) only fail when the manifest declares that runtime; otherwise they warn, scoped to the runtime the evidence covers. Gates that don't apply are reported as coverage gaps, not passes. Never put endpoint credentials in a manifest — validation rejects them. Exit codes match ingot scan: 0 pass, 1 gate hit, 2 invalid input or network error.

Fixing what the scan finds

Findings like a dropped or drifted chat template are metadata-level — ingot patch fetches the model's patch manifest (the file operations addressing its patchable findings, tied to the exact upstream revision and scan) and applies it to a local copy. Weights never move:

ingot patch some-org/drifted-model      # writes ./drifted-model-ingot-patched/
ingot scan --dir drifted-model-ingot-patched   # verify: "ingot patch: intact"

The output lists what was fixed and — just as important — what was not: weight-level findings (glitch tokens, behavioral properties) aren't patchable; for those the scan points at the runtime guard artifact (/api/v1/guard/<owner>/<model>, consumable via the @ingotai/guard package). Patches address the documented findings only — not a safety certification.

Gate on --fail-on warn: the bar for a fail verdict is deliberately high (damaging behavior confirmed on that exact checkpoint by the behavioral battery), so warn — template/tokenizer drift, pickle-only weights, remote-code — is where the real-world signal lives.

Exit codes: 0 clean, 1 verdict gate hit, 2 error — so ingot scan drops straight into any CI system:

ingot scan my-org/my-finetune --fail-on warn || exit 1

GitHub Actions users: prefer the ready-made action, Ember-Sovereignty/ingot/ci@v1.

The public database

Scans of public Hugging Face models publish their analysis to the model's free page at ingot.tools/models/<owner>/<model> — every scan grows the shared database. ingot report reads it without an API key.