Release decision (Go / Go with accepted risk / Hold) from a scan and .keryn/decisions.yml; exit 1 on Hold.
keryn decide [path]Options
Section titled “Options”Usage: keryn decide [path] [--from <result.json>] [options] keryn decide sign [path] [--from <result.json>] [options] keryn decide migrate [path] [--write] [--remove-legacy] [--from <result.json>] [options] keryn decide export [path] (--github <owner/repo> | --gitlab <project>) [--github-url <api>] [--gitlab-url <base>] [--dry-run] [--record] [--label <a,b>] [--from <result.json>] [options] The release decision of a change: Go, Go with accepted risk, or Hold. Keryn proposes it from the scan, the policy and the repository's own answers; a person signs it. It never says a release is good to ship, only what is open and what was accepted. .keryn/decisions.yml (keryn.dev/decisions/v1) holds one answer per finding, keyed on its fingerprint (or a rule/path selector): status not_affected | affected | fixed | under_investigation, a reason, who decided and when; an accepted risk is affected with accepted: true and an expiry. .keryn/scope.yml (keryn.dev/scope/v1) holds the scope, exclusions and the coverage you declare. A finding at or above --fail-on is answered by a live decision; otherwise, or when the decision expired, is under investigation or not accepted, it is a Hold that names the edge and the proof level. Coverage the scan could not read stays on the decision. Exit: Hold 1; Go and Go with accepted risk 0 (10 with --exit-warn when there are warnings or accepted risks); 2, 3, 4 as for scan. 'keryn scan' prints the same decision (and carries it in --json as "decision") when .keryn/decisions.yml or scope.yml exists. 'sign' records the person in git config user.email (shown; no one can sign as another name) in .keryn/releases.jsonl, each record chained to the last by hash. It refuses when CI is set and refuses a Hold. policy.yml 'release: {require_signature: true}' makes an unsigned Go a Hold. With 'release: {signers: [...]}' a record counts only by a listed key's signature (keryn decide key). 'migrate' reads suppress: (.keryn.yml) and waivers: (the policy), scans without suppress: to find the fingerprints they covered, and prints the decisions it would add; --write creates or extends .keryn/decisions.yml and leaves the old entries; --remove-legacy then removes the entries decisions.yml already covers (with --write; without it, a preview). Entries nobody owned get decided_by: unknown. 'export' opens one issue per chain or chokepoint of the trust model for the open Holds (findings on no chain: one per rule and directory), listing the findings, the edge, the proof level, the coverage and the decision status. --dry-run prints the payloads as JSON and needs no token and no network. A real run reads GITHUB_TOKEN or GITLAB_TOKEN from the environment (there is no flag for it), searches the tracker for each issue's 'keryn:issue <digest>' marker first and creates nothing that exists or that a decision already tickets (ticket: in decisions.yml). The created URL becomes 'ticket' on the member decisions; --record also adds under_investigation entries for findings without one, with decided_by from git config user.email (shown). No labels unless --label. --github-url (GitHub Enterprise API) and --gitlab-url (self-managed) must be https, or http on localhost. Closing an issue never changes a decision. This is the one decide command that uses the network, and only for the tracker you name. For per-finding alerts, upload SARIF to code scanning instead (--sarif); issues are for chains.
Inputs --rules <a.yml,bundled:aibom> rule files or bundled packs: aibom, vuln, audit, inventory, all, risk (default: bundled:all for scan, bundled:aibom for bom/diff) --policy <file> policy-as-code YAML --config <file> | --no-config .keryn.yml (default: ./.keryn.yml if present) --base <git ref | bom.json | result.json> baseline for diff --include/--exclude <glob,...> path globs relative to the scan root (ts/fixtures/** is that one folder; **/fixtures/** any depth) --repo-root <dir> (scan, bundle) the repository the scanned folder belongs to: report paths, rule paths:, code roles, --include/--exclude and .keryn.yml (default <dir>/.keryn.yml) see repository-relative paths, as a scan of the whole repository would; fingerprints stay relative to the folder, so earlier baselines still match --max-file-size <bytes> --max-files <n> --max-total-size <bytes> --timeout <seconds> (lockfiles past --max-file-size are still read for dependencies, up to 64 MiB) --symlinks skip|follow-confined|error (default: skip) --subject <name> --revision <id> --timestamp <iso|now> --observed-browser <snapshot.json> a page snapshot (extension download): its AI technologies join the BOM, basis observed-in-browser --observed-network <observed-ports.json> network observations: classified AI services join the BOM (observed-on-network), their findings gate --summary-by owasp_llm|owasp_agentic|cwe|nist_ai_rmf|atlas group findings by a framework taxonomy in the console and markdown summary (reference only; not a compliance assessment) --offline (source scan/import: accepted and a no-op; these commands do not use the network)
Outputs ("-" writes to stdout; several per run) --aibom <f> CycloneDX 1.6 --sarif <f> SARIF 2.1.0 --sbom <f> dependency SBOM: every locked package, licence, graph (--sbom-format cyclonedx|spdx: CycloneDX 1.6, SPDX 2.3) --junit <f> JUnit XML --gitlab-sast <f> GitLab SAST report --codequality <f> Code Quality --json <f> Keryn result JSON --markdown <f> PR/MR summary --annotations github|azure|gitlab|teamcity -q, --quiet --verbose list findings with proof rung and flow
Gate --fail-on error|warning|info|none (default error) --fail-on-unsupported exit 3 on unsupported/partial/timed-out rules (now the default; kept for scripts) --allow-incomplete do not exit 3 when rules were unsupported/partial/timed out (default: exit 3) --dependencies <file> (scan) a resolved dependency list your build produced, read like a lockfile; repeatable. dependency-tree.json or dependency-tree.txt (mvn dependency:tree), or a CycloneDX / SPDX JSON SBOM named bom.json, sbom.json, *.cdx.json or *.spdx.json. It supersedes the pom.xml or Gradle build of its project. Keryn does not run Maven or Gradle --advisory-max-age <days> (scan) the installed offline advisory snapshot (keryn sca db update) may be this old; an older one still checks the dependencies but the run is incomplete (exit 3). Without --online an installed snapshot is used with no flag --require-advisories exit 3 when lockfiles were not checked against advisories (offline); the verdict always says so --gate-confidence P1|P2 lowest rule confidence that counts toward --fail-on (default P1; P2 widens) --secrets-config <file> (scan, ci) gitleaks TOML with your own secret rules ([extend] useDefault = true keeps the 222 defaults); default: .gitleaks.toml at the scanned root when present. A .gitleaksignore at the root is read. keryn rules lint <file.toml> checks one without scanning --secrets-history (scan, ci) also scan the added lines of every commit reachable from HEAD for secrets; --secrets-since <ref|date>, --secrets-max-commits N --no-deep (scan, bundle) skip the Deep pass: pattern rules only (default: Deep runs after them, fed with their facts) --deep-timeout <seconds> (scan, bundle) Deep's time limit (default 300; KERYN_DEEP_TIMEOUT_MS sets it in milliseconds). A Deep run stopped by it leaves the pattern findings and makes the scan incomplete (exit 3 in keryn ci) --engine deep|forge (scan) the interprocedural engine of the Deep pass: deep (default) or forge, the fact-bundle solver with KSQL rules (Python and TypeScript today); side by side while Forge proves itself --vex <local-file> repeatable OpenVEX, CSAF 2.0 VEX or CycloneDX VEX; attributed producer assertions, exact advisory and purl match --vex-product <purl|url> root context for VEX subcomponents; claims for other containers never apply globally --online (scan, bundle, artifact analyze) check locked dependencies (artifact: crates and npm packages read from the file) against OSV.dev advisories, and (scan) look up on deps.dev the licences lockfiles do not record: sends package names and versions only, never code or paths (default: offline; the report says which lockfiles were not checked). Reads deno.lock, and Deno code without one as declared, not locked; JSR, deno.land/x and URL modules are never sent --no-cache (scan, bundle) neither read nor write the rescan cache (KERYN_NO_CACHE=1 does the same); 'keryn cache clear' empties it --no-ignore scan files that .gitignore / .git/info/exclude exclude too (default: they are skipped and counted in the coverage line); Keryn's own earlier outputs are never scanned --new-only gate new findings against a paired Git --base; incomplete comparison fails --fail-on-added (diff) exit 1 when components were added --exit-warn exit 10 for pass-with-warnings
Exit codes: 0 pass | 1 violations | 2 usage/config | 3 coverage | 4 internal/timeout | 10 warningsExamples
Section titled “Examples”# Go, Go with accepted risk, or Hold.keryn decide .
# Decide from a saved scan.keryn decide . --from result.json --fail-on warningExit codes
Section titled “Exit codes”| Code | Meaning |
|---|---|
| 0 | Go, or Go with accepted risk |
| 1 | Hold: a finding at or above –fail-on has no live decision |
| 2 | usage or configuration error |
| 3 | coverage incomplete |
| 4 | internal error or timeout |
| 10 | Go with warnings or accepted risks (only with –exit-warn) |