{
  "schema": "keryn.dev/cli-reference/v1",
  "version": "0.5.2",
  "environment": [
    {
      "name": "KERYN_REVIEW_TOKEN",
      "description": "Read-only GitHub review token for trusted pull-request approval checks when a release signature is required. Never put it in candidate code.",
      "default": "GITHUB_TOKEN when available; otherwise host approval cannot be established"
    },
    {
      "name": "KERYN_ENFORCED_BASE",
      "description": "Trusted CI fallback commit SHA for PR policy enforcement when provider base metadata is unavailable; fetch this commit before scanning. Set in the trusted job, never from candidate content.",
      "default": "provider pull-request base metadata or the fetched target branch"
    },
    {
      "name": "KERYN_PR_AUTHOR",
      "description": "Trusted CI identity of the pull-request author, used to reject self-approval. Set only from trusted job metadata.",
      "default": "GitHub pull_request.user.login when available; otherwise unset"
    },
    {
      "name": "KERYN_DEBUG",
      "description": "Print the stack of an internal error.",
      "default": "unset"
    },
    {
      "name": "KERYN_CONFIG_DIR",
      "description": "Where keryn login keeps the device key, the device token, the cached entitlement and an offline licence (each file mode 0600).",
      "default": "$XDG_CONFIG_HOME/keryn, else ~/.config/keryn (Windows: %APPDATA%\\keryn)"
    },
    {
      "name": "KERYN_SERVER",
      "description": "The Keryn service keryn login signs in to.",
      "default": "https://api.keryn.app"
    },
    {
      "name": "KERYN_TOKEN",
      "description": "Non-interactive sign-in for CI: a service-account token an organization administrator issued in Account > Developers. Used instead of a stored keryn login (an offline licence still comes first); never written to disk or printed. Store it as a CI secret.",
      "default": "unset"
    },
    {
      "name": "KERYN_LICENCE_FILE",
      "description": "An offline licence file to use instead of the installed one.",
      "default": "licence.kl in the config directory"
    },
    {
      "name": "KERYN_MACHINE_ID",
      "description": "Development builds only: a stand-in machine identity for tests. Release builds ignore it and read the operating system (Linux /etc/machine-id, macOS IOPlatformUUID, Windows MachineGuid); only a hash is used.",
      "default": "unset"
    },
    {
      "name": "KERYN_ENTITLEMENT_DEV_KEYS",
      "description": "Development builds only: extra entitlement verifying keys (JSON). Release builds ignore it.",
      "default": "unset"
    },
    {
      "name": "KERYN_NO_CACHE",
      "description": "Set to 1 to skip the rescan cache for the run (same as --no-cache).",
      "default": "unset"
    },
    {
      "name": "KERYN_OWNERSHIP_DIR",
      "description": "Trusted local ownership issuer state directory; contains a private signing key, not project input.",
      "default": "$XDG_STATE_HOME/keryn/ownership, else ~/.local/state/keryn/ownership"
    },
    {
      "name": "KERYN_CACHE_DIR",
      "description": "Where the rescan cache lives.",
      "default": "the platform cache directory (see keryn cache path)"
    },
    {
      "name": "KERYN_CACHE_MAX_MB",
      "description": "Size cap of the rescan cache; least recently used files are deleted past it.",
      "default": "512"
    },
    {
      "name": "KERYN_DEEP_TIMEOUT_MS",
      "description": "Time limit of cross-file analysis, in milliseconds (--deep-timeout sets seconds).",
      "default": "300000"
    },
    {
      "name": "SOURCE_DATE_EPOCH",
      "description": "Unix seconds used as the timestamp when --timestamp is not given, for reproducible output.",
      "default": "a fixed 1970 timestamp"
    },
    {
      "name": "KERYN_NATIVE",
      "description": "Path to the keryn-native binary that runs the Workbench commands. An empty value disables it.",
      "default": "searched on PATH and next to keryn"
    },
    {
      "name": "KERYN_MCP_GUARD",
      "description": "Path to the keryn-mcp-guard binary used by keryn mcp guard.",
      "default": "searched on PATH and next to keryn"
    },
    {
      "name": "KERYN_DOCS_PACK",
      "description": "Directory of another offline docs pack in the same format, read by keryn docs.",
      "default": "the pack inside this CLI"
    },
    {
      "name": "KERYN_RUNTIME_PACK",
      "description": "Directory of another unpacked Keryn Runtime release, used by keryn runtime in place of the agent inside this CLI.",
      "default": "the agent inside this CLI"
    },
    {
      "name": "KERYN_NDAY",
      "description": "Set to 0 to turn known-fix matching off in keryn scan.",
      "default": "on (enabled)"
    },
    {
      "name": "KERYN_REGISTRY_USERNAME",
      "description": "With keryn sca image --pull: the user name for the registry. Sent with KERYN_REGISTRY_PASSWORD to the token endpoint the registry advertises, or to the registry on a Basic challenge. Never written to an output.",
      "default": "none: an anonymous pull"
    },
    {
      "name": "KERYN_REGISTRY_PASSWORD",
      "description": "With keryn sca image --pull: the password or access token that goes with KERYN_REGISTRY_USERNAME. Never written to an output.",
      "default": "none"
    },
    {
      "name": "KERYN_REGISTRY_TOKEN",
      "description": "With keryn sca image --pull: a bearer token for the registry, used as is (for example one from a cloud provider's own login command). Never written to an output.",
      "default": "none"
    },
    {
      "name": "KERYN_SCA_DB",
      "description": "Directory of the offline advisory snapshot that keryn sca db update installs and keryn scan and keryn sca image read. The value off makes scans ignore an installed snapshot.",
      "default": "the user data directory: <data dir>/keryn/sca-db"
    },
    {
      "name": "KERYN_NDAY_DB",
      "description": "Directory with the known-fix database (manifest.json and signatures.v1.jsonl).",
      "default": "the database the known-fix updater (keryn-native) installed, else the one packaged with the build"
    },
    {
      "name": "KERYN_NDAY_ALLOW_UNSIGNED",
      "description": "Set to 1 to load an unsigned known-fix database in this CLI. Development only; a warning is printed.",
      "default": "unset (unsigned databases are refused)"
    },
    {
      "name": "KERYN_CORE_WASM",
      "description": "Path to keryn-wasm-core.wasm when running from a checkout.",
      "default": "the workspace build output"
    },
    {
      "name": "GITHUB_TOKEN",
      "description": "Token for keryn decide export --github. There is no flag for it.",
      "default": "unset"
    },
    {
      "name": "GITLAB_TOKEN",
      "description": "Token for keryn decide export --gitlab. There is no flag for it.",
      "default": "unset"
    },
    {
      "name": "CI",
      "description": "When set, keryn decide sign refuses: a person signs a release, never a pipeline.",
      "default": "unset"
    }
  ],
  "scanFlags": [
    {
      "name": "vex",
      "arg": "<local-file>",
      "description": "Consume OpenVEX, CSAF 2.0 VEX or CycloneDX VEX. Match advisory and exact product; preserve attribution. PR jobs use trusted base files. Applies to a fresh scan (scan, bom, diff, bundle, decide); refused with --from.",
      "default": "none",
      "repeatable": true
    },
    {
      "name": "vex-product",
      "arg": "<purl|url>",
      "description": "Root product context for subcomponent assertions in --vex documents.",
      "default": "none"
    },
    {
      "name": "rules",
      "arg": "<a.yml,bundled:aibom>",
      "description": "Rule files or bundled packs (aibom, vuln, audit, inventory, all, risk), comma separated.",
      "default": "bundled:all for scan; bundled:aibom for bom, diff and the other commands",
      "repeatable": true
    },
    {
      "name": "policy",
      "arg": "<file>",
      "description": "Policy-as-code YAML that decides which AI providers and components are allowed.",
      "default": "the policy in .keryn.yml, else none"
    },
    {
      "name": "config",
      "arg": "<file>",
      "description": "Configuration file to read.",
      "default": "./.keryn.yml when present"
    },
    {
      "name": "no-config",
      "description": "Ignore .keryn.yml and use built-in defaults.",
      "default": "off"
    },
    {
      "name": "base",
      "arg": "<git-ref|bom.json|result.json>",
      "description": "Baseline to compare against: a git ref, a saved AI-BOM or a saved result.",
      "default": "none"
    },
    {
      "name": "include",
      "arg": "<glob,...>",
      "description": "Only scan paths matching these globs, relative to the scan root. `ts/fixtures/**` is that one folder; `**/fixtures/**` matches at any depth.",
      "default": "everything",
      "repeatable": true
    },
    {
      "name": "exclude",
      "arg": "<glob,...>",
      "description": "Skip paths matching these globs.",
      "default": "none",
      "repeatable": true
    },
    {
      "name": "max-file-size",
      "arg": "<bytes>",
      "description": "Largest file read; larger files are listed as skipped and counted in coverage. Lockfiles past it are still read for the dependency stage, up to 64 MiB, and never by the pattern or secrets pass.",
      "default": "the built-in limit"
    },
    {
      "name": "max-files",
      "arg": "<n>",
      "description": "Most files read.",
      "default": "the built-in limit"
    },
    {
      "name": "max-total-size",
      "arg": "<bytes>",
      "description": "Most bytes read in total.",
      "default": "the built-in limit"
    },
    {
      "name": "timeout",
      "arg": "<seconds>",
      "description": "Time limit of the scan. Reaching it leaves coverage incomplete (exit 3).",
      "default": "the timeout in .keryn.yml, else the built-in limit"
    },
    {
      "name": "offline",
      "description": "Accepted and a no-op: these commands never use the network unless --online is given.",
      "default": "off"
    },
    {
      "name": "symlinks",
      "arg": "skip|follow-confined|error",
      "description": "What to do with symbolic links: skip them, follow them inside the scan root, or fail.",
      "default": "skip"
    },
    {
      "name": "aibom",
      "arg": "<file>",
      "description": "Write the CycloneDX 1.6 AI bill of materials. `-` is stdout.",
      "default": "none"
    },
    {
      "name": "sbom",
      "arg": "<file>",
      "description": "Write the dependency SBOM: every package the lockfiles lock, with purl, licence and dependency graph (the AI-BOM lists AI components only). `-` is stdout.",
      "default": "none"
    },
    {
      "name": "sbom-format",
      "arg": "cyclonedx|spdx",
      "description": "Format of --sbom: CycloneDX 1.6 JSON or SPDX 2.3 JSON.",
      "default": "cyclonedx"
    },
    {
      "name": "sarif",
      "arg": "<file>",
      "description": "Write SARIF 2.1.0. `-` is stdout.",
      "default": "none"
    },
    {
      "name": "junit",
      "arg": "<file>",
      "description": "Write a JUnit XML report. `-` is stdout.",
      "default": "none"
    },
    {
      "name": "gitlab-sast",
      "arg": "<file>",
      "description": "Write a GitLab SAST report. `-` is stdout.",
      "default": "none"
    },
    {
      "name": "codequality",
      "arg": "<file>",
      "description": "Write a Code Quality report. `-` is stdout.",
      "default": "none"
    },
    {
      "name": "json",
      "arg": "<file>",
      "description": "Write the Keryn result JSON (keryn.dev/result/v1). `-` is stdout.",
      "default": "none"
    },
    {
      "name": "markdown",
      "arg": "<file>",
      "description": "Write a pull request or merge request summary. `-` is stdout.",
      "default": "none"
    },
    {
      "name": "annotations",
      "arg": "github|azure|gitlab|teamcity",
      "description": "Print findings as CI log annotations for that system.",
      "default": "none"
    },
    {
      "name": "fail-on",
      "arg": "error|warning|info|none",
      "description": "Lowest severity that makes the run exit 1.",
      "default": "error"
    },
    {
      "name": "fail-on-unsupported",
      "description": "Exit 3 on unsupported, partial or timed-out rules. This is already the default; the flag is kept for scripts.",
      "default": "on"
    },
    {
      "name": "allow-incomplete",
      "description": "Do not exit 3 when rules were unsupported, partial or timed out.",
      "default": "off"
    },
    {
      "name": "advisory-max-age",
      "arg": "<days>",
      "description": "How old the installed offline advisory snapshot may be. An older one still checks the dependencies, but the run is incomplete (exit 3) and coverage says how old it is.",
      "default": ".keryn.yml advisoryMaxAge, else no limit"
    },
    {
      "name": "require-advisories",
      "description": "Exit 3 when the tree has lockfiles whose packages were not matched against vulnerability advisories (an offline scan); pass --online to check them. Off by default: an offline scan says \"dependency advisories not checked (offline)\" in its verdict and exits as before.",
      "default": "off"
    },
    {
      "name": "gate-confidence",
      "arg": "P1|P2",
      "description": "Lowest rule confidence that counts toward --fail-on. P2 widens the gate.",
      "default": "P1"
    },
    {
      "name": "secrets-history",
      "description": "Also scan the added lines of every commit reachable from HEAD for secrets. A secret removed in a later commit is reported with the commit that introduced it, and must still be revoked. A shallow clone, the commit cap or a missing git make the secrets coverage incomplete.",
      "default": "off"
    },
    {
      "name": "secrets-since",
      "arg": "<ref|date>",
      "description": "With --secrets-history: only commits after this ref or date.",
      "default": "all reachable commits"
    },
    {
      "name": "dependencies",
      "arg": "<file>",
      "description": "A resolved dependency list your build produced, read like a lockfile: dependency-tree.json or dependency-tree.txt from mvn dependency:tree, or a CycloneDX or SPDX JSON SBOM named bom.json, sbom.json, *.cdx.json or *.spdx.json. It must be inside the scanned folder and supersedes the pom.xml or Gradle build of its project. A component whose purl cannot be read makes the dependency coverage incomplete. Keryn runs no build tool.",
      "default": "a dependency-tree.json or dependency-tree.txt found in the scanned tree; an SBOM is read only when named",
      "repeatable": true
    },
    {
      "name": "secrets-config",
      "arg": "<file>",
      "description": "A gitleaks TOML config with your own secret rules; [extend] useDefault = true keeps the 222 defaults. A file that cannot be used as a whole is a usage error (exit 2). A .gitleaksignore at the scanned root is always read.",
      "default": ".keryn.yml secrets.config, else .gitleaks.toml at the scanned root, else the defaults"
    },
    {
      "name": "secrets-max-commits",
      "arg": "<n>",
      "description": "With --secrets-history: read at most this many commits (newest first); more makes coverage incomplete.",
      "default": "10000"
    },
    {
      "name": "no-deep",
      "description": "Skip cross-file analysis (interprocedural) and run the pattern rules only.",
      "default": "off: cross-file analysis runs after the pattern rules"
    },
    {
      "name": "deep-timeout",
      "arg": "<seconds>",
      "description": "Time limit of cross-file analysis. A run stopped by it keeps the pattern findings and makes the scan incomplete.",
      "default": "300",
      "env": [
        "KERYN_DEEP_TIMEOUT_MS"
      ]
    },
    {
      "name": "engine",
      "arg": "deep|forge",
      "description": "Interprocedural engine of cross-file analysis. Forge is the fact-bundle solver with KSQL rules, side by side with deep while it proves itself.",
      "default": "deep"
    },
    {
      "name": "repo-root",
      "arg": "<dir>",
      "description": "The repository the scanned folder belongs to: report paths, rule `paths:`, code roles, include/exclude and .keryn.yml see repository-relative paths. Fingerprints stay relative to the folder.",
      "default": "the scanned folder"
    },
    {
      "name": "no-cache",
      "description": "Neither read nor write the rescan cache.",
      "default": "off",
      "env": [
        "KERYN_NO_CACHE"
      ]
    },
    {
      "name": "online",
      "description": "Check locked dependencies against OSV.dev, refresh the malicious-package (MAL) records for them, and look up on deps.dev the licences their lockfiles do not record. Sends package names and versions only, never code or paths. Without it the report says which lockfiles were not checked.",
      "default": "off"
    },
    {
      "name": "no-ignore",
      "description": "Also scan files .gitignore and .git/info/exclude exclude. Keryn's own earlier outputs are never scanned.",
      "default": "off: ignored files are skipped and counted in coverage"
    },
    {
      "name": "new-only",
      "description": "Gate only new findings against an explicit paired Git --base. Incomplete comparisons fail closed; this is not release approval. Requires a release after 0.5.2.",
      "default": "off"
    },
    {
      "name": "fail-on-added",
      "description": "Exit 1 when components were added relative to --base. Refused together with --new-only.",
      "default": "off"
    },
    {
      "name": "exit-warn",
      "description": "Exit 10 for a pass with warnings.",
      "default": "off"
    },
    {
      "name": "subject",
      "arg": "<name>",
      "description": "Name recorded as the subject of the AI-BOM.",
      "default": "the folder name"
    },
    {
      "name": "revision",
      "arg": "<id>",
      "description": "Revision recorded in the output. Default: the git commit of the scanned checkout, with -dirty when the scanned path has uncommitted or untracked changes; \"dir\" outside git.",
      "default": "git HEAD, else dir"
    },
    {
      "name": "timestamp",
      "arg": "<iso|now>",
      "description": "Timestamp written into outputs. The default keeps the same input giving the same bytes.",
      "default": "1970-01-01T00:00:00Z, or SOURCE_DATE_EPOCH when set",
      "env": [
        "SOURCE_DATE_EPOCH"
      ]
    },
    {
      "name": "observed-browser",
      "arg": "<snapshot.json>",
      "description": "A page snapshot (the extension's download): its AI technologies join the AI-BOM with basis observed-in-browser.",
      "default": "none"
    },
    {
      "name": "observed-network",
      "arg": "<observed-ports.json>",
      "description": "Network observations: classified AI services join the AI-BOM (observed-on-network) and their findings gate.",
      "default": "none"
    },
    {
      "name": "summary-by",
      "arg": "owasp_llm|owasp_agentic|cwe|nist_ai_rmf|atlas",
      "description": "Group findings by a framework in the console and markdown summary. Reference only; not a compliance assessment.",
      "default": "ungrouped"
    },
    {
      "name": "verbose",
      "description": "List the gating findings with their proof rung and flow.",
      "default": "off"
    },
    {
      "name": "quiet",
      "short": "q",
      "description": "Print nothing on success.",
      "default": "off"
    }
  ],
  "commands": [
    {
      "path": "scan",
      "summary": "inventory + rules -> AI-BOM, findings, policy",
      "usage": "keryn scan [path] [options]",
      "args": [
        {
          "name": "path",
          "description": "Folder or file to scan.",
          "required": false
        }
      ],
      "flags": [
        {
          "name": "vex",
          "arg": "<local-file>",
          "description": "Consume OpenVEX, CSAF 2.0 VEX or CycloneDX VEX. Match advisory and exact product; preserve attribution. PR jobs use trusted base files. Applies to a fresh scan (scan, bom, diff, bundle, decide); refused with --from.",
          "default": "none",
          "repeatable": true
        },
        {
          "name": "vex-product",
          "arg": "<purl|url>",
          "description": "Root product context for subcomponent assertions in --vex documents.",
          "default": "none"
        },
        {
          "name": "rules",
          "arg": "<a.yml,bundled:aibom>",
          "description": "Rule files or bundled packs (aibom, vuln, audit, inventory, all, risk), comma separated.",
          "default": "bundled:all for scan; bundled:aibom for bom, diff and the other commands",
          "repeatable": true
        },
        {
          "name": "policy",
          "arg": "<file>",
          "description": "Policy-as-code YAML that decides which AI providers and components are allowed.",
          "default": "the policy in .keryn.yml, else none"
        },
        {
          "name": "config",
          "arg": "<file>",
          "description": "Configuration file to read.",
          "default": "./.keryn.yml when present"
        },
        {
          "name": "no-config",
          "description": "Ignore .keryn.yml and use built-in defaults.",
          "default": "off"
        },
        {
          "name": "base",
          "arg": "<git-ref|bom.json|result.json>",
          "description": "Baseline to compare against: a git ref, a saved AI-BOM or a saved result.",
          "default": "none"
        },
        {
          "name": "include",
          "arg": "<glob,...>",
          "description": "Only scan paths matching these globs, relative to the scan root. `ts/fixtures/**` is that one folder; `**/fixtures/**` matches at any depth.",
          "default": "everything",
          "repeatable": true
        },
        {
          "name": "exclude",
          "arg": "<glob,...>",
          "description": "Skip paths matching these globs.",
          "default": "none",
          "repeatable": true
        },
        {
          "name": "max-file-size",
          "arg": "<bytes>",
          "description": "Largest file read; larger files are listed as skipped and counted in coverage. Lockfiles past it are still read for the dependency stage, up to 64 MiB, and never by the pattern or secrets pass.",
          "default": "the built-in limit"
        },
        {
          "name": "max-files",
          "arg": "<n>",
          "description": "Most files read.",
          "default": "the built-in limit"
        },
        {
          "name": "max-total-size",
          "arg": "<bytes>",
          "description": "Most bytes read in total.",
          "default": "the built-in limit"
        },
        {
          "name": "timeout",
          "arg": "<seconds>",
          "description": "Time limit of the scan. Reaching it leaves coverage incomplete (exit 3).",
          "default": "the timeout in .keryn.yml, else the built-in limit"
        },
        {
          "name": "offline",
          "description": "Accepted and a no-op: these commands never use the network unless --online is given.",
          "default": "off"
        },
        {
          "name": "symlinks",
          "arg": "skip|follow-confined|error",
          "description": "What to do with symbolic links: skip them, follow them inside the scan root, or fail.",
          "default": "skip"
        },
        {
          "name": "aibom",
          "arg": "<file>",
          "description": "Write the CycloneDX 1.6 AI bill of materials. `-` is stdout.",
          "default": "none"
        },
        {
          "name": "sbom",
          "arg": "<file>",
          "description": "Write the dependency SBOM: every package the lockfiles lock, with purl, licence and dependency graph (the AI-BOM lists AI components only). `-` is stdout.",
          "default": "none"
        },
        {
          "name": "sbom-format",
          "arg": "cyclonedx|spdx",
          "description": "Format of --sbom: CycloneDX 1.6 JSON or SPDX 2.3 JSON.",
          "default": "cyclonedx"
        },
        {
          "name": "sarif",
          "arg": "<file>",
          "description": "Write SARIF 2.1.0. `-` is stdout.",
          "default": "none"
        },
        {
          "name": "junit",
          "arg": "<file>",
          "description": "Write a JUnit XML report. `-` is stdout.",
          "default": "none"
        },
        {
          "name": "gitlab-sast",
          "arg": "<file>",
          "description": "Write a GitLab SAST report. `-` is stdout.",
          "default": "none"
        },
        {
          "name": "codequality",
          "arg": "<file>",
          "description": "Write a Code Quality report. `-` is stdout.",
          "default": "none"
        },
        {
          "name": "json",
          "arg": "<file>",
          "description": "Write the Keryn result JSON (keryn.dev/result/v1). `-` is stdout.",
          "default": "none"
        },
        {
          "name": "markdown",
          "arg": "<file>",
          "description": "Write a pull request or merge request summary. `-` is stdout.",
          "default": "none"
        },
        {
          "name": "annotations",
          "arg": "github|azure|gitlab|teamcity",
          "description": "Print findings as CI log annotations for that system.",
          "default": "none"
        },
        {
          "name": "fail-on",
          "arg": "error|warning|info|none",
          "description": "Lowest severity that makes the run exit 1.",
          "default": "error"
        },
        {
          "name": "fail-on-unsupported",
          "description": "Exit 3 on unsupported, partial or timed-out rules. This is already the default; the flag is kept for scripts.",
          "default": "on"
        },
        {
          "name": "allow-incomplete",
          "description": "Do not exit 3 when rules were unsupported, partial or timed out.",
          "default": "off"
        },
        {
          "name": "advisory-max-age",
          "arg": "<days>",
          "description": "How old the installed offline advisory snapshot may be. An older one still checks the dependencies, but the run is incomplete (exit 3) and coverage says how old it is.",
          "default": ".keryn.yml advisoryMaxAge, else no limit"
        },
        {
          "name": "require-advisories",
          "description": "Exit 3 when the tree has lockfiles whose packages were not matched against vulnerability advisories (an offline scan); pass --online to check them. Off by default: an offline scan says \"dependency advisories not checked (offline)\" in its verdict and exits as before.",
          "default": "off"
        },
        {
          "name": "gate-confidence",
          "arg": "P1|P2",
          "description": "Lowest rule confidence that counts toward --fail-on. P2 widens the gate.",
          "default": "P1"
        },
        {
          "name": "secrets-history",
          "description": "Also scan the added lines of every commit reachable from HEAD for secrets. A secret removed in a later commit is reported with the commit that introduced it, and must still be revoked. A shallow clone, the commit cap or a missing git make the secrets coverage incomplete.",
          "default": "off"
        },
        {
          "name": "secrets-since",
          "arg": "<ref|date>",
          "description": "With --secrets-history: only commits after this ref or date.",
          "default": "all reachable commits"
        },
        {
          "name": "dependencies",
          "arg": "<file>",
          "description": "A resolved dependency list your build produced, read like a lockfile: dependency-tree.json or dependency-tree.txt from mvn dependency:tree, or a CycloneDX or SPDX JSON SBOM named bom.json, sbom.json, *.cdx.json or *.spdx.json. It must be inside the scanned folder and supersedes the pom.xml or Gradle build of its project. A component whose purl cannot be read makes the dependency coverage incomplete. Keryn runs no build tool.",
          "default": "a dependency-tree.json or dependency-tree.txt found in the scanned tree; an SBOM is read only when named",
          "repeatable": true
        },
        {
          "name": "secrets-config",
          "arg": "<file>",
          "description": "A gitleaks TOML config with your own secret rules; [extend] useDefault = true keeps the 222 defaults. A file that cannot be used as a whole is a usage error (exit 2). A .gitleaksignore at the scanned root is always read.",
          "default": ".keryn.yml secrets.config, else .gitleaks.toml at the scanned root, else the defaults"
        },
        {
          "name": "secrets-max-commits",
          "arg": "<n>",
          "description": "With --secrets-history: read at most this many commits (newest first); more makes coverage incomplete.",
          "default": "10000"
        },
        {
          "name": "no-deep",
          "description": "Skip cross-file analysis (interprocedural) and run the pattern rules only.",
          "default": "off: cross-file analysis runs after the pattern rules"
        },
        {
          "name": "deep-timeout",
          "arg": "<seconds>",
          "description": "Time limit of cross-file analysis. A run stopped by it keeps the pattern findings and makes the scan incomplete.",
          "default": "300",
          "env": [
            "KERYN_DEEP_TIMEOUT_MS"
          ]
        },
        {
          "name": "engine",
          "arg": "deep|forge",
          "description": "Interprocedural engine of cross-file analysis. Forge is the fact-bundle solver with KSQL rules, side by side with deep while it proves itself.",
          "default": "deep"
        },
        {
          "name": "repo-root",
          "arg": "<dir>",
          "description": "The repository the scanned folder belongs to: report paths, rule `paths:`, code roles, include/exclude and .keryn.yml see repository-relative paths. Fingerprints stay relative to the folder.",
          "default": "the scanned folder"
        },
        {
          "name": "no-cache",
          "description": "Neither read nor write the rescan cache.",
          "default": "off",
          "env": [
            "KERYN_NO_CACHE"
          ]
        },
        {
          "name": "online",
          "description": "Check locked dependencies against OSV.dev, refresh the malicious-package (MAL) records for them, and look up on deps.dev the licences their lockfiles do not record. Sends package names and versions only, never code or paths. Without it the report says which lockfiles were not checked.",
          "default": "off"
        },
        {
          "name": "no-ignore",
          "description": "Also scan files .gitignore and .git/info/exclude exclude. Keryn's own earlier outputs are never scanned.",
          "default": "off: ignored files are skipped and counted in coverage"
        },
        {
          "name": "new-only",
          "description": "Gate only new findings against an explicit paired Git --base. Incomplete comparisons fail closed; this is not release approval. Requires a release after 0.5.2.",
          "default": "off"
        },
        {
          "name": "fail-on-added",
          "description": "Exit 1 when components were added relative to --base. Refused together with --new-only.",
          "default": "off"
        },
        {
          "name": "exit-warn",
          "description": "Exit 10 for a pass with warnings.",
          "default": "off"
        },
        {
          "name": "subject",
          "arg": "<name>",
          "description": "Name recorded as the subject of the AI-BOM.",
          "default": "the folder name"
        },
        {
          "name": "revision",
          "arg": "<id>",
          "description": "Revision recorded in the output. Default: the git commit of the scanned checkout, with -dirty when the scanned path has uncommitted or untracked changes; \"dir\" outside git.",
          "default": "git HEAD, else dir"
        },
        {
          "name": "timestamp",
          "arg": "<iso|now>",
          "description": "Timestamp written into outputs. The default keeps the same input giving the same bytes.",
          "default": "1970-01-01T00:00:00Z, or SOURCE_DATE_EPOCH when set",
          "env": [
            "SOURCE_DATE_EPOCH"
          ]
        },
        {
          "name": "observed-browser",
          "arg": "<snapshot.json>",
          "description": "A page snapshot (the extension's download): its AI technologies join the AI-BOM with basis observed-in-browser.",
          "default": "none"
        },
        {
          "name": "observed-network",
          "arg": "<observed-ports.json>",
          "description": "Network observations: classified AI services join the AI-BOM (observed-on-network) and their findings gate.",
          "default": "none"
        },
        {
          "name": "summary-by",
          "arg": "owasp_llm|owasp_agentic|cwe|nist_ai_rmf|atlas",
          "description": "Group findings by a framework in the console and markdown summary. Reference only; not a compliance assessment.",
          "default": "ungrouped"
        },
        {
          "name": "verbose",
          "description": "List the gating findings with their proof rung and flow.",
          "default": "off"
        },
        {
          "name": "quiet",
          "short": "q",
          "description": "Print nothing on success.",
          "default": "off"
        },
        {
          "name": "agent-card",
          "arg": "<file>",
          "description": "Read a local A2A Agent Card as declarations (up to 32 JSON files, each at most 256 KiB). Requires --aibom or --json unless bom uses its default AI-BOM output.",
          "default": "none",
          "repeatable": true,
          "commands": [
            "scan",
            "bom"
          ]
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn scan .",
          "note": "Scan the current folder; the exit code is the gate."
        },
        {
          "command": "keryn scan . --aibom bom.cdx.json --sarif keryn.sarif --fail-on warning",
          "note": "Write CycloneDX and SARIF, and fail on warnings too."
        },
        {
          "command": "keryn scan . --base origin/main --fail-on-added",
          "note": "Fail when the change adds AI components."
        }
      ],
      "exit": {
        "0": "pass: nothing at or above --fail-on, coverage complete",
        "1": "violations: findings at or above --fail-on, or a policy violation",
        "2": "usage or configuration error",
        "3": "coverage incomplete: a rule was unsupported, partial or timed out (--allow-incomplete opts out)",
        "4": "internal error or timeout",
        "10": "pass with warnings (only with --exit-warn)"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "bom",
      "summary": "AI-BOM only (fast path); prints CycloneDX to stdout by default",
      "usage": "keryn bom [path] [options]",
      "args": [
        {
          "name": "path",
          "description": "Folder or file to inventory.",
          "required": false
        }
      ],
      "flags": [
        {
          "name": "vex",
          "arg": "<local-file>",
          "description": "Consume OpenVEX, CSAF 2.0 VEX or CycloneDX VEX. Match advisory and exact product; preserve attribution. PR jobs use trusted base files. Applies to a fresh scan (scan, bom, diff, bundle, decide); refused with --from.",
          "default": "none",
          "repeatable": true
        },
        {
          "name": "vex-product",
          "arg": "<purl|url>",
          "description": "Root product context for subcomponent assertions in --vex documents.",
          "default": "none"
        },
        {
          "name": "rules",
          "arg": "<a.yml,bundled:aibom>",
          "description": "Rule files or bundled packs (aibom, vuln, audit, inventory, all, risk), comma separated.",
          "default": "bundled:all for scan; bundled:aibom for bom, diff and the other commands",
          "repeatable": true
        },
        {
          "name": "policy",
          "arg": "<file>",
          "description": "Policy-as-code YAML that decides which AI providers and components are allowed.",
          "default": "the policy in .keryn.yml, else none"
        },
        {
          "name": "config",
          "arg": "<file>",
          "description": "Configuration file to read.",
          "default": "./.keryn.yml when present"
        },
        {
          "name": "no-config",
          "description": "Ignore .keryn.yml and use built-in defaults.",
          "default": "off"
        },
        {
          "name": "base",
          "arg": "<git-ref|bom.json|result.json>",
          "description": "Baseline to compare against: a git ref, a saved AI-BOM or a saved result.",
          "default": "none"
        },
        {
          "name": "include",
          "arg": "<glob,...>",
          "description": "Only scan paths matching these globs, relative to the scan root. `ts/fixtures/**` is that one folder; `**/fixtures/**` matches at any depth.",
          "default": "everything",
          "repeatable": true
        },
        {
          "name": "exclude",
          "arg": "<glob,...>",
          "description": "Skip paths matching these globs.",
          "default": "none",
          "repeatable": true
        },
        {
          "name": "max-file-size",
          "arg": "<bytes>",
          "description": "Largest file read; larger files are listed as skipped and counted in coverage. Lockfiles past it are still read for the dependency stage, up to 64 MiB, and never by the pattern or secrets pass.",
          "default": "the built-in limit"
        },
        {
          "name": "max-files",
          "arg": "<n>",
          "description": "Most files read.",
          "default": "the built-in limit"
        },
        {
          "name": "max-total-size",
          "arg": "<bytes>",
          "description": "Most bytes read in total.",
          "default": "the built-in limit"
        },
        {
          "name": "timeout",
          "arg": "<seconds>",
          "description": "Time limit of the scan. Reaching it leaves coverage incomplete (exit 3).",
          "default": "the timeout in .keryn.yml, else the built-in limit"
        },
        {
          "name": "offline",
          "description": "Accepted and a no-op: these commands never use the network unless --online is given.",
          "default": "off"
        },
        {
          "name": "symlinks",
          "arg": "skip|follow-confined|error",
          "description": "What to do with symbolic links: skip them, follow them inside the scan root, or fail.",
          "default": "skip"
        },
        {
          "name": "aibom",
          "arg": "<file>",
          "description": "Write the CycloneDX 1.6 AI bill of materials. `-` is stdout.",
          "default": "none"
        },
        {
          "name": "sbom",
          "arg": "<file>",
          "description": "Write the dependency SBOM: every package the lockfiles lock, with purl, licence and dependency graph (the AI-BOM lists AI components only). `-` is stdout.",
          "default": "none"
        },
        {
          "name": "sbom-format",
          "arg": "cyclonedx|spdx",
          "description": "Format of --sbom: CycloneDX 1.6 JSON or SPDX 2.3 JSON.",
          "default": "cyclonedx"
        },
        {
          "name": "sarif",
          "arg": "<file>",
          "description": "Write SARIF 2.1.0. `-` is stdout.",
          "default": "none"
        },
        {
          "name": "junit",
          "arg": "<file>",
          "description": "Write a JUnit XML report. `-` is stdout.",
          "default": "none"
        },
        {
          "name": "gitlab-sast",
          "arg": "<file>",
          "description": "Write a GitLab SAST report. `-` is stdout.",
          "default": "none"
        },
        {
          "name": "codequality",
          "arg": "<file>",
          "description": "Write a Code Quality report. `-` is stdout.",
          "default": "none"
        },
        {
          "name": "json",
          "arg": "<file>",
          "description": "Write the Keryn result JSON (keryn.dev/result/v1). `-` is stdout.",
          "default": "none"
        },
        {
          "name": "markdown",
          "arg": "<file>",
          "description": "Write a pull request or merge request summary. `-` is stdout.",
          "default": "none"
        },
        {
          "name": "annotations",
          "arg": "github|azure|gitlab|teamcity",
          "description": "Print findings as CI log annotations for that system.",
          "default": "none"
        },
        {
          "name": "fail-on",
          "arg": "error|warning|info|none",
          "description": "Lowest severity that makes the run exit 1.",
          "default": "error"
        },
        {
          "name": "fail-on-unsupported",
          "description": "Exit 3 on unsupported, partial or timed-out rules. This is already the default; the flag is kept for scripts.",
          "default": "on"
        },
        {
          "name": "allow-incomplete",
          "description": "Do not exit 3 when rules were unsupported, partial or timed out.",
          "default": "off"
        },
        {
          "name": "advisory-max-age",
          "arg": "<days>",
          "description": "How old the installed offline advisory snapshot may be. An older one still checks the dependencies, but the run is incomplete (exit 3) and coverage says how old it is.",
          "default": ".keryn.yml advisoryMaxAge, else no limit"
        },
        {
          "name": "require-advisories",
          "description": "Exit 3 when the tree has lockfiles whose packages were not matched against vulnerability advisories (an offline scan); pass --online to check them. Off by default: an offline scan says \"dependency advisories not checked (offline)\" in its verdict and exits as before.",
          "default": "off"
        },
        {
          "name": "gate-confidence",
          "arg": "P1|P2",
          "description": "Lowest rule confidence that counts toward --fail-on. P2 widens the gate.",
          "default": "P1"
        },
        {
          "name": "secrets-history",
          "description": "Also scan the added lines of every commit reachable from HEAD for secrets. A secret removed in a later commit is reported with the commit that introduced it, and must still be revoked. A shallow clone, the commit cap or a missing git make the secrets coverage incomplete.",
          "default": "off"
        },
        {
          "name": "secrets-since",
          "arg": "<ref|date>",
          "description": "With --secrets-history: only commits after this ref or date.",
          "default": "all reachable commits"
        },
        {
          "name": "dependencies",
          "arg": "<file>",
          "description": "A resolved dependency list your build produced, read like a lockfile: dependency-tree.json or dependency-tree.txt from mvn dependency:tree, or a CycloneDX or SPDX JSON SBOM named bom.json, sbom.json, *.cdx.json or *.spdx.json. It must be inside the scanned folder and supersedes the pom.xml or Gradle build of its project. A component whose purl cannot be read makes the dependency coverage incomplete. Keryn runs no build tool.",
          "default": "a dependency-tree.json or dependency-tree.txt found in the scanned tree; an SBOM is read only when named",
          "repeatable": true
        },
        {
          "name": "secrets-config",
          "arg": "<file>",
          "description": "A gitleaks TOML config with your own secret rules; [extend] useDefault = true keeps the 222 defaults. A file that cannot be used as a whole is a usage error (exit 2). A .gitleaksignore at the scanned root is always read.",
          "default": ".keryn.yml secrets.config, else .gitleaks.toml at the scanned root, else the defaults"
        },
        {
          "name": "secrets-max-commits",
          "arg": "<n>",
          "description": "With --secrets-history: read at most this many commits (newest first); more makes coverage incomplete.",
          "default": "10000"
        },
        {
          "name": "no-deep",
          "description": "Skip cross-file analysis (interprocedural) and run the pattern rules only.",
          "default": "off: cross-file analysis runs after the pattern rules"
        },
        {
          "name": "deep-timeout",
          "arg": "<seconds>",
          "description": "Time limit of cross-file analysis. A run stopped by it keeps the pattern findings and makes the scan incomplete.",
          "default": "300",
          "env": [
            "KERYN_DEEP_TIMEOUT_MS"
          ]
        },
        {
          "name": "engine",
          "arg": "deep|forge",
          "description": "Interprocedural engine of cross-file analysis. Forge is the fact-bundle solver with KSQL rules, side by side with deep while it proves itself.",
          "default": "deep"
        },
        {
          "name": "repo-root",
          "arg": "<dir>",
          "description": "The repository the scanned folder belongs to: report paths, rule `paths:`, code roles, include/exclude and .keryn.yml see repository-relative paths. Fingerprints stay relative to the folder.",
          "default": "the scanned folder"
        },
        {
          "name": "no-cache",
          "description": "Neither read nor write the rescan cache.",
          "default": "off",
          "env": [
            "KERYN_NO_CACHE"
          ]
        },
        {
          "name": "online",
          "description": "Check locked dependencies against OSV.dev, refresh the malicious-package (MAL) records for them, and look up on deps.dev the licences their lockfiles do not record. Sends package names and versions only, never code or paths. Without it the report says which lockfiles were not checked.",
          "default": "off"
        },
        {
          "name": "no-ignore",
          "description": "Also scan files .gitignore and .git/info/exclude exclude. Keryn's own earlier outputs are never scanned.",
          "default": "off: ignored files are skipped and counted in coverage"
        },
        {
          "name": "new-only",
          "description": "Gate only new findings against an explicit paired Git --base. Incomplete comparisons fail closed; this is not release approval. Requires a release after 0.5.2.",
          "default": "off"
        },
        {
          "name": "fail-on-added",
          "description": "Exit 1 when components were added relative to --base. Refused together with --new-only.",
          "default": "off"
        },
        {
          "name": "exit-warn",
          "description": "Exit 10 for a pass with warnings.",
          "default": "off"
        },
        {
          "name": "subject",
          "arg": "<name>",
          "description": "Name recorded as the subject of the AI-BOM.",
          "default": "the folder name"
        },
        {
          "name": "revision",
          "arg": "<id>",
          "description": "Revision recorded in the output. Default: the git commit of the scanned checkout, with -dirty when the scanned path has uncommitted or untracked changes; \"dir\" outside git.",
          "default": "git HEAD, else dir"
        },
        {
          "name": "timestamp",
          "arg": "<iso|now>",
          "description": "Timestamp written into outputs. The default keeps the same input giving the same bytes.",
          "default": "1970-01-01T00:00:00Z, or SOURCE_DATE_EPOCH when set",
          "env": [
            "SOURCE_DATE_EPOCH"
          ]
        },
        {
          "name": "observed-browser",
          "arg": "<snapshot.json>",
          "description": "A page snapshot (the extension's download): its AI technologies join the AI-BOM with basis observed-in-browser.",
          "default": "none"
        },
        {
          "name": "observed-network",
          "arg": "<observed-ports.json>",
          "description": "Network observations: classified AI services join the AI-BOM (observed-on-network) and their findings gate.",
          "default": "none"
        },
        {
          "name": "summary-by",
          "arg": "owasp_llm|owasp_agentic|cwe|nist_ai_rmf|atlas",
          "description": "Group findings by a framework in the console and markdown summary. Reference only; not a compliance assessment.",
          "default": "ungrouped"
        },
        {
          "name": "verbose",
          "description": "List the gating findings with their proof rung and flow.",
          "default": "off"
        },
        {
          "name": "quiet",
          "short": "q",
          "description": "Print nothing on success.",
          "default": "off"
        },
        {
          "name": "agent-card",
          "arg": "<file>",
          "description": "Read a local A2A Agent Card as declarations (up to 32 JSON files, each at most 256 KiB). Requires --aibom or --json unless bom uses its default AI-BOM output.",
          "default": "none",
          "repeatable": true,
          "commands": [
            "scan",
            "bom"
          ]
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn bom . > bom.cdx.json",
          "note": "Print the CycloneDX 1.6 AI-BOM."
        },
        {
          "command": "keryn bom . --aibom bom.cdx.json --quiet",
          "note": "Write it to a file."
        }
      ],
      "exit": {
        "0": "pass: nothing at or above --fail-on, coverage complete",
        "1": "violations: findings at or above --fail-on, or a policy violation",
        "2": "usage or configuration error",
        "3": "coverage incomplete: a rule was unsupported, partial or timed out (--allow-incomplete opts out)",
        "4": "internal error or timeout",
        "10": "pass with warnings (only with --exit-warn)"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "diff",
      "summary": "components/findings added/removed vs a base",
      "usage": "keryn diff [path] --base <git ref | bom.json> [options]",
      "args": [
        {
          "name": "path",
          "description": "Folder to compare.",
          "required": false
        }
      ],
      "flags": [
        {
          "name": "vex",
          "arg": "<local-file>",
          "description": "Consume OpenVEX, CSAF 2.0 VEX or CycloneDX VEX. Match advisory and exact product; preserve attribution. PR jobs use trusted base files. Applies to a fresh scan (scan, bom, diff, bundle, decide); refused with --from.",
          "default": "none",
          "repeatable": true
        },
        {
          "name": "vex-product",
          "arg": "<purl|url>",
          "description": "Root product context for subcomponent assertions in --vex documents.",
          "default": "none"
        },
        {
          "name": "rules",
          "arg": "<a.yml,bundled:aibom>",
          "description": "Rule files or bundled packs (aibom, vuln, audit, inventory, all, risk), comma separated.",
          "default": "bundled:all for scan; bundled:aibom for bom, diff and the other commands",
          "repeatable": true
        },
        {
          "name": "policy",
          "arg": "<file>",
          "description": "Policy-as-code YAML that decides which AI providers and components are allowed.",
          "default": "the policy in .keryn.yml, else none"
        },
        {
          "name": "config",
          "arg": "<file>",
          "description": "Configuration file to read.",
          "default": "./.keryn.yml when present"
        },
        {
          "name": "no-config",
          "description": "Ignore .keryn.yml and use built-in defaults.",
          "default": "off"
        },
        {
          "name": "base",
          "arg": "<git-ref|bom.json|result.json>",
          "description": "Baseline to compare against: a git ref, a saved AI-BOM or a saved result.",
          "default": "none"
        },
        {
          "name": "include",
          "arg": "<glob,...>",
          "description": "Only scan paths matching these globs, relative to the scan root. `ts/fixtures/**` is that one folder; `**/fixtures/**` matches at any depth.",
          "default": "everything",
          "repeatable": true
        },
        {
          "name": "exclude",
          "arg": "<glob,...>",
          "description": "Skip paths matching these globs.",
          "default": "none",
          "repeatable": true
        },
        {
          "name": "max-file-size",
          "arg": "<bytes>",
          "description": "Largest file read; larger files are listed as skipped and counted in coverage. Lockfiles past it are still read for the dependency stage, up to 64 MiB, and never by the pattern or secrets pass.",
          "default": "the built-in limit"
        },
        {
          "name": "max-files",
          "arg": "<n>",
          "description": "Most files read.",
          "default": "the built-in limit"
        },
        {
          "name": "max-total-size",
          "arg": "<bytes>",
          "description": "Most bytes read in total.",
          "default": "the built-in limit"
        },
        {
          "name": "timeout",
          "arg": "<seconds>",
          "description": "Time limit of the scan. Reaching it leaves coverage incomplete (exit 3).",
          "default": "the timeout in .keryn.yml, else the built-in limit"
        },
        {
          "name": "offline",
          "description": "Accepted and a no-op: these commands never use the network unless --online is given.",
          "default": "off"
        },
        {
          "name": "symlinks",
          "arg": "skip|follow-confined|error",
          "description": "What to do with symbolic links: skip them, follow them inside the scan root, or fail.",
          "default": "skip"
        },
        {
          "name": "aibom",
          "arg": "<file>",
          "description": "Write the CycloneDX 1.6 AI bill of materials. `-` is stdout.",
          "default": "none"
        },
        {
          "name": "sbom",
          "arg": "<file>",
          "description": "Write the dependency SBOM: every package the lockfiles lock, with purl, licence and dependency graph (the AI-BOM lists AI components only). `-` is stdout.",
          "default": "none"
        },
        {
          "name": "sbom-format",
          "arg": "cyclonedx|spdx",
          "description": "Format of --sbom: CycloneDX 1.6 JSON or SPDX 2.3 JSON.",
          "default": "cyclonedx"
        },
        {
          "name": "sarif",
          "arg": "<file>",
          "description": "Write SARIF 2.1.0. `-` is stdout.",
          "default": "none"
        },
        {
          "name": "junit",
          "arg": "<file>",
          "description": "Write a JUnit XML report. `-` is stdout.",
          "default": "none"
        },
        {
          "name": "gitlab-sast",
          "arg": "<file>",
          "description": "Write a GitLab SAST report. `-` is stdout.",
          "default": "none"
        },
        {
          "name": "codequality",
          "arg": "<file>",
          "description": "Write a Code Quality report. `-` is stdout.",
          "default": "none"
        },
        {
          "name": "json",
          "arg": "<file>",
          "description": "Write the Keryn result JSON (keryn.dev/result/v1). `-` is stdout.",
          "default": "none"
        },
        {
          "name": "markdown",
          "arg": "<file>",
          "description": "Write a pull request or merge request summary. `-` is stdout.",
          "default": "none"
        },
        {
          "name": "annotations",
          "arg": "github|azure|gitlab|teamcity",
          "description": "Print findings as CI log annotations for that system.",
          "default": "none"
        },
        {
          "name": "fail-on",
          "arg": "error|warning|info|none",
          "description": "Lowest severity that makes the run exit 1.",
          "default": "error"
        },
        {
          "name": "fail-on-unsupported",
          "description": "Exit 3 on unsupported, partial or timed-out rules. This is already the default; the flag is kept for scripts.",
          "default": "on"
        },
        {
          "name": "allow-incomplete",
          "description": "Do not exit 3 when rules were unsupported, partial or timed out.",
          "default": "off"
        },
        {
          "name": "advisory-max-age",
          "arg": "<days>",
          "description": "How old the installed offline advisory snapshot may be. An older one still checks the dependencies, but the run is incomplete (exit 3) and coverage says how old it is.",
          "default": ".keryn.yml advisoryMaxAge, else no limit"
        },
        {
          "name": "require-advisories",
          "description": "Exit 3 when the tree has lockfiles whose packages were not matched against vulnerability advisories (an offline scan); pass --online to check them. Off by default: an offline scan says \"dependency advisories not checked (offline)\" in its verdict and exits as before.",
          "default": "off"
        },
        {
          "name": "gate-confidence",
          "arg": "P1|P2",
          "description": "Lowest rule confidence that counts toward --fail-on. P2 widens the gate.",
          "default": "P1"
        },
        {
          "name": "secrets-history",
          "description": "Also scan the added lines of every commit reachable from HEAD for secrets. A secret removed in a later commit is reported with the commit that introduced it, and must still be revoked. A shallow clone, the commit cap or a missing git make the secrets coverage incomplete.",
          "default": "off"
        },
        {
          "name": "secrets-since",
          "arg": "<ref|date>",
          "description": "With --secrets-history: only commits after this ref or date.",
          "default": "all reachable commits"
        },
        {
          "name": "dependencies",
          "arg": "<file>",
          "description": "A resolved dependency list your build produced, read like a lockfile: dependency-tree.json or dependency-tree.txt from mvn dependency:tree, or a CycloneDX or SPDX JSON SBOM named bom.json, sbom.json, *.cdx.json or *.spdx.json. It must be inside the scanned folder and supersedes the pom.xml or Gradle build of its project. A component whose purl cannot be read makes the dependency coverage incomplete. Keryn runs no build tool.",
          "default": "a dependency-tree.json or dependency-tree.txt found in the scanned tree; an SBOM is read only when named",
          "repeatable": true
        },
        {
          "name": "secrets-config",
          "arg": "<file>",
          "description": "A gitleaks TOML config with your own secret rules; [extend] useDefault = true keeps the 222 defaults. A file that cannot be used as a whole is a usage error (exit 2). A .gitleaksignore at the scanned root is always read.",
          "default": ".keryn.yml secrets.config, else .gitleaks.toml at the scanned root, else the defaults"
        },
        {
          "name": "secrets-max-commits",
          "arg": "<n>",
          "description": "With --secrets-history: read at most this many commits (newest first); more makes coverage incomplete.",
          "default": "10000"
        },
        {
          "name": "no-deep",
          "description": "Skip cross-file analysis (interprocedural) and run the pattern rules only.",
          "default": "off: cross-file analysis runs after the pattern rules"
        },
        {
          "name": "deep-timeout",
          "arg": "<seconds>",
          "description": "Time limit of cross-file analysis. A run stopped by it keeps the pattern findings and makes the scan incomplete.",
          "default": "300",
          "env": [
            "KERYN_DEEP_TIMEOUT_MS"
          ]
        },
        {
          "name": "engine",
          "arg": "deep|forge",
          "description": "Interprocedural engine of cross-file analysis. Forge is the fact-bundle solver with KSQL rules, side by side with deep while it proves itself.",
          "default": "deep"
        },
        {
          "name": "repo-root",
          "arg": "<dir>",
          "description": "The repository the scanned folder belongs to: report paths, rule `paths:`, code roles, include/exclude and .keryn.yml see repository-relative paths. Fingerprints stay relative to the folder.",
          "default": "the scanned folder"
        },
        {
          "name": "no-cache",
          "description": "Neither read nor write the rescan cache.",
          "default": "off",
          "env": [
            "KERYN_NO_CACHE"
          ]
        },
        {
          "name": "online",
          "description": "Check locked dependencies against OSV.dev, refresh the malicious-package (MAL) records for them, and look up on deps.dev the licences their lockfiles do not record. Sends package names and versions only, never code or paths. Without it the report says which lockfiles were not checked.",
          "default": "off"
        },
        {
          "name": "no-ignore",
          "description": "Also scan files .gitignore and .git/info/exclude exclude. Keryn's own earlier outputs are never scanned.",
          "default": "off: ignored files are skipped and counted in coverage"
        },
        {
          "name": "new-only",
          "description": "Gate only new findings against an explicit paired Git --base. Incomplete comparisons fail closed; this is not release approval. Requires a release after 0.5.2.",
          "default": "off"
        },
        {
          "name": "fail-on-added",
          "description": "Exit 1 when components were added relative to --base. Refused together with --new-only.",
          "default": "off"
        },
        {
          "name": "exit-warn",
          "description": "Exit 10 for a pass with warnings.",
          "default": "off"
        },
        {
          "name": "subject",
          "arg": "<name>",
          "description": "Name recorded as the subject of the AI-BOM.",
          "default": "the folder name"
        },
        {
          "name": "revision",
          "arg": "<id>",
          "description": "Revision recorded in the output. Default: the git commit of the scanned checkout, with -dirty when the scanned path has uncommitted or untracked changes; \"dir\" outside git.",
          "default": "git HEAD, else dir"
        },
        {
          "name": "timestamp",
          "arg": "<iso|now>",
          "description": "Timestamp written into outputs. The default keeps the same input giving the same bytes.",
          "default": "1970-01-01T00:00:00Z, or SOURCE_DATE_EPOCH when set",
          "env": [
            "SOURCE_DATE_EPOCH"
          ]
        },
        {
          "name": "observed-browser",
          "arg": "<snapshot.json>",
          "description": "A page snapshot (the extension's download): its AI technologies join the AI-BOM with basis observed-in-browser.",
          "default": "none"
        },
        {
          "name": "observed-network",
          "arg": "<observed-ports.json>",
          "description": "Network observations: classified AI services join the AI-BOM (observed-on-network) and their findings gate.",
          "default": "none"
        },
        {
          "name": "summary-by",
          "arg": "owasp_llm|owasp_agentic|cwe|nist_ai_rmf|atlas",
          "description": "Group findings by a framework in the console and markdown summary. Reference only; not a compliance assessment.",
          "default": "ungrouped"
        },
        {
          "name": "verbose",
          "description": "List the gating findings with their proof rung and flow.",
          "default": "off"
        },
        {
          "name": "quiet",
          "short": "q",
          "description": "Print nothing on success.",
          "default": "off"
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn diff . --base origin/main",
          "note": "What this branch adds or removes against main."
        },
        {
          "command": "keryn diff . --base bom.cdx.json --fail-on-added",
          "note": "Fail when a component was added to the saved AI-BOM."
        }
      ],
      "exit": {
        "0": "pass: nothing at or above --fail-on, coverage complete",
        "1": "violations, or components added with --fail-on-added",
        "2": "usage or configuration error",
        "3": "coverage incomplete: a rule was unsupported, partial or timed out (--allow-incomplete opts out)",
        "4": "internal error or timeout",
        "10": "pass with warnings (only with --exit-warn)"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "sbom",
      "summary": "dependency SBOM: every locked package with purl, licence and graph, CycloneDX 1.6 or SPDX 2.3 (no rules, offline)",
      "usage": "keryn sbom [path] [--format cyclonedx|spdx] [-o <file>]",
      "args": [
        {
          "name": "path",
          "description": "Folder whose lockfiles to list.",
          "required": false
        }
      ],
      "flags": [
        {
          "name": "format",
          "arg": "cyclonedx|spdx",
          "description": "CycloneDX 1.6 JSON or SPDX 2.3 JSON.",
          "default": "cyclonedx"
        },
        {
          "name": "out",
          "arg": "<file>",
          "description": "Write here instead of stdout. `-` is stdout.",
          "default": "stdout",
          "short": "o"
        },
        {
          "name": "subject",
          "arg": "<name>",
          "description": "Name of the root component (the application).",
          "default": "the folder name"
        },
        {
          "name": "revision",
          "arg": "<id>",
          "description": "Version of the root component. Default: the git commit of the scanned checkout (-dirty when it has changes); \"dir\" outside git.",
          "default": "git HEAD, else dir"
        },
        {
          "name": "timestamp",
          "arg": "<iso|now>",
          "description": "Document timestamp, for reproducible output.",
          "default": "SOURCE_DATE_EPOCH, else a fixed 1970 timestamp",
          "env": [
            "SOURCE_DATE_EPOCH"
          ]
        },
        {
          "name": "no-ignore",
          "description": "Also read lockfiles that .gitignore excludes.",
          "default": "off"
        },
        {
          "name": "quiet",
          "description": "No summary line on stderr.",
          "default": "off",
          "short": "q"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn sbom . -o sbom.cdx.json",
          "note": "CycloneDX 1.6 SBOM of every locked dependency."
        },
        {
          "command": "keryn sbom . --format spdx -o sbom.spdx.json",
          "note": "The same as SPDX 2.3."
        }
      ],
      "exit": {
        "0": "written",
        "2": "usage error",
        "3": "no lockfile found, or a lockfile too large to read: the SBOM is incomplete"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "policy check",
      "summary": "evaluate a policy against an existing BOM (--policy required)",
      "usage": "keryn policy check <bom.json> --policy <policy.yml> [options]",
      "args": [
        {
          "name": "bom.json",
          "description": "A CycloneDX AI-BOM written by keryn bom or keryn scan --aibom.",
          "required": true
        }
      ],
      "flags": [],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn policy check bom.cdx.json --policy .keryn/policy.yml",
          "note": "Judge a saved AI-BOM without rescanning."
        }
      ],
      "exit": {
        "0": "pass: nothing at or above --fail-on, coverage complete",
        "1": "violations: findings at or above --fail-on, or a policy violation",
        "2": "usage or configuration error",
        "3": "coverage incomplete: a rule was unsupported, partial or timed out (--allow-incomplete opts out)",
        "4": "internal error or timeout",
        "10": "pass with warnings (only with --exit-warn)"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "policy lint",
      "summary": "validate a policy file against the policy schema",
      "usage": "keryn policy lint <policy.yml>",
      "args": [
        {
          "name": "policy.yml",
          "description": "Policy file to validate.",
          "required": true
        }
      ],
      "flags": [],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn policy lint .keryn/policy.yml",
          "note": "Check the file against keryn-policy.schema.json."
        }
      ],
      "exit": {
        "0": "valid",
        "1": "problems found",
        "2": "usage error or unreadable file"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "bundle",
      "summary": "scan (or --from result.json) -> tamper-evident evidence bundle <out>.bundle.json (keryn-core)",
      "usage": "keryn bundle [path] [options] [--out <prefix>] [--from <result.json>]",
      "args": [
        {
          "name": "path",
          "description": "Folder to scan.",
          "required": false
        }
      ],
      "flags": [
        {
          "name": "out",
          "arg": "<prefix>",
          "description": "Prefix of the written <prefix>.bundle.json. `-` writes the bundle to stdout.",
          "default": "keryn"
        },
        {
          "name": "from",
          "arg": "<result.json>",
          "description": "Build the bundle from a saved result (keryn.dev/result/v1, for example from keryn scan --json) and scan nothing.",
          "default": "scan the path"
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn bundle . --out release --timestamp now",
          "note": "Scan and write release.bundle.json with a real date."
        },
        {
          "command": "keryn bundle --from result.json --out release",
          "note": "Package a saved result without scanning."
        }
      ],
      "exit": {
        "0": "bundle written (gating is keryn scan)",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "verify-bundle",
      "summary": "recompute every digest in a bundle; exit 0 only when ok and publishable",
      "usage": "keryn verify-bundle <file.bundle.json>",
      "args": [
        {
          "name": "file.bundle.json",
          "description": "Bundle written by keryn bundle.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "out",
          "arg": "<prefix>",
          "description": "Prefix of the written <prefix>.bundle.json. `-` writes the bundle to stdout.",
          "default": "keryn"
        },
        {
          "name": "from",
          "arg": "<result.json>",
          "description": "Build the bundle from a saved result (keryn.dev/result/v1, for example from keryn scan --json) and scan nothing.",
          "default": "scan the path"
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn verify-bundle release.bundle.json",
          "note": "Recompute every document and anchor digest."
        }
      ],
      "exit": {
        "0": "ok and publishable (at least one digest-backed anchor)",
        "1": "a digest does not match, or nothing is publishable",
        "2": "usage error or unreadable file"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "rules lint",
      "summary": "check rule files (structure, and what this engine can run)",
      "usage": "keryn rules lint [file|bundled:<pack> ...] [--json] [--fail-on-unsupported] [-q]",
      "args": [
        {
          "name": "file|bundled:<pack>",
          "description": "YAML rules, gitleaks TOML configs, or bundled packs. Defaults to bundled:aibom. Runs offline.",
          "required": false
        }
      ],
      "flags": [
        {
          "name": "json",
          "description": "Print the lint result as JSON.",
          "default": "off"
        },
        {
          "name": "fail-on-unsupported",
          "description": "Exit 3 when a rule is unsupported or partially supported.",
          "default": "off"
        },
        {
          "name": "quiet",
          "short": "q",
          "description": "Suppress the text report. JSON output is still emitted with --json.",
          "default": "off"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn rules lint my-rules.yml",
          "note": "Check structure and support."
        },
        {
          "command": "keryn rules lint bundled:all --json",
          "note": "Lint every bundled pack."
        }
      ],
      "exit": {
        "0": "no errors or requested coverage failure",
        "1": "invalid rules or gitleaks config",
        "2": "invalid arguments or unreadable input",
        "3": "unsupported or partially supported rules with --fail-on-unsupported",
        "4": "internal error"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "ai",
      "summary": "model-proposed triage, summary, threat model, exception drafts, ship-or-hold advice; nothing applied (recorded example without a key)",
      "usage": "keryn ai <triage|summary|threat-model|exceptions|release> --from <result.json> [options]",
      "args": [
        {
          "name": "task",
          "description": "triage, summary, threat-model, exceptions or release.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "from",
          "arg": "<result.json>",
          "description": "Saved scan result the task reads.",
          "default": "required with a model key"
        },
        {
          "name": "model",
          "arg": "<id>",
          "description": "Model id; auto routes triage to claude-haiku-5-5 and every other task to claude-opus-5-5. Required with --provider.",
          "default": "auto"
        },
        {
          "name": "provider",
          "arg": "<kind>",
          "description": "anthropic, openai, azure, bedrock, google, cloudflare, vercel, openrouter, ollama or compatible (alias openai-compatible): the same providers as Keryn Web's model connectors.",
          "default": "Anthropic with ANTHROPIC_API_KEY or ~/.config/keryn/*.env"
        },
        {
          "name": "base-url",
          "arg": "<url>",
          "description": "Address of an ollama or compatible endpoint; https, or http for localhost.",
          "default": "ollama: http://localhost:11434/v1"
        },
        {
          "name": "key-env",
          "arg": "<NAME>",
          "description": "Environment variable that holds the key; the key is never printed.",
          "default": "the provider's usual variable, none for ollama"
        },
        {
          "name": "resource",
          "arg": "<name>",
          "description": "Azure OpenAI resource name.",
          "default": "none"
        },
        {
          "name": "region",
          "arg": "<name>",
          "description": "Amazon Bedrock region.",
          "default": "none"
        },
        {
          "name": "account",
          "arg": "<id>",
          "description": "Cloudflare account id.",
          "default": "none"
        },
        {
          "name": "gateway",
          "arg": "<name>",
          "description": "Cloudflare AI Gateway name.",
          "default": "default"
        },
        {
          "name": "recorded",
          "description": "Show the recorded example instead of calling a model (the default when no key is found).",
          "default": "off"
        },
        {
          "name": "with-code",
          "description": "Triage: send redacted code excerpts; refused unless --visibility public and cloud.sharing is not off (#188), whatever the provider: a private repository is triaged without code.",
          "default": "off"
        },
        {
          "name": "visibility",
          "arg": "<public|private>",
          "description": "Repository visibility; unknown is treated as private and sends no code.",
          "default": "unknown"
        },
        {
          "name": "approve",
          "arg": "<ids|all>",
          "description": "Exceptions: the proposals a person approves (finding ids or their first characters).",
          "default": "none"
        },
        {
          "name": "write",
          "description": "Exceptions: record the approved drafts in .keryn/decisions.yml as git user.email; refuses in CI.",
          "default": "off"
        },
        {
          "name": "owner",
          "arg": "<name>",
          "description": "Exceptions: owner of the drafts.",
          "default": "the approving person"
        },
        {
          "name": "limit",
          "arg": "<n>",
          "description": "Triage: how many findings to send.",
          "default": "40"
        },
        {
          "name": "json",
          "arg": "<file|->",
          "description": "Write the run as JSON.",
          "default": "none"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn ai release --from result.json",
          "note": "The release decision, then the model's advice beside it."
        },
        {
          "command": "keryn ai exceptions --from result.json --approve 3f2a9c --write",
          "note": "Record one approved exception draft in .keryn/decisions.yml."
        }
      ],
      "exit": {
        "0": "proposals shown (never a gate)",
        "2": "bad usage, unreadable result, or --with-code not allowed by the sharing setting"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "explain",
      "summary": "a rule's message, severity, confidence, edge, CWE/OWASP/NIST, remediation, references (offline)",
      "usage": "keryn explain <rule-id> [--json] [--rules <file|bundled:pack>]\n       keryn explain <fingerprint-or-rule-id> --from <result.json> [--json]",
      "args": [
        {
          "name": "rule-id",
          "description": "Rule ID, or with --from a finding fingerprint or rule ID. A matching fingerprint takes precedence.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "from",
          "arg": "<result.json>",
          "description": "Explain a saved result without running analysis. Requires a regular result file no larger than 32 MiB. Cannot be combined with --rules.",
          "default": "explain the rule only"
        },
        {
          "name": "rules",
          "arg": "<file|bundled:pack>",
          "description": "Comma-separated local files or bundled packs. The first source containing the rule ID wins.",
          "default": "the bundled rules"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn explain keryn.agentclient.codex-sandbox-full-access",
          "note": "What the rule says, its edge, CWE and remediation."
        },
        {
          "command": "keryn explain keryn.agentclient.codex-sandbox-full-access --from result.json --json",
          "note": "Every saved occurrence with proof and flow."
        }
      ],
      "exit": {
        "0": "explained or help shown",
        "2": "unknown selector, invalid input or bad usage"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "controls",
      "summary": "findings mapped to OWASP LLM/Agentic, MITRE ATLAS, NIST AI RMF, ISO 42001, EU AI Act, NIST 800-53, ISO 27001, CWE",
      "usage": "keryn controls <result.json> [--json] [--framework <id>]",
      "args": [
        {
          "name": "result.json",
          "description": "A saved scan result (keryn scan . --json result.json).",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "framework",
          "arg": "<id>",
          "description": "List every control of one framework: owasp-llm, owasp-agentic, mitre-atlas, nist-ai-rmf, iso-42001, eu-ai-act, nist-800-53, iso-27001, cwe.",
          "default": "all frameworks, summarised",
          "commands": [
            "controls"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn controls result.json",
          "note": "Control-by-control status: findings, clear or not tested."
        },
        {
          "command": "keryn controls result.json --framework owasp-llm",
          "note": "Every OWASP LLM control."
        }
      ],
      "exit": {
        "0": "mapped",
        "2": "unreadable or not a Keryn result"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "posture",
      "summary": "what the scan pre-fills in the AI product security posture assessment",
      "usage": "keryn posture <result.json> [--json]",
      "args": [
        {
          "name": "result.json",
          "description": "A saved scan result.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn posture result.json --json",
          "note": "Inferred context and suggested answers as JSON."
        }
      ],
      "exit": {
        "0": "ok",
        "2": "unreadable or not a Keryn result"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "handoff",
      "summary": "hand-off report: gaps | evidence | tools | posture (one self-contained HTML file)",
      "usage": "keryn handoff <gaps|evidence|tools|posture> [result.json] [--answers <posture.json>] [--root <dir>] [-o <file.html>]",
      "args": [
        {
          "name": "kind",
          "description": "gaps, evidence, tools or posture.",
          "required": true
        },
        {
          "name": "result.json",
          "description": "A saved scan result. Optional for posture when --answers is given.",
          "required": false
        }
      ],
      "flags": [
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "answers",
          "arg": "<posture.json>",
          "description": "Posture answers ({mode, context, answers}) laid over the scan's suggestions.",
          "default": "none",
          "commands": [
            "handoff"
          ]
        },
        {
          "name": "root",
          "arg": "<dir>",
          "description": "Folder holding .keryn/decisions.yml and .keryn/scope.yml, read for the release decision.",
          "default": "the current folder",
          "commands": [
            "handoff"
          ]
        },
        {
          "name": "out",
          "short": "o",
          "arg": "<file.html>",
          "description": "Write the report here. With it, evidence also writes <file>.openvex.json beside it.",
          "default": "stdout",
          "commands": [
            "handoff"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn handoff gaps result.json -o gaps.html",
          "note": "Control gap assessment as one HTML file."
        },
        {
          "command": "keryn handoff evidence result.json --root . -o evidence.html",
          "note": "Evidence pack with the release decision and an OpenVEX file."
        }
      ],
      "exit": {
        "0": "written",
        "2": "bad usage"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "docs",
      "summary": "offline docs: command help, exit codes, formats, the eight edge kinds",
      "usage": "keryn docs [topic] [--list] [--json]",
      "args": [
        {
          "name": "topic",
          "description": "A page id or a unique prefix.",
          "required": false
        }
      ],
      "flags": [
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "list",
          "description": "List the pages of the offline docs pack.",
          "default": "off"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn docs --list",
          "note": "List the pages."
        },
        {
          "command": "keryn docs exit-codes",
          "note": "Print one page, verified against the pack's sha256 manifest."
        }
      ],
      "exit": {
        "0": "printed",
        "2": "unknown topic or unreadable pack"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": [
        "KERYN_DOCS_PACK"
      ]
    },
    {
      "path": "runtime init",
      "summary": "copy the Keryn Runtime agent (IAST, RASP, request inspection) into an application and wire it in",
      "usage": "keryn runtime init [dir] [--app <id>] [--dry-run] [--json]",
      "args": [
        {
          "name": "dir",
          "description": "The application's directory. Default: the current directory.",
          "required": false
        }
      ],
      "flags": [
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "app",
          "arg": "<id>",
          "description": "Application id written into the agent's settings and its reports.",
          "default": "the id in .keryn/application.yml, else the package.json name, else the folder name",
          "commands": [
            "init",
            "check"
          ]
        },
        {
          "name": "dry-run",
          "description": "Show what would be copied and wired; write nothing.",
          "default": "off",
          "commands": [
            "init"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn runtime init --dry-run",
          "note": "Show what would be copied and wired in this directory; write nothing."
        },
        {
          "command": "keryn runtime init apps/api --app api",
          "note": "Install into one application of a repository, naming it in reports."
        }
      ],
      "exit": {
        "0": "installed, or the plan was printed",
        "1": "no supported entry point was found",
        "2": "not a directory, bad usage, or the agent inside the CLI failed its checksum"
      },
      "notes": [
        "Supabase Edge Functions, Cloudflare Workers and Node are wired completely. For Vercel and Netlify handlers the agent is copied and the lines to add are printed.",
        "Nothing the installer adds changes behaviour until a KERYN_RUNTIME_* variable is set in the application's environment."
      ],
      "runsIn": "keryn",
      "environment": [
        "KERYN_RUNTIME_PACK"
      ]
    },
    {
      "path": "runtime check",
      "summary": "verify an installed Keryn Runtime agent: the pinned copy is unmodified and the entry points are wired",
      "usage": "keryn runtime check [dir] [--app <id>] [--json]",
      "args": [
        {
          "name": "dir",
          "description": "The application's directory. Default: the current directory.",
          "required": false
        }
      ],
      "flags": [
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "app",
          "arg": "<id>",
          "description": "Application id written into the agent's settings and its reports.",
          "default": "the id in .keryn/application.yml, else the package.json name, else the folder name",
          "commands": [
            "init",
            "check"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn runtime check",
          "note": "In CI: fail when the pinned copy was edited or an entry point lost its wiring."
        }
      ],
      "exit": {
        "0": "the copies match their manifests and the entry points are wired",
        "1": "a copy was edited, is missing, or an entry point is not wired",
        "2": "not a directory or bad usage"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": [
        "KERYN_RUNTIME_PACK"
      ]
    },
    {
      "path": "runtime report",
      "summary": "turn the Keryn Runtime agent's events into findings, protection decisions and coverage",
      "usage": "keryn runtime report <events.jsonl | log export> <out-dir> [--declared <ops.json>] [--json]",
      "args": [
        {
          "name": "events",
          "description": "The agent's JSONL file (KERYN_RUNTIME_REPORT=file:<path>) or a platform log export containing keryn.rt lines.",
          "required": true
        },
        {
          "name": "out-dir",
          "description": "Directory for summary.md, findings.json and analysis.json.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "declared",
          "arg": "<ops.json>",
          "description": "JSON object of function name to the operation names it is meant to serve; operations seen but not listed are reported.",
          "default": "none",
          "commands": [
            "report"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn runtime report keryn-events.jsonl keryn-report",
          "note": "Build the report from a test run's events."
        }
      ],
      "exit": {
        "0": "report written",
        "2": "unreadable input, or no Keryn Runtime events in it"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": [
        "KERYN_RUNTIME_PACK"
      ]
    },
    {
      "path": "import",
      "summary": "third-party scanner report (Semgrep, Trivy, SARIF, gitleaks, ZAP, ...) -> findings, outputs, gate",
      "usage": "keryn import <report-file | capture> [--parser <id>] [--scan-type <name>] [options]\n       keryn import --list\n       keryn import <capture.har> [options]",
      "args": [
        {
          "name": "report-file",
          "description": "A scanner report, or a HAR/Burp/ZAP capture for the passive web rules.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "parser",
          "arg": "<id>",
          "description": "Report format to read. See --list for the supported ids.",
          "default": "detected from the file"
        },
        {
          "name": "scan-type",
          "arg": "<name>",
          "description": "Scan type name that disambiguates formats which share a file shape.",
          "default": "detected"
        },
        {
          "name": "list",
          "description": "List the supported report formats and exit.",
          "default": "off"
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn import semgrep.json --sarif keryn.sarif",
          "note": "Gate and convert a Semgrep report."
        },
        {
          "command": "keryn import --list",
          "note": "Show every supported format."
        },
        {
          "command": "keryn import traffic.har --fail-on warning",
          "note": "Run the passive web rules over captured traffic."
        }
      ],
      "exit": {
        "0": "pass: nothing at or above --fail-on, coverage complete",
        "1": "violations: findings at or above --fail-on, or a policy violation",
        "2": "usage or configuration error",
        "3": "coverage incomplete: a rule was unsupported, partial or timed out (--allow-incomplete opts out)",
        "4": "internal error or timeout",
        "10": "pass with warnings (only with --exit-warn)"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "import runtime",
      "summary": "decisions and request-filter matches a Keryn Runtime agent reported (refused, flagged in shadow mode) -> findings, outputs, gate",
      "usage": "keryn import runtime <events.jsonl | log export> [options]",
      "args": [
        {
          "name": "events.jsonl",
          "description": "keryn.dev/runtime-observations/v1 batches, one per line, or a platform log export whose lines carry them.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "parser",
          "arg": "<id>",
          "description": "Report format to read. See --list for the supported ids.",
          "default": "detected from the file"
        },
        {
          "name": "scan-type",
          "arg": "<name>",
          "description": "Scan type name that disambiguates formats which share a file shape.",
          "default": "detected"
        },
        {
          "name": "list",
          "description": "List the supported report formats and exit.",
          "default": "off"
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn import runtime events.jsonl --json runtime/result.json --fail-on none",
          "note": "Read the decisions and request-filter matches a Keryn Runtime agent reported; pass the directory to keryn ledger build."
        }
      ],
      "exit": {
        "0": "pass: nothing at or above --fail-on, coverage complete",
        "1": "violations: findings at or above --fail-on, or a policy violation",
        "2": "usage or configuration error",
        "3": "coverage incomplete: a rule was unsupported, partial or timed out (--allow-incomplete opts out)",
        "4": "internal error or timeout",
        "10": "pass with warnings (only with --exit-warn)"
      },
      "notes": [
        "RASP decisions are ERROR findings and gate like a scan; request-filter (Edge) matches are INFO and gate only with --fail-on info.",
        "Exit 3 when a batch is incomplete, events were dropped, or a decision chain is broken or has gaps."
      ],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "init",
      "summary": "write .keryn.yml and .keryn/policy.yml",
      "usage": "keryn init [--force]",
      "args": [],
      "flags": [
        {
          "name": "force",
          "description": "Overwrite existing .keryn.yml and .keryn/policy.yml.",
          "default": "off"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn init",
          "note": "Write the starter configuration; refuses to overwrite."
        }
      ],
      "exit": {
        "0": "written",
        "2": "a file exists and --force was not given"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "cache clear",
      "summary": "delete everything the rescan cache holds",
      "usage": "keryn cache clear",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn cache clear",
          "note": "Free the cache."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error or unreadable input"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": [
        "KERYN_CACHE_DIR",
        "KERYN_CACHE_MAX_MB",
        "KERYN_NO_CACHE"
      ]
    },
    {
      "path": "cache stats",
      "summary": "how many entries and how many bytes the rescan cache holds",
      "usage": "keryn cache stats",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn cache stats",
          "note": "Entries and megabytes."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error or unreadable input"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": [
        "KERYN_CACHE_DIR",
        "KERYN_CACHE_MAX_MB",
        "KERYN_NO_CACHE"
      ]
    },
    {
      "path": "cache path",
      "summary": "the rescan cache directory",
      "usage": "keryn cache path",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn cache path",
          "note": "Print the directory (KERYN_CACHE_DIR overrides it)."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error or unreadable input"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": [
        "KERYN_CACHE_DIR",
        "KERYN_CACHE_MAX_MB",
        "KERYN_NO_CACHE"
      ]
    },
    {
      "path": "login",
      "summary": "sign this machine in to your organization (device code); release builds need it to scan",
      "usage": "keryn login [--server <url>] [--name <name>]",
      "args": [],
      "flags": [
        {
          "name": "server",
          "arg": "<url>",
          "description": "The Keryn service to sign in to.",
          "default": "https://api.keryn.app",
          "commands": [
            "login"
          ],
          "env": [
            "KERYN_SERVER"
          ]
        },
        {
          "name": "name",
          "arg": "<name>",
          "description": "The device name your organization sees in its device list.",
          "default": "this machine's host name",
          "commands": [
            "login"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn login",
          "note": "Open the link it prints, confirm the code, and the CLI is bound to your organization, team and account."
        }
      ],
      "exit": {
        "0": "signed in, entitlement stored",
        "1": "sign-in failed or the code expired",
        "2": "usage error"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": [
        "KERYN_CONFIG_DIR",
        "KERYN_SERVER",
        "KERYN_TOKEN",
        "KERYN_LICENCE_FILE",
        "KERYN_MACHINE_ID",
        "KERYN_ENTITLEMENT_DEV_KEYS"
      ]
    },
    {
      "path": "logout",
      "summary": "forget the sign-in on this machine",
      "usage": "keryn logout",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn logout",
          "note": "Removes the device token, the cached entitlement and queued usage, then asks Keryn Cloud to end the device so a copy of the token stops working; the device key stays. Offline, it still signs out here."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error or unreadable input"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": [
        "KERYN_CONFIG_DIR",
        "KERYN_SERVER",
        "KERYN_TOKEN",
        "KERYN_LICENCE_FILE",
        "KERYN_MACHINE_ID",
        "KERYN_ENTITLEMENT_DEV_KEYS"
      ]
    },
    {
      "path": "whoami",
      "summary": "organization, team, account, plan, features and entitlement expiry",
      "usage": "keryn whoami [--json]",
      "args": [],
      "flags": [
        {
          "name": "json",
          "description": "Machine-readable output.",
          "default": "off",
          "commands": [
            "whoami",
            "licence status",
            "licence usage",
            "update"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn whoami --json",
          "note": "Works offline from the cached entitlement; refreshes it when signed in and online."
        }
      ],
      "exit": {
        "0": "an entitlement or licence is valid (possibly in its offline grace period)",
        "1": "none, or it cannot be used",
        "2": "usage error"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": [
        "KERYN_CONFIG_DIR",
        "KERYN_SERVER",
        "KERYN_TOKEN",
        "KERYN_LICENCE_FILE",
        "KERYN_MACHINE_ID",
        "KERYN_ENTITLEMENT_DEV_KEYS"
      ]
    },
    {
      "path": "update",
      "summary": "check whether a newer release is available to your organization; reports only, nothing is downloaded or installed",
      "usage": "keryn update [--json]",
      "args": [],
      "flags": [
        {
          "name": "json",
          "description": "Machine-readable output.",
          "default": "off",
          "commands": [
            "whoami",
            "licence status",
            "licence usage",
            "update"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn update",
          "note": "Says which release is newest and prints the installer command that verifies the release signature before installing."
        }
      ],
      "exit": {
        "0": "checked: up to date, or a newer release is named",
        "1": "could not check (not signed in, or the service could not be reached)",
        "2": "usage error"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": [
        "KERYN_CONFIG_DIR",
        "KERYN_SERVER",
        "KERYN_TOKEN",
        "KERYN_LICENCE_FILE",
        "KERYN_MACHINE_ID",
        "KERYN_ENTITLEMENT_DEV_KEYS"
      ]
    },
    {
      "path": "licence status",
      "summary": "the offline licence on this machine (contract customers)",
      "usage": "keryn licence status [--json]",
      "args": [],
      "flags": [
        {
          "name": "json",
          "description": "Machine-readable output.",
          "default": "off",
          "commands": [
            "whoami",
            "licence status",
            "licence usage",
            "update"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn licence status",
          "note": "Organization, plan, contract and expiry of the installed licence."
        }
      ],
      "exit": {
        "0": "a valid licence is installed",
        "1": "no licence, or it cannot be used here",
        "2": "usage error"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": [
        "KERYN_CONFIG_DIR",
        "KERYN_SERVER",
        "KERYN_TOKEN",
        "KERYN_LICENCE_FILE",
        "KERYN_MACHINE_ID",
        "KERYN_ENTITLEMENT_DEV_KEYS"
      ]
    },
    {
      "path": "licence request",
      "summary": "write an offline-licence request: this machine's fingerprint and device key, no secret",
      "usage": "keryn licence request [--org <id>] [--out <file>]",
      "args": [],
      "flags": [
        {
          "name": "org",
          "arg": "<id>",
          "description": "The organization the licence is requested for.",
          "default": "unset",
          "commands": [
            "licence request"
          ]
        },
        {
          "name": "out",
          "arg": "<file>",
          "description": "Write the licence request, or the usage report, to a file instead of stdout.",
          "default": "stdout",
          "commands": [
            "licence request",
            "licence usage"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn licence request --org org_123 --out request.json",
          "note": "Send request.json to your Keryn contact; the licence they return runs on this machine only."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error or unreadable input"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": [
        "KERYN_CONFIG_DIR",
        "KERYN_SERVER",
        "KERYN_TOKEN",
        "KERYN_LICENCE_FILE",
        "KERYN_MACHINE_ID",
        "KERYN_ENTITLEMENT_DEV_KEYS"
      ]
    },
    {
      "path": "licence install",
      "summary": "verify and install an offline licence (signed, bound to this machine, no phone-home)",
      "usage": "keryn licence install <file>",
      "args": [
        {
          "name": "file",
          "description": "The licence file Keryn issued.",
          "required": true
        }
      ],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn licence install acme.kl",
          "note": "Refused when the licence names other machines, is expired, or was not signed by Keryn."
        }
      ],
      "exit": {
        "0": "installed",
        "1": "refused: not valid on this machine",
        "2": "usage error"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": [
        "KERYN_CONFIG_DIR",
        "KERYN_SERVER",
        "KERYN_TOKEN",
        "KERYN_LICENCE_FILE",
        "KERYN_MACHINE_ID",
        "KERYN_ENTITLEMENT_DEV_KEYS"
      ]
    },
    {
      "path": "licence usage",
      "summary": "the usage counted on this machine under its offline licence, for a usage-priced contract's true-up; nothing is sent",
      "usage": "keryn licence usage [--from <YYYY-MM>] [--to <YYYY-MM>] [--out <file>] [--json]",
      "args": [],
      "flags": [
        {
          "name": "json",
          "description": "Machine-readable output.",
          "default": "off",
          "commands": [
            "whoami",
            "licence status",
            "licence usage",
            "update"
          ]
        },
        {
          "name": "out",
          "arg": "<file>",
          "description": "Write the licence request, or the usage report, to a file instead of stdout.",
          "default": "stdout",
          "commands": [
            "licence request",
            "licence usage"
          ]
        },
        {
          "name": "from",
          "arg": "<YYYY-MM>",
          "description": "First month of the usage report.",
          "default": "the first month with usage",
          "commands": [
            "licence usage"
          ]
        },
        {
          "name": "to",
          "arg": "<YYYY-MM>",
          "description": "Last month of the usage report.",
          "default": "the current month",
          "commands": [
            "licence usage"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn licence usage --from 2026-01 --to 2026-12 --out usage-2026.json",
          "note": "Writes counts per month (command, size class, outcome, Deep) with a digest. No path, repository name or finding. Send the file to your Keryn contact if your contract prices by usage."
        }
      ],
      "exit": {
        "0": "the report was printed or written",
        "1": "no usable offline licence on this machine",
        "2": "usage error"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": [
        "KERYN_CONFIG_DIR",
        "KERYN_SERVER",
        "KERYN_TOKEN",
        "KERYN_LICENCE_FILE",
        "KERYN_MACHINE_ID",
        "KERYN_ENTITLEMENT_DEV_KEYS"
      ]
    },
    {
      "path": "lsp",
      "summary": "Language Server (https://keryn.dev/docs/reference/lsp/)",
      "usage": "keryn lsp --stdio",
      "args": [],
      "flags": [
        {
          "name": "stdio",
          "description": "Speak the Language Server Protocol on stdin and stdout. The only transport.",
          "default": "required"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn lsp --stdio",
          "note": "Started by an editor plugin, not by hand."
        }
      ],
      "exit": {
        "0": "client closed the session",
        "2": "usage error"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "version",
      "summary": "print the version",
      "usage": "keryn version [--json]",
      "args": [],
      "flags": [
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn version --json",
          "note": "Version, engine and build provenance as JSON."
        }
      ],
      "exit": {
        "0": "printed",
        "2": "unknown flag"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "decide",
      "summary": "release decision (Go / Go with accepted risk / Hold) from a scan and .keryn/decisions.yml; exit 1 on Hold",
      "usage": "keryn decide [path] [--from <result.json>] [options]",
      "args": [
        {
          "name": "path",
          "description": "Folder to scan and decide.",
          "required": false
        }
      ],
      "flags": [
        {
          "name": "from",
          "arg": "<result.json>",
          "description": "Decide from a saved result instead of scanning.",
          "default": "scan the path",
          "commands": [
            "decide",
            "decide sign",
            "decide migrate",
            "decide export",
            "export"
          ]
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn decide .",
          "note": "Go, Go with accepted risk, or Hold."
        },
        {
          "command": "keryn decide . --from result.json --fail-on warning",
          "note": "Decide from a saved scan."
        }
      ],
      "exit": {
        "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)"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "decide sign",
      "summary": "a person signs a Go: appends a hash-chained record to .keryn/releases.jsonl (never from CI)",
      "usage": "keryn decide sign [path] [--from <result.json>] [options]",
      "args": [
        {
          "name": "path",
          "description": "Folder to decide.",
          "required": false
        }
      ],
      "flags": [
        {
          "name": "from",
          "arg": "<result.json>",
          "description": "Decide from a saved result instead of scanning.",
          "default": "scan the path",
          "commands": [
            "decide",
            "decide sign",
            "decide migrate",
            "decide export",
            "export"
          ]
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn decide sign .",
          "note": "Record the signed Go under your git user.email."
        }
      ],
      "exit": {
        "0": "signed",
        "1": "Hold, or CI is set: refused",
        "2": "usage or configuration error"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "decide key",
      "summary": "your release-signing key and its entry for release.signers in the policy (never from CI)",
      "usage": "keryn decide key [--login <github login>] [--json]",
      "args": [],
      "flags": [
        {
          "name": "login",
          "arg": "<github login>",
          "description": "The GitHub login the key belongs to, written into the printed release.signers entry.",
          "default": "unset",
          "commands": [
            "decide key"
          ]
        },
        {
          "name": "json",
          "description": "Machine-readable output.",
          "default": "off",
          "commands": [
            "decide key"
          ]
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn decide key --login octocat",
          "note": "Creates the key on first use and prints the release.signers entry; only the public half is shown."
        }
      ],
      "exit": {
        "0": "printed",
        "2": "usage error, or CI is set: refused"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "decide migrate",
      "summary": "suppress: entries and policy waivers -> .keryn/decisions.yml (--write, --remove-legacy)",
      "usage": "keryn decide migrate [path] [--write] [--remove-legacy] [--from <result.json>] [options]",
      "args": [
        {
          "name": "path",
          "description": "Folder to migrate.",
          "required": false
        }
      ],
      "flags": [
        {
          "name": "from",
          "arg": "<result.json>",
          "description": "Decide from a saved result instead of scanning.",
          "default": "scan the path",
          "commands": [
            "decide",
            "decide sign",
            "decide migrate",
            "decide export",
            "export"
          ]
        },
        {
          "name": "write",
          "description": "Create or extend .keryn/decisions.yml with the decisions migrate would add. Without it, migrate only previews.",
          "default": "off",
          "commands": [
            "decide migrate"
          ]
        },
        {
          "name": "remove-legacy",
          "description": "With --write: remove the suppress: and waivers: entries decisions.yml now covers. Without --write it is a preview.",
          "default": "off",
          "commands": [
            "decide migrate"
          ]
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn decide migrate .",
          "note": "Preview the decisions it would add."
        },
        {
          "command": "keryn decide migrate . --write --remove-legacy",
          "note": "Write them and drop the covered legacy entries."
        }
      ],
      "exit": {
        "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)"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "decide export",
      "summary": "open GitHub (--github) or GitLab (--gitlab) issues for the Holds, one per chain or chokepoint (--dry-run, --record)",
      "usage": "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]",
      "args": [
        {
          "name": "path",
          "description": "Folder to decide.",
          "required": false
        }
      ],
      "flags": [
        {
          "name": "from",
          "arg": "<result.json>",
          "description": "Decide from a saved result instead of scanning.",
          "default": "scan the path",
          "commands": [
            "decide",
            "decide sign",
            "decide migrate",
            "decide export",
            "export"
          ]
        },
        {
          "name": "github",
          "arg": "<owner/repo>",
          "description": "Open one GitHub issue per chain or chokepoint for the open Holds. Token from GITHUB_TOKEN.",
          "default": "none",
          "commands": [
            "decide export"
          ],
          "env": [
            "GITHUB_TOKEN"
          ]
        },
        {
          "name": "gitlab",
          "arg": "<project>",
          "description": "Open GitLab issues for the open Holds. Token from GITLAB_TOKEN.",
          "default": "none",
          "commands": [
            "decide export"
          ],
          "env": [
            "GITLAB_TOKEN"
          ]
        },
        {
          "name": "github-url",
          "arg": "<api-url>",
          "description": "GitHub Enterprise API base. Must be https, or http on localhost.",
          "default": "https://api.github.com",
          "commands": [
            "decide export"
          ]
        },
        {
          "name": "gitlab-url",
          "arg": "<base-url>",
          "description": "Self-managed GitLab base URL. Must be https, or http on localhost.",
          "default": "https://gitlab.com",
          "commands": [
            "decide export"
          ]
        },
        {
          "name": "dry-run",
          "description": "Print the issue payloads as JSON; needs no token and no network.",
          "default": "off",
          "commands": [
            "decide export"
          ]
        },
        {
          "name": "record",
          "description": "Also add under_investigation decisions, with decided_by from git config user.email, for findings that have none.",
          "default": "off",
          "commands": [
            "decide export"
          ]
        },
        {
          "name": "label",
          "arg": "<a,b>",
          "description": "Labels to put on the created issues.",
          "default": "none",
          "commands": [
            "decide export"
          ]
        },
        {
          "name": "format",
          "arg": "openvex|cyclonedx",
          "description": "VEX output format.",
          "default": "openvex",
          "commands": [
            "export"
          ]
        },
        {
          "name": "vex",
          "arg": "<file>",
          "description": "Write .keryn/decisions.yml as a VEX document: OpenVEX 0.2.0, or CycloneDX 1.6 VEX with --format cyclonedx. `-` is stdout.",
          "default": "required",
          "commands": [
            "export"
          ]
        },
        {
          "name": "product",
          "arg": "<purl|url>",
          "description": "Product identifier in the VEX document.",
          "default": "the git remote as a purl, else pkg:generic/<folder>",
          "commands": [
            "export"
          ]
        },
        {
          "name": "author",
          "arg": "<name>",
          "description": "Author recorded in the VEX document.",
          "default": "the git user",
          "commands": [
            "export"
          ]
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn decide export . --github acme/app --dry-run",
          "note": "Print the issues it would open."
        },
        {
          "command": "GITHUB_TOKEN=... keryn decide export . --github acme/app --label security",
          "note": "Open them; nothing that exists or is ticketed is created twice."
        }
      ],
      "exit": {
        "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)"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "export",
      "summary": ".keryn/decisions.yml as an OpenVEX 0.2.0 or CycloneDX 1.6 VEX document",
      "usage": "keryn export --vex <file> [--format openvex|cyclonedx] [path] [--product <purl|url>] [--author <name>] [--timestamp <iso>] [--from <result.json>]",
      "args": [
        {
          "name": "path",
          "description": "Folder holding .keryn/decisions.yml.",
          "required": false
        }
      ],
      "flags": [
        {
          "name": "from",
          "arg": "<result.json>",
          "description": "Decide from a saved result instead of scanning.",
          "default": "scan the path",
          "commands": [
            "decide",
            "decide sign",
            "decide migrate",
            "decide export",
            "export"
          ]
        },
        {
          "name": "format",
          "arg": "openvex|cyclonedx",
          "description": "VEX output format.",
          "default": "openvex",
          "commands": [
            "export"
          ]
        },
        {
          "name": "vex",
          "arg": "<file>",
          "description": "Write .keryn/decisions.yml as a VEX document: OpenVEX 0.2.0, or CycloneDX 1.6 VEX with --format cyclonedx. `-` is stdout.",
          "default": "required",
          "commands": [
            "export"
          ]
        },
        {
          "name": "product",
          "arg": "<purl|url>",
          "description": "Product identifier in the VEX document.",
          "default": "the git remote as a purl, else pkg:generic/<folder>",
          "commands": [
            "export"
          ]
        },
        {
          "name": "author",
          "arg": "<name>",
          "description": "Author recorded in the VEX document.",
          "default": "the git user",
          "commands": [
            "export"
          ]
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn export --vex keryn.openvex.json .",
          "note": "Write the decisions as OpenVEX."
        }
      ],
      "exit": {
        "0": "written",
        "2": "usage error or no decisions file"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "trust-graph",
      "summary": "trust graph derived from a repository scan (routes, agents, tools, providers, MCP servers, secrets): JSON for the trust canvas, or a keryn-export/1 file",
      "usage": "keryn trust-graph [path] [--out <file>] [--envelope] [--analyze] [options]",
      "args": [
        {
          "name": "path",
          "description": "Repository folder.",
          "required": false
        }
      ],
      "flags": [
        {
          "name": "out",
          "arg": "<file>",
          "description": "Write the graph here.",
          "default": "stdout"
        },
        {
          "name": "analyze",
          "description": "Lay the graph out and analyse it with the trust-model engine (boundaries, chains, risks); written next to it as <name>.analysis.json.",
          "default": "off"
        },
        {
          "name": "envelope",
          "description": "Write a keryn-export/1 file holding the graph (and the analysis with --analyze) instead of the bare graph.",
          "default": "off"
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn trust-graph . --out graph.json",
          "note": "Graph for the Trust Canvas (#/trust)."
        },
        {
          "command": "keryn trust-graph . --out graph.json --analyze --envelope",
          "note": "Graph plus boundary and chain analysis in one export file."
        }
      ],
      "exit": {
        "0": "written",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "sca malicious",
      "summary": "inspect local package install hooks and published malicious-package coordinates",
      "usage": "keryn sca malicious <directory|package.tar.gz> --out <new-directory> [--base <hook-snapshot.json|directory>] [--online]",
      "args": [
        {
          "name": "target",
          "description": "Local installed package contents or a vendored tarball, never executed.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "fail-on",
          "arg": "error|warning|info|none",
          "description": "Lowest severity that makes the run exit 1.",
          "default": "error"
        },
        {
          "name": "online",
          "description": "Permit advisory requests to OSV.dev (package names and versions only). Without it the installed scanner must have a local advisory database. For sca fix: Allow registry access only for the explicitly requested package manager. Advisory records stay pinned; requires --run-package-manager.",
          "default": "off",
          "commands": [
            "scan",
            "collect",
            "deno",
            "image",
            "malicious",
            "fix"
          ]
        },
        {
          "name": "base",
          "arg": "<inventory.json|hook-snapshot.json|directory>",
          "description": "Earlier inventory, or comparable package hook metadata for malicious inspection.",
          "default": "none",
          "commands": [
            "inventory",
            "malicious"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn sca malicious node_modules --out out/hooks",
          "note": "Inspect available package contents using shipped, dated MAL data."
        }
      ],
      "exit": {
        "0": "pass",
        "1": "findings or a requested change gate",
        "2": "usage error or invalid input",
        "3": "incomplete or unknown completion",
        "4": "execution or normalization failure"
      },
      "notes": [
        "Artifacts are written to --out: raw evidence, run.json, and when parseable result.json, results.sarif and summary.md."
      ],
      "runsIn": "keryn",
      "environment": [
        "GITHUB_TOKEN",
        "GITLAB_TOKEN"
      ]
    },
    {
      "path": "sca fix",
      "summary": "propose direct-dependency patches with pinned comparable scans and optional owned-repository draft PRs",
      "usage": "keryn sca fix [directory] --out <new-directory> [--from <result.json> | --advisories <OSV-array.json>] [--run-package-manager] [--github <owner/repo> | --gitlab <group/project>] [--dry-run | --create-pr]",
      "args": [
        {
          "name": "directory",
          "description": "Source tree copied before analysis; original files stay unchanged.",
          "required": false
        }
      ],
      "flags": [
        {
          "name": "vex",
          "arg": "<local-file>",
          "description": "Consume attributed OpenVEX, CSAF 2.0 VEX or CycloneDX VEX; unknown coverage and independent inventory/SBOM gates remain unchanged.",
          "default": "none",
          "repeatable": true,
          "commands": [
            "sca fix",
            "sca image",
            "sca scan",
            "sca import",
            "sca collect",
            "sca inventory",
            "sca assess",
            "sca deno",
            "sca sbom"
          ]
        },
        {
          "name": "vex-product",
          "arg": "<purl|url>",
          "description": "Root product context for --vex subcomponents.",
          "default": "none",
          "commands": [
            "sca fix",
            "sca image",
            "sca scan",
            "sca import",
            "sca collect",
            "sca inventory",
            "sca assess",
            "sca deno",
            "sca sbom"
          ]
        },
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "fail-on",
          "arg": "error|warning|info|none",
          "description": "Lowest severity that makes the run exit 1.",
          "default": "error"
        },
        {
          "name": "timeout",
          "arg": "<seconds>",
          "description": "Time limit for the scanner run. Maximum 3600. For sca fix: Per-scan analysis time limit. Manager executions have a separate fixed timeout.",
          "default": "300",
          "commands": [
            "scan",
            "collect",
            "fix"
          ]
        },
        {
          "name": "online",
          "description": "Permit advisory requests to OSV.dev (package names and versions only). Without it the installed scanner must have a local advisory database. For sca fix: Allow registry access only for the explicitly requested package manager. Advisory records stay pinned; requires --run-package-manager.",
          "default": "off",
          "commands": [
            "scan",
            "collect",
            "deno",
            "image",
            "malicious",
            "fix"
          ]
        },
        {
          "name": "config",
          "arg": "<.keryn.yml>",
          "description": "Configuration used for dependency roles. For sca fix: Configuration for the comparison scope. PR jobs use trusted-base configuration.",
          "default": "<repo-root>/.keryn.yml, else ./.keryn.yml",
          "commands": [
            "scan",
            "fix"
          ]
        },
        {
          "name": "no-config",
          "description": "Use the default roles instead of any .keryn.yml. For sca fix: Use defaults instead of local configuration.",
          "default": "off",
          "commands": [
            "scan",
            "fix"
          ]
        },
        {
          "name": "from",
          "arg": "<result.json | directory | https URL>",
          "description": "sca fix: a result.json whose pinned advisory records are used (a fresh baseline of the current source is always scanned). sca db update: where the advisory exports are, a folder holding the per-ecosystem exports (<ecosystem>/all.zip), an https address that serves them the same way (the only network call, only in that command), or a signed built snapshot.",
          "default": "sca fix: none; sca db update: required",
          "commands": [
            "fix",
            "db"
          ]
        },
        {
          "name": "run-package-manager",
          "description": "Run fixed npm/Cargo/Go resolution commands in the copied candidate. Scripts disabled; offline unless --online. Pinned requirements need no pip execution.",
          "default": "off",
          "commands": [
            "fix"
          ]
        },
        {
          "name": "github",
          "arg": "<owner/repo>",
          "description": "Plan a fix PR for this checkout origin. Actual creation requires --create-pr and verified personal/org ownership.",
          "default": "none",
          "commands": [
            "fix"
          ],
          "env": [
            "GITHUB_TOKEN"
          ]
        },
        {
          "name": "gitlab",
          "arg": "<group/project>",
          "description": "Plan a fix MR for this checkout origin. Actual creation requires --create-pr and personal/group ownership.",
          "default": "none",
          "commands": [
            "fix"
          ],
          "env": [
            "GITLAB_TOKEN"
          ]
        },
        {
          "name": "github-url",
          "arg": "<api-url>",
          "description": "GitHub Enterprise API base. HTTPS or explicit loopback only.",
          "default": "https://api.github.com",
          "commands": [
            "fix"
          ]
        },
        {
          "name": "gitlab-url",
          "arg": "<base-url>",
          "description": "GitLab instance base URL. HTTPS or explicit loopback only.",
          "default": "https://gitlab.com",
          "commands": [
            "fix"
          ]
        },
        {
          "name": "base-branch",
          "arg": "<branch>",
          "description": "Owned destination branch whose remote SHA must equal the local committed base.",
          "default": "current local branch",
          "commands": [
            "fix"
          ]
        },
        {
          "name": "create-pr",
          "description": "Explicitly create a draft PR/MR after ownership/base/source checks. Never automatic in CI. Third-party write/admin access does not authorize it.",
          "default": "off",
          "commands": [
            "fix"
          ]
        },
        {
          "name": "dry-run",
          "description": "Print the PR payload without a token or any tracker request. Overrides --create-pr.",
          "default": "off",
          "commands": [
            "fix"
          ]
        },
        {
          "name": "rules",
          "arg": "<file|bundled:pack>",
          "description": "Rules loaded once for both comparison scans; the digest is recorded.",
          "default": "bundled:all",
          "commands": [
            "fix"
          ],
          "repeatable": true
        },
        {
          "name": "policy",
          "arg": "<file>",
          "description": "Policy loaded once for both comparison scans. PR jobs use trusted-base policy.",
          "default": "configured policy",
          "commands": [
            "fix"
          ]
        },
        {
          "name": "include",
          "arg": "<glob,...>",
          "description": "Include matching paths in both copied-tree scans.",
          "default": "all supported paths",
          "commands": [
            "fix"
          ],
          "repeatable": true
        },
        {
          "name": "exclude",
          "arg": "<glob,...>",
          "description": "Exclude matching paths from both scans.",
          "default": "none",
          "commands": [
            "fix"
          ],
          "repeatable": true
        },
        {
          "name": "max-files",
          "arg": "<count>",
          "description": "Source scan file limit applied to both scans. Copy limits are recorded separately.",
          "default": "scanner default",
          "commands": [
            "fix"
          ]
        },
        {
          "name": "max-file-size",
          "arg": "<bytes>",
          "description": "Per-file source scan limit applied to both scans.",
          "default": "scanner default",
          "commands": [
            "fix"
          ]
        },
        {
          "name": "timestamp",
          "arg": "<iso|now>",
          "description": "Report timestamp shared by both scans; analysis conditions are frozen once.",
          "default": "deterministic scanner timestamp",
          "commands": [
            "fix"
          ]
        },
        {
          "name": "advisories",
          "arg": "<OSV-record-array.json>",
          "description": "Local OSV record snapshot for image assessment or fix comparison; no advisory network requests.",
          "default": "none; offline inventory remains unknown",
          "commands": [
            "image",
            "fix"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn sca fix . --from result.json --out out/fix",
          "note": "Review the manifest patch and the actual before/after evidence."
        },
        {
          "command": "keryn sca fix . --advisories osv.json --out out/fix --github acme/app --dry-run",
          "note": "Print the planned owned-repository PR payload without a token or network."
        }
      ],
      "exit": {
        "0": "after gate passed within the recorded scope; proposal only",
        "1": "remaining gate findings, including a pending lockfile upgrade",
        "2": "usage or invalid pinned input",
        "3": "unknown, incomplete, manager failure or refused PR; local patch may still be available"
      },
      "notes": [
        "Managers and PR creation are separate explicit opt-ins. Actual PRs require verified personal or organization/group ownership, a clean source and matching origin/base. Never third-party repositories."
      ],
      "runsIn": "keryn",
      "environment": [
        "GITHUB_TOKEN",
        "GITLAB_TOKEN"
      ]
    },
    {
      "path": "sca db",
      "summary": "the offline advisory snapshot that keryn scan and keryn sca image check dependencies against with no network: update builds or installs it, status shows it",
      "usage": "keryn sca db update --from <directory|https URL> [--ecosystems <name,...>] [--check] [--json]\n       keryn sca db status [--json]",
      "args": [
        {
          "name": "update|status",
          "description": "update builds the snapshot from OSV's per-ecosystem exports or installs a signed one; status lists each ecosystem with its record count, source and date.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "fail-on",
          "arg": "error|warning|info|none",
          "description": "Lowest severity that makes the run exit 1.",
          "default": "error"
        },
        {
          "name": "from",
          "arg": "<result.json | directory | https URL>",
          "description": "sca fix: a result.json whose pinned advisory records are used (a fresh baseline of the current source is always scanned). sca db update: where the advisory exports are, a folder holding the per-ecosystem exports (<ecosystem>/all.zip), an https address that serves them the same way (the only network call, only in that command), or a signed built snapshot.",
          "default": "sca fix: none; sca db update: required",
          "commands": [
            "fix",
            "db"
          ]
        },
        {
          "name": "ecosystems",
          "arg": "<name,...>",
          "description": "The exports to build the snapshot from, for example npm,PyPI,Maven. Distribution exports (Debian, Ubuntu, Alpine) are large and are included only when named.",
          "default": "a folder: every export in it; an address: npm, PyPI, Maven, Go, crates.io, RubyGems, NuGet, Packagist",
          "commands": [
            "db"
          ]
        },
        {
          "name": "check",
          "description": "Do everything except install: read, build and verify, then report what would be installed. Nothing is written.",
          "default": "off",
          "commands": [
            "db"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn sca db update --from ./osv-exports",
          "note": "On the machine without a network: build the snapshot from the export files you carried in (npm/all.zip, PyPI/all.zip, ...)."
        },
        {
          "command": "keryn sca db update --from https://osv-vulnerabilities.storage.googleapis.com --ecosystems npm,PyPI",
          "note": "On a connected machine: download the two exports from that address and build the snapshot."
        },
        {
          "command": "keryn sca db status",
          "note": "What dependencies are checked against when there is no network."
        }
      ],
      "exit": {
        "0": "update: installed (or, with --check, would install); status: a snapshot is installed and verifies",
        "2": "usage error, or update refused the snapshot whole (unsigned, altered, truncated, not there): nothing is installed and the previous snapshot stays",
        "3": "status: no snapshot is installed, or it was refused"
      },
      "notes": [
        "A built snapshot that arrives from elsewhere must be signed; one built here from the exports is marked as built on this machine.",
        "The snapshot lives in the user data directory; KERYN_SCA_DB names another directory, and the value off makes scans ignore it."
      ],
      "runsIn": "keryn",
      "environment": [
        "GITHUB_TOKEN",
        "GITLAB_TOKEN"
      ]
    },
    {
      "path": "sca image",
      "summary": "inventory a local OCI layout or Docker archive, or an image read from its registry with --pull, and assess OS and language dependencies",
      "usage": "keryn sca image <oci-layout|docker-archive.tar|registry/repository[:tag|@sha256:digest]> --out <new-directory> [--pull [--platform <os/arch>] [--pull-redirects]] [--advisories <OSV-record-array.json> | --online] [--fail-on error|warning|info|none]",
      "args": [
        {
          "name": "image",
          "description": "Local image layout or archive, or with --pull a registry reference. Never executed; nothing is fetched without --pull.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "vex",
          "arg": "<local-file>",
          "description": "Consume attributed OpenVEX, CSAF 2.0 VEX or CycloneDX VEX; unknown coverage and independent inventory/SBOM gates remain unchanged.",
          "default": "none",
          "repeatable": true,
          "commands": [
            "sca fix",
            "sca image",
            "sca scan",
            "sca import",
            "sca collect",
            "sca inventory",
            "sca assess",
            "sca deno",
            "sca sbom"
          ]
        },
        {
          "name": "vex-product",
          "arg": "<purl|url>",
          "description": "Root product context for --vex subcomponents.",
          "default": "none",
          "commands": [
            "sca fix",
            "sca image",
            "sca scan",
            "sca import",
            "sca collect",
            "sca inventory",
            "sca assess",
            "sca deno",
            "sca sbom"
          ]
        },
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "fail-on",
          "arg": "error|warning|info|none",
          "description": "Lowest severity that makes the run exit 1.",
          "default": "error"
        },
        {
          "name": "online",
          "description": "Permit advisory requests to OSV.dev (package names and versions only). Without it the installed scanner must have a local advisory database. For sca fix: Allow registry access only for the explicitly requested package manager. Advisory records stay pinned; requires --run-package-manager.",
          "default": "off",
          "commands": [
            "scan",
            "collect",
            "deno",
            "image",
            "malicious",
            "fix"
          ]
        },
        {
          "name": "advisories",
          "arg": "<OSV-record-array.json>",
          "description": "Local OSV record snapshot for image assessment or fix comparison; no advisory network requests.",
          "default": "none; offline inventory remains unknown",
          "commands": [
            "image",
            "fix"
          ]
        },
        {
          "name": "pull",
          "description": "Read the image from its registry over HTTPS instead of from a local file: the manifest, then the config and layers by digest, each checked against its digest and size. Only the registry you name and the token endpoint it advertises are contacted. Credentials come from KERYN_REGISTRY_USERNAME and KERYN_REGISTRY_PASSWORD, or KERYN_REGISTRY_TOKEN.",
          "default": "off",
          "commands": [
            "image"
          ]
        },
        {
          "name": "platform",
          "arg": "<os/arch>",
          "description": "With --pull: the platform to read from a multi-architecture image, for example linux/amd64.",
          "default": "the image's only platform; a choice between several is a usage error that lists them",
          "commands": [
            "image"
          ]
        },
        {
          "name": "pull-redirects",
          "description": "With --pull: also follow a layer download that the registry redirects to its storage host (HTTPS only, without the registry credentials). The host is recorded.",
          "default": "off",
          "commands": [
            "image"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn sca image image.tar --out out/image --advisories osv.json",
          "note": "Assess installed packages using a local advisory snapshot."
        },
        {
          "command": "keryn sca image registry.example.com/team/app@sha256:6f1c0f3b8a4d2e5c9b7a1d0e3f2c4b5a6978d0e1f2a3b4c5d6e7f8091a2b3c4d --pull --platform linux/amd64 --out out/image --online",
          "note": "Read the pushed image from its registry, with no daemon, and check it against OSV.dev."
        }
      ],
      "exit": {
        "0": "pass",
        "1": "findings or a requested change gate",
        "2": "usage error or invalid input",
        "3": "incomplete or unknown completion",
        "4": "execution or normalization failure"
      },
      "notes": [
        "Artifacts are written to --out: raw evidence, run.json, and when parseable result.json, results.sarif and summary.md."
      ],
      "runsIn": "keryn",
      "environment": [
        "GITHUB_TOKEN",
        "GITLAB_TOKEN"
      ]
    },
    {
      "path": "sca collect",
      "summary": "OSV-Scanner execution, SCA report intake with completion receipts, complete-package inventory, offline advisory assessment",
      "usage": "keryn sca collect <target> --out <new-directory> [--context <deployment.json>|--bindings <bindings.json>] [--snapshot <snapshot.json>] [--online]",
      "args": [
        {
          "name": "target",
          "description": "Directory, lockfile or SBOM to collect packages and advisories for.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "vex",
          "arg": "<local-file>",
          "description": "Consume attributed OpenVEX, CSAF 2.0 VEX or CycloneDX VEX; unknown coverage and independent inventory/SBOM gates remain unchanged.",
          "default": "none",
          "repeatable": true,
          "commands": [
            "sca fix",
            "sca image",
            "sca scan",
            "sca import",
            "sca collect",
            "sca inventory",
            "sca assess",
            "sca deno",
            "sca sbom"
          ]
        },
        {
          "name": "vex-product",
          "arg": "<purl|url>",
          "description": "Root product context for --vex subcomponents.",
          "default": "none",
          "commands": [
            "sca fix",
            "sca image",
            "sca scan",
            "sca import",
            "sca collect",
            "sca inventory",
            "sca assess",
            "sca deno",
            "sca sbom"
          ]
        },
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "fail-on",
          "arg": "error|warning|info|none",
          "description": "Lowest severity that makes the run exit 1.",
          "default": "error"
        },
        {
          "name": "executable",
          "arg": "<path>",
          "description": "The scanner binary to run: osv-scanner for sca, the ZAP launcher for dast. Nothing is installed automatically.",
          "default": "found on PATH",
          "commands": [
            "scan",
            "collect"
          ]
        },
        {
          "name": "timeout",
          "arg": "<seconds>",
          "description": "Time limit for the scanner run. Maximum 3600. For sca fix: Per-scan analysis time limit. Manager executions have a separate fixed timeout.",
          "default": "300",
          "commands": [
            "scan",
            "collect",
            "fix"
          ]
        },
        {
          "name": "online",
          "description": "Permit advisory requests to OSV.dev (package names and versions only). Without it the installed scanner must have a local advisory database. For sca fix: Allow registry access only for the explicitly requested package manager. Advisory records stay pinned; requires --run-package-manager.",
          "default": "off",
          "commands": [
            "scan",
            "collect",
            "deno",
            "image",
            "malicious",
            "fix"
          ]
        },
        {
          "name": "offline",
          "description": "Explicitly stay offline (the default).",
          "default": "off",
          "commands": [
            "scan",
            "collect"
          ]
        },
        {
          "name": "context",
          "arg": "<deployment.json>",
          "description": "Deployment context that binds explicit AI roles to packages.",
          "default": "none",
          "commands": [
            "collect"
          ]
        },
        {
          "name": "bindings",
          "arg": "<bindings.json>",
          "description": "Explicit AI role bindings for the packages.",
          "default": "none",
          "commands": [
            "collect",
            "inventory"
          ]
        },
        {
          "name": "snapshot",
          "arg": "<snapshot.json>",
          "description": "Advisory database identity (id and optional generatedAt) to preserve freshness context.",
          "default": "none",
          "commands": [
            "collect",
            "inventory"
          ]
        },
        {
          "name": "as-of",
          "arg": "<UTC-ISO>",
          "description": "Instant for deterministic age calculation; needs --snapshot.",
          "default": "none",
          "commands": [
            "collect",
            "inventory"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn sca collect . --out out/sca",
          "note": "Collect every OSV package and advisory in one offline invocation."
        }
      ],
      "exit": {
        "0": "pass",
        "1": "findings or a requested change gate",
        "2": "usage error or invalid input",
        "3": "incomplete or unknown completion",
        "4": "execution or normalization failure"
      },
      "notes": [
        "Artifacts are written to --out: raw evidence, run.json, and when parseable result.json, results.sarif and summary.md."
      ],
      "runsIn": "keryn",
      "environment": [
        "GITHUB_TOKEN",
        "GITLAB_TOKEN"
      ]
    },
    {
      "path": "sca scan",
      "summary": "run an installed OSV-Scanner v2 over a directory, lockfile or SBOM",
      "usage": "keryn sca scan <directory|lockfile|sbom> --out <new-directory> [--online] [--executable <osv-scanner>] [--repo-root <dir>] [--config <.keryn.yml> | --no-config]",
      "args": [
        {
          "name": "target",
          "description": "What to scan.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "vex",
          "arg": "<local-file>",
          "description": "Consume attributed OpenVEX, CSAF 2.0 VEX or CycloneDX VEX; unknown coverage and independent inventory/SBOM gates remain unchanged.",
          "default": "none",
          "repeatable": true,
          "commands": [
            "sca fix",
            "sca image",
            "sca scan",
            "sca import",
            "sca collect",
            "sca inventory",
            "sca assess",
            "sca deno",
            "sca sbom"
          ]
        },
        {
          "name": "vex-product",
          "arg": "<purl|url>",
          "description": "Root product context for --vex subcomponents.",
          "default": "none",
          "commands": [
            "sca fix",
            "sca image",
            "sca scan",
            "sca import",
            "sca collect",
            "sca inventory",
            "sca assess",
            "sca deno",
            "sca sbom"
          ]
        },
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "fail-on",
          "arg": "error|warning|info|none",
          "description": "Lowest severity that makes the run exit 1.",
          "default": "error"
        },
        {
          "name": "executable",
          "arg": "<path>",
          "description": "The scanner binary to run: osv-scanner for sca, the ZAP launcher for dast. Nothing is installed automatically.",
          "default": "found on PATH",
          "commands": [
            "scan",
            "collect"
          ]
        },
        {
          "name": "timeout",
          "arg": "<seconds>",
          "description": "Time limit for the scanner run. Maximum 3600. For sca fix: Per-scan analysis time limit. Manager executions have a separate fixed timeout.",
          "default": "300",
          "commands": [
            "scan",
            "collect",
            "fix"
          ]
        },
        {
          "name": "online",
          "description": "Permit advisory requests to OSV.dev (package names and versions only). Without it the installed scanner must have a local advisory database. For sca fix: Allow registry access only for the explicitly requested package manager. Advisory records stay pinned; requires --run-package-manager.",
          "default": "off",
          "commands": [
            "scan",
            "collect",
            "deno",
            "image",
            "malicious",
            "fix"
          ]
        },
        {
          "name": "offline",
          "description": "Explicitly stay offline (the default).",
          "default": "off",
          "commands": [
            "scan",
            "collect"
          ]
        },
        {
          "name": "config",
          "arg": "<.keryn.yml>",
          "description": "Configuration used for dependency roles. For sca fix: Configuration for the comparison scope. PR jobs use trusted-base configuration.",
          "default": "<repo-root>/.keryn.yml, else ./.keryn.yml",
          "commands": [
            "scan",
            "fix"
          ]
        },
        {
          "name": "no-config",
          "description": "Use the default roles instead of any .keryn.yml. For sca fix: Use defaults instead of local configuration.",
          "default": "off",
          "commands": [
            "scan",
            "fix"
          ]
        },
        {
          "name": "repo-root",
          "arg": "<dir>",
          "description": "Judge manifest roles relative to this repository instead of the target, so scripts/** is tooling as in keryn scan.",
          "default": "the target",
          "commands": [
            "scan"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn sca scan . --out out/sca --fail-on warning",
          "note": "Offline scan using the local advisory database."
        },
        {
          "command": "keryn sca scan package-lock.json --out out/sca --online",
          "note": "Permit OSV.dev advisory requests."
        }
      ],
      "exit": {
        "0": "pass",
        "1": "findings or a requested change gate",
        "2": "usage error or invalid input",
        "3": "incomplete or unknown completion",
        "4": "execution or normalization failure"
      },
      "notes": [
        "Artifacts are written to --out: raw evidence, run.json, and when parseable result.json, results.sarif and summary.md."
      ],
      "runsIn": "keryn",
      "environment": [
        "GITHUB_TOKEN",
        "GITLAB_TOKEN"
      ]
    },
    {
      "path": "sca import",
      "summary": "import an SCA report with a completion receipt",
      "usage": "keryn sca import <report> --out <new-directory> [--parser <id>] [--completion complete|partial|unknown|failed] [--vex <file> --vex-identity <profile>]",
      "args": [
        {
          "name": "report",
          "description": "A scanner report file, read locally.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "vex",
          "arg": "<local-file>",
          "description": "Consume attributed OpenVEX, CSAF 2.0 VEX or CycloneDX VEX; unknown coverage and independent inventory/SBOM gates remain unchanged.",
          "default": "none",
          "repeatable": true,
          "commands": [
            "sca fix",
            "sca image",
            "sca scan",
            "sca import",
            "sca collect",
            "sca inventory",
            "sca assess",
            "sca deno",
            "sca sbom"
          ]
        },
        {
          "name": "vex-product",
          "arg": "<purl|url>",
          "description": "Root product context for --vex subcomponents.",
          "default": "none",
          "commands": [
            "sca fix",
            "sca image",
            "sca scan",
            "sca import",
            "sca collect",
            "sca inventory",
            "sca assess",
            "sca deno",
            "sca sbom"
          ]
        },
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "fail-on",
          "arg": "error|warning|info|none",
          "description": "Lowest severity that makes the run exit 1.",
          "default": "error"
        },
        {
          "name": "parser",
          "arg": "<id>",
          "description": "Report format to read (SCA: an OSV-Scanner or other SCA report format; DAST: burp or zap).",
          "default": "detected, else required",
          "commands": [
            "import"
          ]
        },
        {
          "name": "completion",
          "arg": "complete|partial|unknown|failed",
          "description": "How complete the original scan was. Keryn cannot verify it; the value is recorded as caller-attested.",
          "default": "unknown (exits 3)",
          "commands": [
            "import"
          ]
        },
        {
          "name": "vex-identity",
          "arg": "legacy|keryn-package-id/1",
          "description": "Select the package identity profile for VEX matching. Requires --vex. The keryn-package-id/1 profile uses the installed package identity WASM module.",
          "default": "legacy",
          "commands": [
            "import"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn sca import osv.sarif --out out/sca --completion complete",
          "note": "Gate OSV-Scanner SARIF you ran elsewhere (scan with --format sarif)."
        }
      ],
      "exit": {
        "0": "pass",
        "1": "findings or a requested change gate",
        "2": "usage error or invalid input",
        "3": "incomplete or unknown completion",
        "4": "execution or normalization failure"
      },
      "notes": [
        "Artifacts are written to --out: raw evidence, run.json, and when parseable result.json, results.sarif and summary.md."
      ],
      "runsIn": "keryn",
      "environment": [
        "GITHUB_TOKEN",
        "GITLAB_TOKEN"
      ]
    },
    {
      "path": "sca inventory",
      "summary": "complete-package inventory with explicit AI roles and reproducible change detection",
      "usage": "keryn sca inventory <osv.json|cyclonedx.json|spdx.json> --out <new-directory> [--bindings <bindings.json>] [--complete] [--base <inventory.json> --fail-on-change] [--snapshot <snapshot.json> --as-of <UTC-ISO>]",
      "args": [
        {
          "name": "report",
          "description": "OSV JSON, CycloneDX JSON or SPDX 2.3 JSON.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "vex",
          "arg": "<local-file>",
          "description": "Consume attributed OpenVEX, CSAF 2.0 VEX or CycloneDX VEX; unknown coverage and independent inventory/SBOM gates remain unchanged.",
          "default": "none",
          "repeatable": true,
          "commands": [
            "sca fix",
            "sca image",
            "sca scan",
            "sca import",
            "sca collect",
            "sca inventory",
            "sca assess",
            "sca deno",
            "sca sbom"
          ]
        },
        {
          "name": "vex-product",
          "arg": "<purl|url>",
          "description": "Root product context for --vex subcomponents.",
          "default": "none",
          "commands": [
            "sca fix",
            "sca image",
            "sca scan",
            "sca import",
            "sca collect",
            "sca inventory",
            "sca assess",
            "sca deno",
            "sca sbom"
          ]
        },
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "fail-on",
          "arg": "error|warning|info|none",
          "description": "Lowest severity that makes the run exit 1.",
          "default": "error"
        },
        {
          "name": "bindings",
          "arg": "<bindings.json>",
          "description": "Explicit AI role bindings for the packages.",
          "default": "none",
          "commands": [
            "collect",
            "inventory"
          ]
        },
        {
          "name": "snapshot",
          "arg": "<snapshot.json>",
          "description": "Advisory database identity (id and optional generatedAt) to preserve freshness context.",
          "default": "none",
          "commands": [
            "collect",
            "inventory"
          ]
        },
        {
          "name": "as-of",
          "arg": "<UTC-ISO>",
          "description": "Instant for deterministic age calculation; needs --snapshot.",
          "default": "none",
          "commands": [
            "collect",
            "inventory"
          ]
        },
        {
          "name": "complete",
          "description": "Assert that the input report is a complete collection. Without it inventory exits 3 as incomplete.",
          "default": "off",
          "commands": [
            "inventory"
          ]
        },
        {
          "name": "base",
          "arg": "<inventory.json|hook-snapshot.json|directory>",
          "description": "Earlier inventory, or comparable package hook metadata for malicious inspection.",
          "default": "none",
          "commands": [
            "inventory",
            "malicious"
          ]
        },
        {
          "name": "fail-on-change",
          "description": "Exit 1 when inventory, bindings or snapshot changed against --base, independent of vulnerability severity.",
          "default": "off",
          "commands": [
            "inventory"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn sca inventory bom.cdx.json --out out/inv --complete",
          "note": "Inventory every package, including those without advisories."
        },
        {
          "command": "keryn sca inventory bom.cdx.json --out out/inv --complete --base old/inventory.json --fail-on-change",
          "note": "Gate on inventory changes."
        }
      ],
      "exit": {
        "0": "pass",
        "1": "change gate tripped, or findings",
        "2": "usage error or invalid input",
        "3": "inventory is incomplete (no --complete)",
        "4": "execution or normalization failure"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": [
        "GITHUB_TOKEN",
        "GITLAB_TOKEN"
      ]
    },
    {
      "path": "sca assess",
      "summary": "offline advisory assessment of one OSV batch: affected, not affected or unknown per package",
      "usage": "keryn sca assess <batch.json> --out <new-directory> [--json]",
      "args": [
        {
          "name": "batch.json",
          "description": "A keryn/sca-assessment-batch/1 file: OSV records and package queries.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "vex",
          "arg": "<local-file>",
          "description": "Consume attributed OpenVEX, CSAF 2.0 VEX or CycloneDX VEX; unknown coverage and independent inventory/SBOM gates remain unchanged.",
          "default": "none",
          "repeatable": true,
          "commands": [
            "sca fix",
            "sca image",
            "sca scan",
            "sca import",
            "sca collect",
            "sca inventory",
            "sca assess",
            "sca deno",
            "sca sbom"
          ]
        },
        {
          "name": "vex-product",
          "arg": "<purl|url>",
          "description": "Root product context for --vex subcomponents.",
          "default": "none",
          "commands": [
            "sca fix",
            "sca image",
            "sca scan",
            "sca import",
            "sca collect",
            "sca inventory",
            "sca assess",
            "sca deno",
            "sca sbom"
          ]
        },
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "fail-on",
          "arg": "error|warning|info|none",
          "description": "Lowest severity that makes the run exit 1.",
          "default": "error"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn sca assess batch.json --out out/assess",
          "note": "Decide every advisory range offline."
        }
      ],
      "exit": {
        "0": "no package affected",
        "1": "a package is affected",
        "2": "usage error",
        "3": "coverage incomplete: a range could not be decided",
        "4": "execution failure"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": [
        "GITHUB_TOKEN",
        "GITLAB_TOKEN"
      ]
    },
    {
      "path": "sca deno",
      "summary": "read Deno projects' deno.lock files and imports, which OSV-Scanner has no extractor for",
      "usage": "keryn sca deno <directory> --out <new-directory> [--root <repository>] [--online]",
      "args": [
        {
          "name": "directory",
          "description": "Deno project folder.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "vex",
          "arg": "<local-file>",
          "description": "Consume attributed OpenVEX, CSAF 2.0 VEX or CycloneDX VEX; unknown coverage and independent inventory/SBOM gates remain unchanged.",
          "default": "none",
          "repeatable": true,
          "commands": [
            "sca fix",
            "sca image",
            "sca scan",
            "sca import",
            "sca collect",
            "sca inventory",
            "sca assess",
            "sca deno",
            "sca sbom"
          ]
        },
        {
          "name": "vex-product",
          "arg": "<purl|url>",
          "description": "Root product context for --vex subcomponents.",
          "default": "none",
          "commands": [
            "sca fix",
            "sca image",
            "sca scan",
            "sca import",
            "sca collect",
            "sca inventory",
            "sca assess",
            "sca deno",
            "sca sbom"
          ]
        },
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "fail-on",
          "arg": "error|warning|info|none",
          "description": "Lowest severity that makes the run exit 1.",
          "default": "error"
        },
        {
          "name": "online",
          "description": "Permit advisory requests to OSV.dev (package names and versions only). Without it the installed scanner must have a local advisory database. For sca fix: Allow registry access only for the explicitly requested package manager. Advisory records stay pinned; requires --run-package-manager.",
          "default": "off",
          "commands": [
            "scan",
            "collect",
            "deno",
            "image",
            "malicious",
            "fix"
          ]
        },
        {
          "name": "root",
          "arg": "<repository>",
          "description": "Repository root whose deno.lock and deno.json(c) between it and the directory are also read.",
          "default": "the directory",
          "commands": [
            "deno"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn sca deno . --out out/deno",
          "note": "Inventory deno.lock; add --online to ask OSV.dev."
        }
      ],
      "exit": {
        "0": "pass",
        "1": "findings or a requested change gate",
        "2": "usage error or invalid input",
        "3": "incomplete or unknown completion",
        "4": "execution or normalization failure"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": [
        "GITHUB_TOKEN",
        "GITLAB_TOKEN"
      ]
    },
    {
      "path": "sca sbom",
      "summary": "compare a release's CycloneDX SBOM with what the release's files contain",
      "usage": "keryn sca sbom <release.cdx.json> <file-or-folder>... --out <new-directory> [--cargo-lock <Cargo.lock>]... [--notices <file>]... [--sbom-identity <profile>]",
      "args": [
        {
          "name": "release.cdx.json",
          "description": "The release's CycloneDX SBOM.",
          "required": true
        },
        {
          "name": "file-or-folder",
          "description": "Files to inspect. Archives are named, not unpacked.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "vex",
          "arg": "<local-file>",
          "description": "Consume attributed OpenVEX, CSAF 2.0 VEX or CycloneDX VEX; unknown coverage and independent inventory/SBOM gates remain unchanged.",
          "default": "none",
          "repeatable": true,
          "commands": [
            "sca fix",
            "sca image",
            "sca scan",
            "sca import",
            "sca collect",
            "sca inventory",
            "sca assess",
            "sca deno",
            "sca sbom"
          ]
        },
        {
          "name": "vex-product",
          "arg": "<purl|url>",
          "description": "Root product context for --vex subcomponents.",
          "default": "none",
          "commands": [
            "sca fix",
            "sca image",
            "sca scan",
            "sca import",
            "sca collect",
            "sca inventory",
            "sca assess",
            "sca deno",
            "sca sbom"
          ]
        },
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "fail-on",
          "arg": "error|warning|info|none",
          "description": "Lowest severity that makes the run exit 1.",
          "default": "error"
        },
        {
          "name": "cargo-lock",
          "arg": "<Cargo.lock>",
          "description": "A Cargo.lock whose registry packages are compared too.",
          "default": "none",
          "commands": [
            "sbom"
          ],
          "repeatable": true
        },
        {
          "name": "sbom-identity",
          "arg": "<legacy|keryn-package-id/1>",
          "description": "Select the package identity parser for release SBOM declarations. The check still compares aggregate coverage.",
          "default": "legacy",
          "commands": [
            "sbom"
          ]
        },
        {
          "name": "notices",
          "arg": "<file>",
          "description": "A licence notices file; components it does not name are listed.",
          "default": "none",
          "commands": [
            "sbom"
          ],
          "repeatable": true
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn sca sbom release.cdx.json dist/ --out out/sbom --notices NOTICES.txt",
          "note": "List undeclared components and ones missing from the notices."
        }
      ],
      "exit": {
        "0": "ok",
        "1": "undeclared, mismatched, or missing from notices",
        "2": "usage error",
        "3": "nothing observed"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": [
        "GITHUB_TOKEN",
        "GITLAB_TOKEN"
      ]
    },
    {
      "path": "dast plan",
      "summary": "print what a web test would cover (scope, sign-in, rate, modules, estimate) and send nothing",
      "usage": "keryn dast plan <url...> [--spec f] [--har f] [--sitemap f] [--include p] [--exclude p] [--header-env Name=ENV] [--module passive,crawl] [--rps n] [--max-urls n] [--max-requests n] [--json]",
      "args": [
        {
          "name": "url",
          "description": "One or more start URLs.",
          "required": false
        }
      ],
      "flags": [
        {
          "name": "json",
          "description": "Print the plan, result or receipt as JSON.",
          "default": "off"
        },
        {
          "name": "fail-on",
          "arg": "error|warning|info|none",
          "description": "Lowest severity that makes the run exit 1.",
          "default": "error"
        },
        {
          "name": "spec",
          "arg": "<file>",
          "description": "OpenAPI document that supplies URLs. Read locally; references are not fetched.",
          "default": "none",
          "commands": [
            "plan",
            "test"
          ]
        },
        {
          "name": "har",
          "arg": "<file>",
          "description": "HAR capture that supplies URLs.",
          "default": "none",
          "commands": [
            "plan",
            "test"
          ]
        },
        {
          "name": "sitemap",
          "arg": "<file>",
          "description": "Sitemap that supplies URLs.",
          "default": "none",
          "commands": [
            "plan",
            "test"
          ]
        },
        {
          "name": "include",
          "arg": "<pattern>",
          "description": "Only test URLs matching the pattern.",
          "default": "everything in scope",
          "commands": [
            "plan",
            "test"
          ],
          "repeatable": true
        },
        {
          "name": "exclude",
          "arg": "<pattern>",
          "description": "Never test URLs matching the pattern.",
          "default": "none",
          "commands": [
            "plan",
            "test"
          ],
          "repeatable": true
        },
        {
          "name": "host",
          "arg": "<host>",
          "description": "Add a host to the scope besides those of the given URLs.",
          "default": "hosts of the given URLs",
          "commands": [
            "plan",
            "test"
          ],
          "repeatable": true
        },
        {
          "name": "header-env",
          "arg": "<Name=ENV_VAR>",
          "description": "Send header Name with the value of the environment variable. The value is never printed and never taken from argv.",
          "default": "unauthenticated",
          "commands": [
            "plan",
            "test"
          ]
        },
        {
          "name": "cookie-env",
          "arg": "<Name=ENV_VAR>",
          "description": "Send cookie Name with the value of the environment variable. Not with --header-env.",
          "default": "unauthenticated",
          "commands": [
            "plan",
            "test"
          ]
        },
        {
          "name": "module",
          "arg": "<passive,crawl>",
          "description": "Comma-separated modules to run. Attack probes are keryn dast scan --active.",
          "default": "passive",
          "commands": [
            "plan",
            "test"
          ]
        },
        {
          "name": "depth",
          "arg": "<n>",
          "description": "Crawl depth, 1 to 5.",
          "default": "1",
          "commands": [
            "plan",
            "test"
          ]
        },
        {
          "name": "rps",
          "arg": "<n>",
          "description": "Requests per second, above 0 and at most 100.",
          "default": "the built-in rate",
          "commands": [
            "plan",
            "test"
          ]
        },
        {
          "name": "max-urls",
          "arg": "<n>",
          "description": "Most URLs to test, at most 5000.",
          "default": "the built-in cap",
          "commands": [
            "plan",
            "test"
          ]
        },
        {
          "name": "max-requests",
          "arg": "<n>",
          "description": "Most requests to send: plan and test at most 50000; a Nuclei query-differential profile at most 24 (12 per trial, 2 trials).",
          "default": "plan and test: the built-in cap; nuclei: 24",
          "commands": [
            "plan",
            "test",
            "nuclei"
          ]
        },
        {
          "name": "name",
          "arg": "<name>",
          "description": "Name of the target in the plan and the store.",
          "default": "derived from the URL",
          "commands": [
            "plan",
            "test"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn dast plan https://staging.example.com --spec openapi.json",
          "note": "See scope and estimate before sending anything."
        }
      ],
      "exit": {
        "0": "planned",
        "2": "usage error"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "dast test",
      "summary": "incremental web test: fingerprint the surface, test only what changed, carry earlier results",
      "usage": "keryn dast test <url...> [--spec f] [--har f] [--sitemap f] [--mode auto|cached|recheck|full] [--store dir] [--fail-on error|warning|info|none] [--json]",
      "args": [
        {
          "name": "url",
          "description": "One or more start URLs in scope.",
          "required": false
        }
      ],
      "flags": [
        {
          "name": "json",
          "description": "Print the plan, result or receipt as JSON.",
          "default": "off"
        },
        {
          "name": "fail-on",
          "arg": "error|warning|info|none",
          "description": "Lowest severity that makes the run exit 1.",
          "default": "error"
        },
        {
          "name": "spec",
          "arg": "<file>",
          "description": "OpenAPI document that supplies URLs. Read locally; references are not fetched.",
          "default": "none",
          "commands": [
            "plan",
            "test"
          ]
        },
        {
          "name": "har",
          "arg": "<file>",
          "description": "HAR capture that supplies URLs.",
          "default": "none",
          "commands": [
            "plan",
            "test"
          ]
        },
        {
          "name": "sitemap",
          "arg": "<file>",
          "description": "Sitemap that supplies URLs.",
          "default": "none",
          "commands": [
            "plan",
            "test"
          ]
        },
        {
          "name": "include",
          "arg": "<pattern>",
          "description": "Only test URLs matching the pattern.",
          "default": "everything in scope",
          "commands": [
            "plan",
            "test"
          ],
          "repeatable": true
        },
        {
          "name": "exclude",
          "arg": "<pattern>",
          "description": "Never test URLs matching the pattern.",
          "default": "none",
          "commands": [
            "plan",
            "test"
          ],
          "repeatable": true
        },
        {
          "name": "host",
          "arg": "<host>",
          "description": "Add a host to the scope besides those of the given URLs.",
          "default": "hosts of the given URLs",
          "commands": [
            "plan",
            "test"
          ],
          "repeatable": true
        },
        {
          "name": "header-env",
          "arg": "<Name=ENV_VAR>",
          "description": "Send header Name with the value of the environment variable. The value is never printed and never taken from argv.",
          "default": "unauthenticated",
          "commands": [
            "plan",
            "test"
          ]
        },
        {
          "name": "cookie-env",
          "arg": "<Name=ENV_VAR>",
          "description": "Send cookie Name with the value of the environment variable. Not with --header-env.",
          "default": "unauthenticated",
          "commands": [
            "plan",
            "test"
          ]
        },
        {
          "name": "module",
          "arg": "<passive,crawl>",
          "description": "Comma-separated modules to run. Attack probes are keryn dast scan --active.",
          "default": "passive",
          "commands": [
            "plan",
            "test"
          ]
        },
        {
          "name": "depth",
          "arg": "<n>",
          "description": "Crawl depth, 1 to 5.",
          "default": "1",
          "commands": [
            "plan",
            "test"
          ]
        },
        {
          "name": "rps",
          "arg": "<n>",
          "description": "Requests per second, above 0 and at most 100.",
          "default": "the built-in rate",
          "commands": [
            "plan",
            "test"
          ]
        },
        {
          "name": "max-urls",
          "arg": "<n>",
          "description": "Most URLs to test, at most 5000.",
          "default": "the built-in cap",
          "commands": [
            "plan",
            "test"
          ]
        },
        {
          "name": "max-requests",
          "arg": "<n>",
          "description": "Most requests to send: plan and test at most 50000; a Nuclei query-differential profile at most 24 (12 per trial, 2 trials).",
          "default": "plan and test: the built-in cap; nuclei: 24",
          "commands": [
            "plan",
            "test",
            "nuclei"
          ]
        },
        {
          "name": "mode",
          "arg": "auto|cached|recheck|full",
          "description": "How to use earlier results: auto tests only what changed, cached reuses everything, recheck re-tests carried findings, full re-tests all.",
          "default": "auto",
          "commands": [
            "test"
          ]
        },
        {
          "name": "store",
          "arg": "<dir>",
          "description": "Directory holding fingerprints and carried results.",
          "default": ".keryn/dast",
          "commands": [
            "test"
          ]
        },
        {
          "name": "name",
          "arg": "<name>",
          "description": "Name of the target in the plan and the store.",
          "default": "derived from the URL",
          "commands": [
            "plan",
            "test"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn dast test https://staging.example.com --header-env Authorization=STAGING_TOKEN",
          "note": "Test with a header whose value comes from the environment."
        },
        {
          "command": "keryn dast test https://staging.example.com --mode cached",
          "note": "Re-report without sending requests."
        }
      ],
      "exit": {
        "0": "pass",
        "1": "findings or a requested change gate",
        "2": "usage error or invalid input",
        "3": "incomplete or unknown completion",
        "4": "execution or normalization failure"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "dast boundaries",
      "summary": "check declared redirect and scope boundaries in an existing HAR",
      "usage": "keryn dast boundaries <capture.har> --policy <policy.json> --out <new-directory>",
      "args": [
        {
          "name": "capture.har",
          "description": "Recorded HTTP traffic to inspect offline.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "policy",
          "arg": "<policy.json>",
          "description": "Boundary assertions (keryn.dev/capture-boundaries/v1): redirect hops by zero-based HAR entry index with the credential headers to follow, and test scopes with their private markers.",
          "default": "required",
          "commands": [
            "boundaries"
          ]
        },
        {
          "name": "out",
          "arg": "<path>",
          "description": "New challenge file for ownership mint; new or empty artifact directory otherwise.",
          "default": "required for execution and ownership commands",
          "commands": [
            "scan",
            "import",
            "nuclei",
            "boundaries",
            "ownership check",
            "ownership mint"
          ]
        },
        {
          "name": "json",
          "description": "Print the plan, result or receipt as JSON.",
          "default": "off"
        },
        {
          "name": "fail-on",
          "arg": "error|warning|info|none",
          "description": "Lowest severity that makes the run exit 1.",
          "default": "error"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn dast boundaries test.har --policy boundaries.json --out results",
          "note": "Check observed evidence offline."
        }
      ],
      "exit": {
        "0": "passed",
        "1": "findings",
        "2": "usage error",
        "3": "incomplete evidence"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "dast scan",
      "summary": "run an installed ZAP Automation Framework scan against one explicit target scope",
      "usage": "keryn dast scan <application-url> --out <new-directory> [--active [--strength low|medium|high] [--seed <seeds.json>]] [--test-run <id>] [--ajax] [--executable <zap.sh>] [--auth <auth.json>] [--timeout <seconds>]",
      "args": [
        {
          "name": "application-url",
          "description": "HTTP(S) target scope. Use only a target you are authorized to test.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "ownership",
          "arg": "<challenge.json>",
          "description": "Locally minted ownership challenge. Fresh DNS/file verification is mandatory for active ZAP and Nuclei.",
          "default": "required for active scan and nuclei",
          "commands": [
            "scan",
            "nuclei"
          ]
        },
        {
          "name": "expect-build",
          "arg": "<web.zip>",
          "description": "Compare captured same-origin asset SHA-256 values with this web build. Record discovery/request counts. Mismatch exits 1; incomplete capture exits 3.",
          "default": "no build correlation",
          "commands": [
            "dast scan"
          ]
        },
        {
          "name": "out",
          "arg": "<path>",
          "description": "New challenge file for ownership mint; new or empty artifact directory otherwise.",
          "default": "required for execution and ownership commands",
          "commands": [
            "scan",
            "import",
            "nuclei",
            "boundaries",
            "ownership check",
            "ownership mint"
          ]
        },
        {
          "name": "json",
          "description": "Print the plan, result or receipt as JSON.",
          "default": "off"
        },
        {
          "name": "fail-on",
          "arg": "error|warning|info|none",
          "description": "Lowest severity that makes the run exit 1.",
          "default": "error"
        },
        {
          "name": "executable",
          "arg": "<path>",
          "description": "The scanner binary to run: osv-scanner for sca, the ZAP launcher for dast. Nothing is installed automatically.",
          "default": "found on PATH",
          "commands": [
            "scan"
          ]
        },
        {
          "name": "timeout",
          "arg": "<seconds>",
          "description": "Time limit: scan maximum 3600 seconds; Nuclei maximum 300.",
          "default": "scan 300; Nuclei 30",
          "commands": [
            "scan",
            "nuclei"
          ]
        },
        {
          "name": "active",
          "description": "Also enable ZAP active attack checks and the Open MCP Server Detection probe. Use only on a target you are authorized to test.",
          "default": "off: spider and passive analysis only",
          "commands": [
            "dast scan"
          ]
        },
        {
          "name": "strength",
          "arg": "low|medium|high",
          "description": "With --active: how many requests each attack rule spends on a parameter. Low is quick and misses what needs more than a rule's first payloads; medium and high send several times more requests inside the same time budget, and a rule ZAP cuts short is named (exit 3).",
          "default": "low",
          "commands": [
            "dast scan"
          ]
        },
        {
          "name": "seed",
          "arg": "<seeds.json>",
          "description": "With --active: a file (keryn.dev/dast-seeds/v1) of requests no crawl reaches, such as a JSON login call made from script or an unlinked path. Each is sent once after the crawl and its parameters are attacked with the rest. At most 50 requests, paths under the target only, method, path, contentType and body only: no headers or credentials.",
          "default": "none: only what the spiders find is attacked",
          "commands": [
            "dast scan"
          ]
        },
        {
          "name": "test-run",
          "arg": "<id>",
          "description": "Send the header x-keryn-test-run-id with this value on every request of the scan (spiders, seed requests and attack rules). An application running a Keryn Runtime agent records it with each flow of request input it observes, and keryn ledger build then puts on each web finding the code location its input was observed reaching. An identifier you choose (letters, digits, dot, underscore, hyphen; at most 128), not a credential; recorded in provenance.json.",
          "default": "none: no test identity header is sent",
          "commands": [
            "dast scan"
          ]
        },
        {
          "name": "ajax",
          "description": "Also run ZAP's AJAX spider in a headless Chrome, Chromium or Firefox already on PATH, inside the same scope and time budget (1 browser, depth 5, at most 50 crawl states, no random input). Needs the spiderAjax, selenium and webdriver add-ons; KERYN_ZAP_CHROMEDRIVER or KERYN_ZAP_GECKODRIVER can name an installed driver that matches the browser. Nothing is downloaded, and a browser that does not start fails the run.",
          "default": "off: a script-rendered target page is reported as not crawled (exit 3)",
          "commands": [
            "dast scan"
          ]
        },
        {
          "name": "auth",
          "arg": "<auth.json>",
          "description": "Reviewed authentication with a same-scope identity poll and authentication-statistics gates: one header from an environment variable, or a session (keryn.dev/ai-session/v1) Keryn logs in, hands to ZAP and logs out of. Optional exclude (paths no job requests, such as sign-out) and start (the signed-in landing page the spiders begin at), both inside the target.",
          "default": "unauthenticated",
          "commands": [
            "dast scan"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn dast scan https://staging.example.com --out out/dast",
          "note": "Spider and passive analysis; still sends HTTP requests."
        },
        {
          "command": "keryn dast scan https://staging.example.com --out out/dast --active --auth auth.json --ownership owner.json",
          "note": "Add active checks with reviewed authentication and freshly verified ownership."
        }
      ],
      "exit": {
        "0": "pass",
        "1": "findings or a requested change gate",
        "2": "usage error or invalid input",
        "3": "incomplete or unknown completion",
        "4": "execution or normalization failure"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "dast import",
      "summary": "read a Burp or ZAP XML report locally",
      "usage": "keryn dast import <report.xml> --parser burp|zap --target <application-url> --out <new-directory> [--completion complete|partial|unknown|failed]",
      "args": [
        {
          "name": "report.xml",
          "description": "Burp or ZAP XML report.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "out",
          "arg": "<path>",
          "description": "New challenge file for ownership mint; new or empty artifact directory otherwise.",
          "default": "required for execution and ownership commands",
          "commands": [
            "scan",
            "import",
            "nuclei",
            "boundaries",
            "ownership check",
            "ownership mint"
          ]
        },
        {
          "name": "json",
          "description": "Print the plan, result or receipt as JSON.",
          "default": "off"
        },
        {
          "name": "fail-on",
          "arg": "error|warning|info|none",
          "description": "Lowest severity that makes the run exit 1.",
          "default": "error"
        },
        {
          "name": "parser",
          "arg": "<id>",
          "description": "Report format to read (SCA: an OSV-Scanner or other SCA report format; DAST: burp or zap).",
          "default": "detected, else required",
          "commands": [
            "import"
          ]
        },
        {
          "name": "completion",
          "arg": "complete|partial|unknown|failed",
          "description": "How complete the original scan was. Keryn cannot verify it; the value is recorded as caller-attested.",
          "default": "unknown (exits 3)",
          "commands": [
            "import"
          ]
        },
        {
          "name": "target",
          "arg": "<application-url>",
          "description": "Application URL for imported provenance or the explicit verified target of Nuclei template YAML.",
          "default": "required",
          "commands": [
            "dast import",
            "dast nuclei"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn dast import zap.xml --parser zap --target https://staging.example.com --out out/dast",
          "note": "Gate a report from another run."
        }
      ],
      "exit": {
        "0": "pass",
        "1": "findings or a requested change gate",
        "2": "usage error or invalid input",
        "3": "incomplete or unknown completion",
        "4": "execution or normalization failure"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "dast ownership mint",
      "summary": "mint a random origin-bound ownership challenge without contacting the target",
      "usage": "keryn dast ownership mint <origin-or-host> --out <new-file> [--json]",
      "args": [
        {
          "name": "origin-or-host",
          "description": "Exact origin or DNS host you control.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "out",
          "arg": "<path>",
          "description": "New challenge file for ownership mint; new or empty artifact directory otherwise.",
          "default": "required for execution and ownership commands",
          "commands": [
            "scan",
            "import",
            "nuclei",
            "boundaries",
            "ownership check",
            "ownership mint"
          ]
        },
        {
          "name": "json",
          "description": "Print the plan, result or receipt as JSON.",
          "default": "off"
        },
        {
          "name": "fail-on",
          "arg": "error|warning|info|none",
          "description": "Lowest severity that makes the run exit 1.",
          "default": "error"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn dast ownership mint https://staging.example.com --out owner.json",
          "note": "Publish its public DNS TXT or well-known token."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error or unreadable input"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "dast ownership check",
      "summary": "freshly check a locally minted DNS or well-known ownership publication",
      "usage": "keryn dast ownership check <challenge.json> --out <new-directory> [--json]",
      "args": [
        {
          "name": "challenge.json",
          "description": "Challenge minted by this installation.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "out",
          "arg": "<path>",
          "description": "New challenge file for ownership mint; new or empty artifact directory otherwise.",
          "default": "required for execution and ownership commands",
          "commands": [
            "scan",
            "import",
            "nuclei",
            "boundaries",
            "ownership check",
            "ownership mint"
          ]
        },
        {
          "name": "json",
          "description": "Print the plan, result or receipt as JSON.",
          "default": "off"
        },
        {
          "name": "fail-on",
          "arg": "error|warning|info|none",
          "description": "Lowest severity that makes the run exit 1.",
          "default": "error"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn dast ownership check owner.json --out out/ownership",
          "note": "No scanner probe is sent."
        }
      ],
      "exit": {
        "0": "verified",
        "2": "usage",
        "3": "ownership absent or invalid"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "dast nuclei",
      "summary": "run a bounded one-GET Nuclei template/profile against a freshly verified target",
      "usage": "keryn dast nuclei <profile.json|template.yaml> --ownership <challenge.json> --out <new-directory> [--target <url>] [--timeout <seconds>] [--max-requests <n>] [--json]",
      "args": [
        {
          "name": "profile.json",
          "description": "A public JSON profile, a query-differential profile (keryn.dev/nuclei-query-differential/v1), or a one-GET YAML template with body word/status matchers.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "ownership",
          "arg": "<challenge.json>",
          "description": "Locally minted ownership challenge. Fresh DNS/file verification is mandatory for active ZAP and Nuclei.",
          "default": "required for active scan and nuclei",
          "commands": [
            "scan",
            "nuclei"
          ]
        },
        {
          "name": "out",
          "arg": "<path>",
          "description": "New challenge file for ownership mint; new or empty artifact directory otherwise.",
          "default": "required for execution and ownership commands",
          "commands": [
            "scan",
            "import",
            "nuclei",
            "boundaries",
            "ownership check",
            "ownership mint"
          ]
        },
        {
          "name": "json",
          "description": "Print the plan, result or receipt as JSON.",
          "default": "off"
        },
        {
          "name": "fail-on",
          "arg": "error|warning|info|none",
          "description": "Lowest severity that makes the run exit 1.",
          "default": "error"
        },
        {
          "name": "timeout",
          "arg": "<seconds>",
          "description": "Time limit: scan maximum 3600 seconds; Nuclei maximum 300.",
          "default": "scan 300; Nuclei 30",
          "commands": [
            "scan",
            "nuclei"
          ]
        },
        {
          "name": "target",
          "arg": "<application-url>",
          "description": "Application URL for imported provenance or the explicit verified target of Nuclei template YAML.",
          "default": "required",
          "commands": [
            "dast import",
            "dast nuclei"
          ]
        },
        {
          "name": "max-requests",
          "arg": "<n>",
          "description": "Most requests to send: plan and test at most 50000; a Nuclei query-differential profile at most 24 (12 per trial, 2 trials).",
          "default": "plan and test: the built-in cap; nuclei: 24",
          "commands": [
            "plan",
            "test",
            "nuclei"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn dast nuclei profile.json --ownership owner.json --out out/nuclei",
          "note": "Send one GET and match the profile."
        }
      ],
      "exit": {
        "0": "pass",
        "1": "matched",
        "2": "usage error or invalid input",
        "3": "incomplete",
        "4": "execution or normalization failure"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "api import",
      "summary": "import OpenAPI 3.0/3.1 or HAR into a draft API security review; sends nothing",
      "usage": "keryn api import <file> --format openapi|har --target <origin> --application <id> --revision <revision> --out <new-directory>",
      "args": [
        {
          "name": "file",
          "description": "OpenAPI JSON/YAML or HAR.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "format",
          "arg": "openapi|har",
          "description": "Input format.",
          "default": "required",
          "commands": [
            "import"
          ]
        },
        {
          "name": "target",
          "arg": "<origin>",
          "description": "Origin the suite will talk to.",
          "default": "required",
          "commands": [
            "import"
          ]
        },
        {
          "name": "application",
          "arg": "<id>",
          "description": "Application id recorded in the suite.",
          "default": "required",
          "commands": [
            "import"
          ]
        },
        {
          "name": "revision",
          "arg": "<revision>",
          "description": "Revision recorded in the suite.",
          "default": "required",
          "commands": [
            "import"
          ]
        },
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn api import openapi.yaml --format openapi --target https://staging.example.com --application shop --revision abc123 --out out/api",
          "note": "Draft; references are not fetched and drafts cannot execute."
        }
      ],
      "exit": {
        "0": "pass",
        "1": "findings or a requested change gate",
        "2": "usage error or invalid input",
        "3": "incomplete or unknown completion",
        "4": "execution or normalization failure"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "api compile",
      "summary": "compile an authored api-suite-review/v1 into the AI security suite contract",
      "usage": "keryn api compile <review.json> --out <new-directory> [--json]",
      "args": [
        {
          "name": "review.json",
          "description": "The reviewed draft.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn api compile review.json --out out/suite",
          "note": "Sends no requests."
        }
      ],
      "exit": {
        "0": "pass",
        "1": "findings or a requested change gate",
        "2": "usage error or invalid input",
        "3": "incomplete or unknown completion",
        "4": "execution or normalization failure"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "api validate",
      "summary": "validate a suite; sends no requests",
      "usage": "keryn api validate <suite.json> [--json]",
      "args": [
        {
          "name": "suite.json",
          "description": "Suite to check.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn api validate suite.json",
          "note": "Check the suite contract."
        }
      ],
      "exit": {
        "0": "pass",
        "1": "findings or a requested change gate",
        "2": "usage error or invalid input",
        "3": "incomplete or unknown completion",
        "4": "execution or normalization failure"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "api run",
      "summary": "execute the reviewed requests; may change target state",
      "usage": "keryn api run <suite.json> --out <new-directory> [--suite-sha256 <digest>] [--timeout <seconds>] [--json]",
      "args": [
        {
          "name": "suite.json",
          "description": "Reviewed suite.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "suite-sha256",
          "arg": "<digest>",
          "description": "Pin the original suite bytes; a mismatch sends no requests.",
          "default": "none",
          "commands": [
            "run"
          ]
        },
        {
          "name": "timeout",
          "arg": "<seconds>",
          "description": "Per-request time limit; the suite deadline is 300 seconds.",
          "default": "30",
          "commands": [
            "run"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn api run suite.json --out out/run --suite-sha256 $(sha256sum suite.json | cut -d' ' -f1)",
          "note": "Pin the suite bytes before sending."
        }
      ],
      "exit": {
        "0": "pass",
        "1": "findings or a requested change gate",
        "2": "usage error or invalid input",
        "3": "incomplete or unknown completion",
        "4": "execution or normalization failure"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "api review",
      "summary": "compare a receipt with a baseline receipt",
      "usage": "keryn api review <receipt.json> --suite <suite.json> --baseline <receipt.json> --baseline-suite <suite.json> --out <new-directory>",
      "args": [
        {
          "name": "receipt.json",
          "description": "The after receipt.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "suite",
          "arg": "<suite.json>",
          "description": "The suite the receipt was produced from.",
          "default": "required",
          "commands": [
            "review"
          ]
        },
        {
          "name": "baseline",
          "arg": "<receipt.json>",
          "description": "The earlier receipt to compare with.",
          "default": "required",
          "commands": [
            "review"
          ]
        },
        {
          "name": "baseline-suite",
          "arg": "<suite.json>",
          "description": "The suite the baseline was produced from.",
          "default": "required",
          "commands": [
            "review"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn api review after/receipt.json --suite suite.json --baseline before/receipt.json --baseline-suite suite.json --out out/review",
          "note": "Did the fix hold."
        }
      ],
      "exit": {
        "0": "pass",
        "1": "findings or a requested change gate",
        "2": "usage error or invalid input",
        "3": "incomplete or unknown completion",
        "4": "execution or normalization failure"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "ai-test validate",
      "summary": "validate a suite; sends no requests",
      "usage": "keryn ai-test validate <suite.json> [--json]",
      "args": [
        {
          "name": "suite.json",
          "description": "Suite to check.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn ai-test validate suite.json",
          "note": "Check the contract."
        }
      ],
      "exit": {
        "0": "valid",
        "2": "invalid suite or options"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "ai-test run",
      "summary": "send the suite's bounded HTTP requests to its declared origin and check assertions",
      "usage": "keryn ai-test run <suite.json> --out <new-directory> [--timeout <seconds>] [--suite-sha256 <digest>] [--resume <receipt.json>] [--json]",
      "args": [
        {
          "name": "suite.json",
          "description": "Reviewed suite.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "timeout",
          "arg": "<seconds>",
          "description": "Per-request time limit, at most 300; the suite deadline is 300 seconds. Redirects are refused.",
          "default": "30",
          "commands": [
            "run"
          ]
        },
        {
          "name": "suite-sha256",
          "arg": "<digest>",
          "description": "Pin the original suite bytes (keryn ci does); a mismatch sends no requests.",
          "default": "none",
          "commands": [
            "run"
          ]
        },
        {
          "name": "resume",
          "arg": "<receipt.json>",
          "description": "Resume at the checkpoint of an earlier run that stopped early. Refused unless the suite, revision, target, actors and secret names are unchanged; a trial that had sent a step that is not replayable is reported as a blocker, never sent again.",
          "default": "none",
          "commands": [
            "run"
          ]
        },
        {
          "name": "application",
          "arg": "<id>",
          "description": "Application id recorded in the suite.",
          "default": "required",
          "commands": [
            "init",
            "capture",
            "run"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "STAGING_TOKEN=... keryn ai-test run suite.json --out out/ai",
          "note": "Credentials come from the named environment variables."
        }
      ],
      "exit": {
        "0": "assertions pass",
        "1": "assertion violation",
        "2": "invalid suite or options",
        "3": "inconclusive",
        "4": "execution failure"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "ai-test capture",
      "summary": "read a HAR locally into a redacted, non-executable draft",
      "usage": "keryn ai-test capture <capture.har> --target <url> --application <id> --revision <id> --out <new-directory> [--json]",
      "args": [
        {
          "name": "capture.har",
          "description": "HAR capture.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "target",
          "arg": "<origin|url>",
          "description": "The origin the suite will talk to, or for capture the target URL.",
          "default": "required",
          "commands": [
            "init",
            "capture"
          ]
        },
        {
          "name": "application",
          "arg": "<id>",
          "description": "Application id recorded in the suite.",
          "default": "required",
          "commands": [
            "init",
            "capture",
            "run"
          ]
        },
        {
          "name": "revision",
          "arg": "<id>",
          "description": "Revision recorded in the suite.",
          "default": "required",
          "commands": [
            "init",
            "capture"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn ai-test capture session.har --target https://staging.example.com --application shop --revision abc123 --out out/draft",
          "note": "Add routes, secrets references and assertions before it can run."
        }
      ],
      "exit": {
        "0": "pass",
        "1": "findings or a requested change gate",
        "2": "usage error or invalid input",
        "3": "incomplete or unknown completion",
        "4": "execution or normalization failure"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "ai-test verify",
      "summary": "compare a fix receipt with a reproduced baseline",
      "usage": "keryn ai-test verify <receipt.json> --suite <suite.json> --baseline <receipt.json> --baseline-suite <suite.json> --out <new-directory>",
      "args": [
        {
          "name": "receipt.json",
          "description": "The after receipt.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "suite",
          "arg": "<suite.json>",
          "description": "The suite the receipt was produced from.",
          "default": "required",
          "commands": [
            "verify"
          ]
        },
        {
          "name": "baseline",
          "arg": "<receipt.json>",
          "description": "The earlier receipt to compare with.",
          "default": "required",
          "commands": [
            "verify"
          ]
        },
        {
          "name": "baseline-suite",
          "arg": "<suite.json>",
          "description": "The suite the baseline was produced from.",
          "default": "required",
          "commands": [
            "verify"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn ai-test verify after/receipt.json --suite suite.json --baseline before/receipt.json --baseline-suite suite.json --out out/verify",
          "note": "Comparable evidence that a fix held."
        }
      ],
      "exit": {
        "0": "pass",
        "1": "findings or a requested change gate",
        "2": "usage error or invalid input",
        "3": "incomplete or unknown completion",
        "4": "execution or normalization failure"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "ai-test packs",
      "summary": "list the reusable observed-behavior regression packs",
      "usage": "keryn ai-test packs [--json]",
      "args": [],
      "flags": [
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn ai-test packs",
          "note": "Pack ids and what each checks."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error or unreadable input"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "ai-test init",
      "summary": "instantiate a regression pack for an application",
      "usage": "keryn ai-test init <pack> --target <origin> --application <id> --revision <id> --out <new-directory> [--auth-env <name>] [--actor <id>] [--tenant <id>]",
      "args": [
        {
          "name": "pack",
          "description": "Pack id from keryn ai-test packs.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "target",
          "arg": "<origin|url>",
          "description": "The origin the suite will talk to, or for capture the target URL.",
          "default": "required",
          "commands": [
            "init",
            "capture"
          ]
        },
        {
          "name": "application",
          "arg": "<id>",
          "description": "Application id recorded in the suite.",
          "default": "required",
          "commands": [
            "init",
            "capture",
            "run"
          ]
        },
        {
          "name": "revision",
          "arg": "<id>",
          "description": "Revision recorded in the suite.",
          "default": "required",
          "commands": [
            "init",
            "capture"
          ]
        },
        {
          "name": "auth-env",
          "arg": "<name>",
          "description": "Environment variable holding the credential the suite sends.",
          "default": "none",
          "commands": [
            "init"
          ]
        },
        {
          "name": "actor",
          "arg": "<id>",
          "description": "Actor id the pack's identity checks use.",
          "default": "none",
          "commands": [
            "init"
          ]
        },
        {
          "name": "tenant",
          "arg": "<id>",
          "description": "Tenant id the pack's isolation checks use.",
          "default": "none",
          "commands": [
            "init"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn ai-test init tenant-isolation --target https://staging.example.com --application shop --revision abc123 --out out/suite --auth-env STAGING_TOKEN",
          "note": "Write a runnable suite."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error or unreadable input"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "knowledge probe",
      "summary": "metadata-only Google Drive requests for explicit files, using two configured token environment variables",
      "usage": "keryn knowledge probe <drive-probe.json> --out <new-directory> [--json]",
      "args": [
        {
          "name": "drive-probe.json",
          "description": "The probe definition.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn knowledge probe drive-probe.json --out out/probe",
          "note": "Which files each identity can see."
        }
      ],
      "exit": {
        "0": "expected source access observed",
        "1": "unexpected source access",
        "2": "usage error",
        "3": "inconclusive"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "knowledge compile",
      "summary": "validate fresh source evidence, reviewed identities and synthetic fixtures offline",
      "usage": "keryn knowledge compile <plan.json> --source <source.json> --out <new-directory> [--json]",
      "args": [
        {
          "name": "plan.json",
          "description": "Reviewed plan.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "source",
          "arg": "<source.json>",
          "description": "Fresh source evidence the plan is checked against.",
          "default": "required",
          "commands": [
            "compile"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn knowledge compile plan.json --source source.json --out out/suite",
          "note": "Success is not a security pass."
        }
      ],
      "exit": {
        "0": "pass",
        "1": "findings or a requested change gate",
        "2": "usage error or invalid input",
        "3": "incomplete or unknown completion",
        "4": "execution or normalization failure"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "knowledge run",
      "summary": "send the reviewed assistant requests with the AI security runner",
      "usage": "keryn knowledge run <suite.json> --out <new-directory> --suite-sha256 <digest> [--timeout <seconds>] [--json]",
      "args": [
        {
          "name": "suite.json",
          "description": "Compiled suite.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "suite-sha256",
          "arg": "<digest>",
          "description": "Pin the original suite bytes; a mismatch sends no requests.",
          "default": "required",
          "commands": [
            "run"
          ]
        },
        {
          "name": "timeout",
          "arg": "<seconds>",
          "description": "Per-request time limit.",
          "default": "30",
          "commands": [
            "run"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn knowledge run suite.json --out out/run --suite-sha256 <digest>",
          "note": "Retain original suites and receipts for review."
        }
      ],
      "exit": {
        "0": "pass",
        "1": "findings or a requested change gate",
        "2": "usage error or invalid input",
        "3": "incomplete or unknown completion",
        "4": "execution or normalization failure"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "knowledge review",
      "summary": "compare a receipt with a baseline receipt",
      "usage": "keryn knowledge review <receipt.json> --suite <suite.json> --baseline <receipt.json> --baseline-suite <suite.json> --out <new-directory>",
      "args": [
        {
          "name": "receipt.json",
          "description": "The after receipt.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "suite",
          "arg": "<suite.json>",
          "description": "The suite the receipt was produced from.",
          "default": "required",
          "commands": [
            "review"
          ]
        },
        {
          "name": "baseline",
          "arg": "<receipt.json>",
          "description": "The earlier receipt to compare with.",
          "default": "required",
          "commands": [
            "review"
          ]
        },
        {
          "name": "baseline-suite",
          "arg": "<suite.json>",
          "description": "The suite the baseline was produced from.",
          "default": "required",
          "commands": [
            "review"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn knowledge review after/receipt.json --suite suite.json --baseline before/receipt.json --baseline-suite suite.json --out out/review",
          "note": "Did the boundary hold after the change."
        }
      ],
      "exit": {
        "0": "pass",
        "1": "findings or a requested change gate",
        "2": "usage error or invalid input",
        "3": "incomplete or unknown completion",
        "4": "execution or normalization failure"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "agents inspect",
      "summary": "inspect local agent declarations and compare reviewed evidence",
      "usage": "keryn agents inspect <project> --project-id <stable-id> --out <new-directory> [--base <inspection.json>] [--fail-on-change] [--json]",
      "args": [
        {
          "name": "project",
          "description": "Project folder.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "project-id",
          "arg": "<stable-id>",
          "description": "Stable id binding baselines to this project.",
          "default": "required"
        },
        {
          "name": "base",
          "arg": "<inspection.json>",
          "description": "Earlier inspection of the same project and discovery scope.",
          "default": "none"
        },
        {
          "name": "fail-on-change",
          "description": "Exit 1 when the inspection differs from --base. Requires --base.",
          "default": "off"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn agents inspect . --project-id shop --out out/agents",
          "note": "Offline; no discovered tool is executed."
        },
        {
          "command": "keryn agents inspect . --project-id shop --out out/agents --base old/inspection.json --fail-on-change",
          "note": "Gate changes."
        }
      ],
      "exit": {
        "0": "inspection completed within scope, not a security approval",
        "1": "change gate",
        "2": "usage error",
        "3": "incomplete evidence"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "capabilities inspect",
      "summary": "inspect AI/MCP declarations and gate capability expansion",
      "usage": "keryn capabilities inspect <config.json> --out <new-directory> [--base <snapshot.json>] [--fail-on-expansion] [--observations <batch.json> --run-id <id>]",
      "args": [
        {
          "name": "config.json",
          "description": "Local AI or MCP configuration. Servers and tools are never launched.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "base",
          "arg": "<snapshot.json>",
          "description": "Earlier snapshot to compare with.",
          "default": "none"
        },
        {
          "name": "fail-on-expansion",
          "description": "Exit 1 when authority expanded against --base. Requires --base.",
          "default": "off"
        },
        {
          "name": "observations",
          "arg": "<batch.json>",
          "description": "Run-bound action evidence. Requires --run-id.",
          "default": "none"
        },
        {
          "name": "run-id",
          "arg": "<id>",
          "description": "The run the observations must belong to. Requires --observations.",
          "default": "none"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn capabilities inspect .mcp.json --out out/cap --base main/capabilities.json --fail-on-expansion",
          "note": "Fail when an agent gained authority."
        }
      ],
      "exit": {
        "0": "pass",
        "1": "findings or a requested change gate",
        "2": "usage error or invalid input",
        "3": "incomplete or unknown completion",
        "4": "execution or normalization failure"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "review",
      "summary": "verify a recorded fix, review capability changes, export a PR summary",
      "usage": "keryn review <receipt.json> [--suite <suite.json> --baseline <receipt.json> --baseline-suite <suite.json>] [--capabilities <snapshot.json> --baseline-capabilities <snapshot.json>] --out <new-directory>",
      "args": [
        {
          "name": "receipt.json",
          "description": "Receipt of the run after the fix.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "suite",
          "arg": "<suite.json>",
          "description": "The suite the receipt was produced from.",
          "default": "none"
        },
        {
          "name": "baseline",
          "arg": "<receipt.json>",
          "description": "Earlier receipt to compare with.",
          "default": "none"
        },
        {
          "name": "baseline-suite",
          "arg": "<suite.json>",
          "description": "The suite the baseline was produced from.",
          "default": "none"
        },
        {
          "name": "capabilities",
          "arg": "<snapshot.json>",
          "description": "Capability snapshot after the change.",
          "default": "none"
        },
        {
          "name": "baseline-capabilities",
          "arg": "<snapshot.json>",
          "description": "Capability snapshot before the change.",
          "default": "none"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn review after/receipt.json --suite suite.json --baseline before/receipt.json --baseline-suite suite.json --out out/review",
          "note": "Pull request summary of a verified fix."
        }
      ],
      "exit": {
        "0": "pass",
        "1": "findings or a requested change gate",
        "2": "usage error or invalid input",
        "3": "incomplete or unknown completion",
        "4": "execution or normalization failure"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "ci",
      "summary": "source checks plus requested SCA/DAST stages, artifacts and one CI exit",
      "usage": "keryn ci [path] --out <new-directory> [--base <ref-or-result>] [--rules <packs>] [--policy <file>] [stage options]",
      "args": [
        {
          "name": "path",
          "description": "Repository folder.",
          "required": false
        }
      ],
      "flags": [
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "jobs",
          "arg": "<n>",
          "description": "Stages run at a time, each in a child process, 1 to 64. Outputs are the same bytes at any value.",
          "default": "a quarter of the cores, at most 4"
        },
        {
          "name": "stage",
          "arg": "<name>",
          "description": "Run one stage in this process. Plumbing between Keryn's own processes.",
          "default": "none",
          "internal": true
        },
        {
          "name": "ai-baseline",
          "arg": "<receipt>",
          "description": "Compare the current AI run with reproduced before evidence.",
          "default": "none"
        },
        {
          "name": "ai-baseline-suite",
          "arg": "<suite>",
          "description": "The suite the AI baseline was produced from.",
          "default": "none"
        },
        {
          "name": "ai-tests",
          "arg": "<suite.json>",
          "description": "Run authenticated AI security regressions; the suite bytes are pinned at preflight.",
          "default": "none"
        },
        {
          "name": "application",
          "arg": "<id>",
          "description": "Caller binding; must match the AI test suite when given.",
          "default": "none"
        },
        {
          "name": "application-file",
          "arg": "<file>",
          "description": "Run every stage an application profile (keryn.dev/application/v1) declares.",
          "default": "<path>/.keryn/application.yml when present"
        },
        {
          "name": "no-application-file",
          "description": "Ignore .keryn/application.yml.",
          "default": "off"
        },
        {
          "name": "capabilities",
          "arg": "<config>",
          "description": "AI or MCP configuration to inspect.",
          "default": "none"
        },
        {
          "name": "capabilities-base",
          "arg": "<snapshot>",
          "description": "Earlier capability snapshot.",
          "default": "none"
        },
        {
          "name": "fail-on-expansion",
          "description": "Gate configuration authority changes against --capabilities-base.",
          "default": "off"
        },
        {
          "name": "sca",
          "description": "Also run the installed OSV-Scanner, offline.",
          "default": "off"
        },
        {
          "name": "sca-image",
          "arg": "<oci-layout|docker-archive.tar|reference>",
          "description": "Add an image SCA stage. A local layout or archive, or with --sca-image-pull a registry reference. The image is never executed.",
          "default": "none"
        },
        {
          "name": "sca-image-pull",
          "description": "Read the --sca-image reference from its registry over HTTPS (see keryn sca image --pull).",
          "default": "off"
        },
        {
          "name": "sca-image-platform",
          "arg": "<os/arch>",
          "description": "With --sca-image-pull: the platform of a multi-architecture image.",
          "default": "the image's only platform"
        },
        {
          "name": "sca-image-advisories",
          "arg": "<OSV-record-array.json>",
          "description": "Local advisory snapshot for --sca-image.",
          "default": "none"
        },
        {
          "name": "sca-online",
          "description": "Permit advisory requests for the SCA stage.",
          "default": "off"
        },
        {
          "name": "sca-collect",
          "description": "Collect all OSV packages and advisories in one offline invocation.",
          "default": "off"
        },
        {
          "name": "sca-context",
          "arg": "<deployment>",
          "description": "Bind explicit AI roles.",
          "default": "none"
        },
        {
          "name": "sca-snapshot",
          "arg": "<file>",
          "description": "Advisory snapshot identity.",
          "default": "none"
        },
        {
          "name": "sca-as-of",
          "arg": "<UTC-ISO>",
          "description": "Instant for freshness calculation.",
          "default": "none"
        },
        {
          "name": "sca-inventory",
          "arg": "<report>",
          "description": "Import OSV JSON or CycloneDX inventory instead of a vulnerability report.",
          "default": "none"
        },
        {
          "name": "sca-bindings",
          "arg": "<file>",
          "description": "Explicit AI roles for --sca-inventory.",
          "default": "none"
        },
        {
          "name": "sca-inventory-complete",
          "description": "Attest that the input inventory report is a complete collection.",
          "default": "off"
        },
        {
          "name": "sca-report",
          "arg": "<report>",
          "description": "Import an SCA report instead of running one.",
          "default": "none"
        },
        {
          "name": "sca-parser",
          "arg": "<id>",
          "description": "Format of --sca-report.",
          "default": "detected"
        },
        {
          "name": "sca-completion",
          "arg": "complete|partial|unknown|failed",
          "description": "Completion of --sca-report.",
          "default": "unknown"
        },
        {
          "name": "dast-url",
          "arg": "<url>",
          "description": "Run installed ZAP spider and passive checks against it.",
          "default": "none"
        },
        {
          "name": "dast-ownership",
          "arg": "<challenge.json>",
          "description": "Locally minted ownership challenge for --dast-active; current publication is checked before execution.",
          "default": "required with --dast-active"
        },
        {
          "name": "dast-active",
          "description": "Opt into active ZAP checks after fresh ownership verification.",
          "default": "off"
        },
        {
          "name": "dast-ajax",
          "description": "Pass --ajax to the DAST scan stage: also run ZAP's AJAX spider in a local headless browser.",
          "default": "off"
        },
        {
          "name": "dast-auth",
          "arg": "<auth.json>",
          "description": "Header-env authenticated ZAP discovery and verification.",
          "default": "none"
        },
        {
          "name": "dast-report",
          "arg": "<report.xml>",
          "description": "Import a Burp or ZAP report instead; needs --dast-url and --dast-parser.",
          "default": "none"
        },
        {
          "name": "dast-parser",
          "arg": "burp|zap",
          "description": "Format of --dast-report.",
          "default": "required with --dast-report"
        },
        {
          "name": "dast-completion",
          "arg": "complete|partial|unknown|failed",
          "description": "Completion of --dast-report.",
          "default": "unknown"
        },
        {
          "name": "max-artifact-size",
          "arg": "<bytes>",
          "description": "Per-artifact cap for profile artifacts without maxBytes.",
          "default": "67108864 (64 MiB)"
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn ci . --out out/ci --base origin/main",
          "note": "Source analysis with cross-file analysis; if cross-file analysis is incomplete, it exits 3."
        },
        {
          "command": "keryn ci . --out out/ci --sca --dast-url https://staging.example.com",
          "note": "Add dependency and web stages."
        },
        {
          "command": "keryn ci . --out out/ci --application-file .keryn/application.yml --jobs 2",
          "note": "Run every stage an application profile declares."
        }
      ],
      "exit": {
        "0": "pass",
        "1": "findings",
        "2": "usage or configuration error",
        "3": "incomplete",
        "4": "execution failure",
        "10": "warnings"
      },
      "notes": [
        "Exit precedence: 4 execution, 2 usage, 3 incomplete, 1 findings, 10 warnings, 0 pass."
      ],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "ledger build",
      "summary": "merge every stage of keryn ci runs into one reproducible findings ledger",
      "usage": "keryn ledger build <run-or-stage-dir>... --out <new-file.json> [--json]",
      "args": [
        {
          "name": "run-or-stage-dir",
          "description": "keryn ci run directories or single stage directories.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "out",
          "arg": "<new-file.json>",
          "description": "Where build writes the ledger.",
          "default": "required",
          "commands": [
            "build"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn ledger build out/ci --out ledger.json",
          "note": "Same inputs give the same bytes."
        }
      ],
      "exit": {
        "0": "written",
        "2": "usage error or unreadable input"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "ledger diff",
      "summary": "compare two ledgers: new, fixed, unchanged, changed severity",
      "usage": "keryn ledger diff <old-ledger.json> <new-ledger.json> [--json]",
      "args": [
        {
          "name": "old-ledger.json",
          "description": "Earlier ledger.",
          "required": true
        },
        {
          "name": "new-ledger.json",
          "description": "Later ledger.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn ledger diff old/ledger.json new/ledger.json",
          "note": "What changed between two runs."
        }
      ],
      "exit": {
        "0": "nothing new and no severity raised",
        "1": "new or raised, or an observed-flow entry seen at more places than before",
        "2": "usage error"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "application validate",
      "summary": "check an application profile (.keryn/application.yml) against its schema",
      "usage": "keryn application validate [file] [--json]",
      "args": [
        {
          "name": "file",
          "description": "Profile file.",
          "required": false
        }
      ],
      "flags": [
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn application validate",
          "note": "Check .keryn/application.yml."
        }
      ],
      "exit": {
        "0": "valid",
        "1": "problems",
        "2": "unreadable"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "application show",
      "summary": "the stages keryn ci --application-file would run for a profile",
      "usage": "keryn application show [file] [--root <repository>] [--json]",
      "args": [
        {
          "name": "file",
          "description": "Profile file.",
          "required": false
        }
      ],
      "flags": [
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "root",
          "arg": "<repository>",
          "description": "Repository the profile's paths are relative to.",
          "default": "the folder holding .keryn/, else the profile's folder",
          "commands": [
            "show"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn application show --root .",
          "note": "Stages, artifact sizes and sha256, and every input it would skip. Nothing is contacted."
        }
      ],
      "exit": {
        "0": "shown",
        "2": "unreadable"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "workflow analyze",
      "summary": "n8n / Flowise / Langflow / SimStudio / MCP / OpenAPI / CrewAI / LangChain / OpenAI Agents export -> findings, evidence, gate",
      "usage": "keryn workflow analyze <export.json|export.yaml> [--platform <id>] [--evidence-dir <dir>] [options]",
      "args": [
        {
          "name": "export",
          "description": "Workflow export, read locally and never run.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "platform",
          "arg": "<id>",
          "description": "Platform of the export (see keryn workflow platforms).",
          "default": "detected from the export's shape",
          "commands": [
            "workflow analyze"
          ]
        },
        {
          "name": "evidence-dir",
          "arg": "<dir>",
          "description": "Also write the markdown, mermaid, CSV, threat model and SARIF artifacts here.",
          "default": "none",
          "commands": [
            "workflow analyze"
          ]
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn workflow analyze flow.json --evidence-dir out/workflow",
          "note": "Findings plus threat model and diagrams."
        },
        {
          "command": "keryn workflow analyze flow.json --platform n8n --fail-on warning",
          "note": "Name the platform and gate on warnings."
        }
      ],
      "exit": {
        "0": "pass: nothing at or above --fail-on, coverage complete",
        "1": "violations: findings at or above --fail-on, or a policy violation",
        "2": "usage or configuration error",
        "3": "coverage incomplete: a rule was unsupported, partial or timed out (--allow-incomplete opts out)",
        "4": "internal error or timeout",
        "10": "pass with warnings (only with --exit-warn)"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "workflow platforms",
      "summary": "the workflow export formats the analyzer reads",
      "usage": "keryn workflow platforms",
      "args": [],
      "flags": [],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn workflow platforms",
          "note": "Platform ids for --platform."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error or unreadable input"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "artifact analyze",
      "summary": "binary / strings triage (MCP servers, agent helpers, CLIs) and model files (pickle, PyTorch, joblib, NumPy, Keras, TensorFlow, safetensors, GGUF, ONNX): capabilities, secrets, prompts -> findings, reports, gate",
      "usage": "keryn artifact analyze <file|package> [--kind binary|text|metadata_json] [--report-dir <dir>] [--manifest <file|->] [--no-unpack] [--max-artifact-size <bytes>] [options]",
      "args": [
        {
          "name": "file|package",
          "description": "Binary, strings dump, metadata JSON, or a release package (.deb, .rpm, AppImage, tar, zip, .vsix, .xpi, .jar, .whl, .nupkg, .apk).",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "kind",
          "arg": "binary|text|metadata_json",
          "description": "How to read the input.",
          "default": "detected",
          "commands": [
            "artifact analyze"
          ]
        },
        {
          "name": "report-dir",
          "arg": "<dir>",
          "description": "Also write the markdown, public-safe summary, IOC JSON, YARA draft and full analysis JSON.",
          "default": "none",
          "commands": [
            "artifact analyze"
          ]
        },
        {
          "name": "manifest",
          "arg": "<file|->",
          "description": "Write the member manifest (sizes, sha256, metadata, helpers). `-` is stdout.",
          "default": "none",
          "commands": [
            "artifact analyze"
          ]
        },
        {
          "name": "no-unpack",
          "description": "Analyse the file as is instead of unpacking a release package.",
          "default": "off",
          "commands": [
            "artifact analyze"
          ]
        },
        {
          "name": "max-artifact-size",
          "arg": "<bytes>",
          "description": "Per-artifact cap: the file, or each package member. Larger non-executable members are listed, not analysed (exit 3). Executables are never refused for size; past 256 MiB they are read in 2 MiB windows.",
          "default": "67108864 (64 MiB), at most 1 GiB",
          "commands": [
            "artifact analyze"
          ]
        },
        {
          "name": "max-strings",
          "arg": "<n>",
          "description": "Most strings extracted.",
          "default": "50000",
          "commands": [
            "artifact analyze"
          ]
        },
        {
          "name": "min-string-length",
          "arg": "<n>",
          "description": "Shortest string extracted.",
          "default": "5",
          "commands": [
            "artifact analyze"
          ]
        },
        {
          "name": "no-redact",
          "description": "Do not redact extracted strings.",
          "default": "off: strings are redacted",
          "commands": [
            "artifact analyze"
          ]
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn artifact analyze ./my-mcp-server --report-dir out/artifact",
          "note": "Triage a compiled MCP server without running it."
        },
        {
          "command": "keryn artifact analyze release.deb --manifest -",
          "note": "Analyse every member of a package and print the manifest."
        }
      ],
      "exit": {
        "0": "pass: nothing at or above --fail-on, coverage complete",
        "1": "violations: findings at or above --fail-on, or a policy violation",
        "2": "usage or configuration error",
        "3": "coverage incomplete: a rule was unsupported, partial or timed out (--allow-incomplete opts out)",
        "4": "internal error or timeout",
        "10": "pass with warnings (only with --exit-warn)"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "artifact rules",
      "summary": "the artifact rule set this build runs",
      "usage": "keryn artifact rules",
      "args": [],
      "flags": [],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn artifact rules",
          "note": "List the rules."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error or unreadable input"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "trust scan",
      "summary": "public trust surface scorecard of a website from a prepared input (the browser extension crawls; the CLI never fetches)",
      "usage": "keryn trust scan <trust-input.json> [options]",
      "args": [
        {
          "name": "trust-input.json",
          "description": "The page set the Keryn browser extension writes with Download scan input.",
          "required": true
        }
      ],
      "flags": [],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn trust scan trust-input.json --sarif trust.sarif",
          "note": "Score the site's public trust surface."
        }
      ],
      "exit": {
        "0": "pass: nothing at or above --fail-on, coverage complete",
        "1": "violations: findings at or above --fail-on, or a policy violation",
        "2": "usage or configuration error",
        "3": "coverage incomplete: a rule was unsupported, partial or timed out (--allow-incomplete opts out)",
        "4": "internal error or timeout",
        "10": "pass with warnings (only with --exit-warn)"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "trust detectors",
      "summary": "the trust-surface detectors and what each checks",
      "usage": "keryn trust detectors",
      "args": [],
      "flags": [],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn trust detectors",
          "note": "List detectors."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error or unreadable input"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "stack analyze",
      "summary": "AI technologies a captured web page loads (1,000+ entry catalog) + DOM exposure -> AI-BOM, findings, policy, gate",
      "usage": "keryn stack analyze <snapshot.json> [options]",
      "args": [
        {
          "name": "snapshot.json",
          "description": "A page snapshot from the browser extension.",
          "required": true
        }
      ],
      "flags": [],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn stack analyze snapshot.json --aibom page.cdx.json",
          "note": "AI-BOM with basis observed-in-browser."
        }
      ],
      "exit": {
        "0": "pass: nothing at or above --fail-on, coverage complete",
        "1": "violations: findings at or above --fail-on, or a policy violation",
        "2": "usage or configuration error",
        "3": "coverage incomplete: a rule was unsupported, partial or timed out (--allow-incomplete opts out)",
        "4": "internal error or timeout",
        "10": "pass with warnings (only with --exit-warn)"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "stack catalog",
      "summary": "the AI technology catalog the page-stack analysis matches against",
      "usage": "keryn stack catalog",
      "args": [],
      "flags": [],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn stack catalog",
          "note": "List the catalog."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error or unreadable input"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "forensics scan",
      "summary": "AI forensics of a repository tree (stacks, prompt files, tool definitions, RAG, model artifacts, routes, controls, risks) -> findings, gate",
      "usage": "keryn forensics scan <path> [options]",
      "args": [
        {
          "name": "path",
          "description": "Repository folder.",
          "required": true
        }
      ],
      "flags": [],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn forensics scan . --sarif forensics.sarif",
          "note": "Risks gate and write like audit findings."
        }
      ],
      "exit": {
        "0": "pass: nothing at or above --fail-on, coverage complete",
        "1": "violations: findings at or above --fail-on, or a policy violation",
        "2": "usage or configuration error",
        "3": "coverage incomplete: a rule was unsupported, partial or timed out (--allow-incomplete opts out)",
        "4": "internal error or timeout",
        "10": "pass with warnings (only with --exit-warn)"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "forensics report",
      "summary": "the forensics engine's full JSON for a repository tree",
      "usage": "keryn forensics report <path>",
      "args": [
        {
          "name": "path",
          "description": "Repository folder.",
          "required": true
        }
      ],
      "flags": [],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn forensics report . > forensics.json",
          "note": "Engine JSON on stdout."
        }
      ],
      "exit": {
        "0": "pass: nothing at or above --fail-on, coverage complete",
        "1": "violations: findings at or above --fail-on, or a policy violation",
        "2": "usage or configuration error",
        "3": "coverage incomplete: a rule was unsupported, partial or timed out (--allow-incomplete opts out)",
        "4": "internal error or timeout",
        "10": "pass with warnings (only with --exit-warn)"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "attribution scan",
      "summary": "AI tool use and AI-assisted commits of a repository, per repo, developer and org, with time series -> findings, report, gate",
      "usage": "keryn attribution scan <path> [options]",
      "args": [
        {
          "name": "path",
          "description": "Repository folder (a git work tree for the history signals).",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "repository",
          "arg": "<owner/repo>",
          "description": "Repository identity for AI usage policy outside trusted pull-request CI.",
          "default": "none",
          "commands": [
            "attribution scan"
          ]
        },
        {
          "name": "max-commits",
          "arg": "<n>",
          "description": "Most commits read from the history, newest first. A cut history says so in the report.",
          "default": "20000",
          "commands": [
            "attribution scan"
          ]
        },
        {
          "name": "since",
          "arg": "<date>",
          "description": "Only commits after this date (anything `git log --since` accepts, for example 2026-01-01 or 6.months).",
          "default": "the whole history",
          "commands": [
            "attribution scan"
          ]
        },
        {
          "name": "ref",
          "arg": "<ref>",
          "description": "The branch, tag or commit whose history is read.",
          "default": "HEAD",
          "commands": [
            "attribution scan"
          ]
        },
        {
          "name": "all-branches",
          "description": "Read every branch instead of one ref.",
          "default": "off",
          "commands": [
            "attribution scan"
          ]
        },
        {
          "name": "no-history",
          "description": "Read the working tree only: tool configuration and instruction files, no commit signals.",
          "default": "off",
          "commands": [
            "attribution scan"
          ]
        },
        {
          "name": "no-notes",
          "description": "Do not read Git AI authorship notes (refs/notes/ai) even when the repository has them.",
          "default": "off",
          "commands": [
            "attribution scan"
          ]
        },
        {
          "name": "bucket",
          "arg": "month|week",
          "description": "Bucket of the time series.",
          "default": "month",
          "commands": [
            "attribution scan",
            "attribution org"
          ]
        },
        {
          "name": "developers",
          "arg": "aliases|identities",
          "description": "Add per-developer rows to the report. Sensitive: aliases are keyed hashes of the commit identity, identities show name and email. Off by default; share the result with administrators only.",
          "default": "off: no per-developer rows",
          "commands": [
            "attribution scan"
          ]
        },
        {
          "name": "salt",
          "arg": "<string>",
          "description": "Key of the developer aliases. Use one per organisation so a person keeps the same alias in every repository and over time.",
          "default": "derived from this run, so aliases differ between runs",
          "commands": [
            "attribution scan"
          ]
        },
        {
          "name": "weak-signals",
          "description": "Also read the experimental style signals (low confidence, listed apart, never counted in the headline numbers).",
          "default": "off",
          "commands": [
            "attribution scan"
          ]
        },
        {
          "name": "report",
          "arg": "<file>",
          "description": "Write the full attribution report as JSON (per repository, time series, per-developer rows when asked). `-` is stdout.",
          "default": "none",
          "commands": [
            "attribution scan",
            "attribution org"
          ]
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn attribution scan . --report attribution.json",
          "note": "Tool configuration and commit declarations, with confidence and evidence, and the full report as JSON."
        },
        {
          "command": "keryn attribution scan . --since 6.months --sarif attribution.sarif",
          "note": "Recent history only; the INFO findings go to code scanning."
        },
        {
          "command": "keryn attribution scan . --policy .keryn/policy.yml --repository example/platform --json result.json",
          "note": "Evaluate organization AI usage rules and report violations with evidence."
        }
      ],
      "exit": {
        "0": "pass: nothing at or above --fail-on, coverage complete",
        "1": "violations: findings at or above --fail-on, or a policy violation",
        "2": "usage or configuration error",
        "3": "coverage incomplete: a rule was unsupported, partial or timed out (--allow-incomplete opts out)",
        "4": "internal error or timeout",
        "10": "pass with warnings (only with --exit-warn)"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "attribution pr",
      "summary": "summarize AI attribution and enforce the base policy on a GitHub pull request",
      "usage": "keryn attribution pr --event <github-event.json> --markdown <file> [--annotations]",
      "args": [],
      "flags": [
        {
          "name": "event",
          "arg": "<github-event.json>",
          "description": "GitHub pull request event with the base, head and labels.",
          "default": "none",
          "commands": [
            "attribution pr"
          ]
        },
        {
          "name": "markdown",
          "arg": "<file>",
          "description": "Write the pull request attribution summary to this file.",
          "default": "none",
          "commands": [
            "attribution pr"
          ]
        },
        {
          "name": "annotations",
          "description": "Emit GitHub Actions annotations for attribution observations and policy findings.",
          "default": "off",
          "commands": [
            "attribution pr"
          ]
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn attribution pr --event event.json --markdown attribution.md --annotations",
          "note": "Write the pull request summary and annotate policy violations."
        }
      ],
      "exit": {
        "0": "policy passed",
        "1": "policy violation",
        "2": "invalid inputs or incomplete Git history"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "attribution org",
      "summary": "several repositories' attribution reports -> the organisation's numbers and series",
      "usage": "keryn attribution org <report.json...> [options]",
      "args": [
        {
          "name": "report.json",
          "description": "Reports written by keryn attribution scan --report; one per repository.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "bucket",
          "arg": "month|week",
          "description": "Bucket of the time series.",
          "default": "month",
          "commands": [
            "attribution scan",
            "attribution org"
          ]
        },
        {
          "name": "report",
          "arg": "<file>",
          "description": "Write the full attribution report as JSON (per repository, time series, per-developer rows when asked). `-` is stdout.",
          "default": "none",
          "commands": [
            "attribution scan",
            "attribution org"
          ]
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn attribution org api.json web.json --report org.json",
          "note": "Adds the repositories together and merges the time series."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error or unreadable input"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "attribution rules",
      "summary": "the attribution rule catalogue: tools, signals, confidence",
      "usage": "keryn attribution rules",
      "args": [],
      "flags": [],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn attribution rules",
          "note": "Every rule with its tool, channel and confidence."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error or unreadable input"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "surface classify",
      "summary": "self-hosted AI infrastructure classified from observed ports -> AI-BOM (observed-on-network), findings, policy, gate",
      "usage": "keryn surface classify <observed-ports.json> [options]",
      "args": [
        {
          "name": "observed-ports.json",
          "description": "Network observations. Nothing is probed.",
          "required": true
        }
      ],
      "flags": [],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn surface classify observed-ports.json --aibom surface.cdx.json",
          "note": "Ollama, vLLM, n8n, MCP servers and more from ports you already observed."
        }
      ],
      "exit": {
        "0": "pass: nothing at or above --fail-on, coverage complete",
        "1": "violations: findings at or above --fail-on, or a policy violation",
        "2": "usage or configuration error",
        "3": "coverage incomplete: a rule was unsupported, partial or timed out (--allow-incomplete opts out)",
        "4": "internal error or timeout",
        "10": "pass with warnings (only with --exit-warn)"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "surface signatures",
      "summary": "the service signatures surface classification uses",
      "usage": "keryn surface signatures",
      "args": [],
      "flags": [],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn surface signatures",
          "note": "List the signatures."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error or unreadable input"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "forge scan",
      "summary": "scan a jar, a class directory or a .NET assembly with every shipped rule: findings with their path, SARIF and a gate",
      "usage": "keryn forge scan <jar|class directory|dll>... [--sarif <file>] [--json <file>] [--fail-on error|warning|none] [--accept-missing-deps all|<prefix,...>] [--allow-incomplete]",
      "args": [
        {
          "name": "input",
          "description": "Compiled code: a .jar or .war, a directory of .class files, a .NET assembly. Read from disk, never executed.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "limits",
          "arg": "<limits.json>",
          "description": "JSON file of analysis limits.",
          "default": "built-in limits",
          "commands": [
            "forge query",
            "forge scan"
          ]
        },
        {
          "name": "partition-prefix",
          "arg": "<path prefix>",
          "description": "Analyse each class whose file name starts with this prefix (with its inner classes) as its own program, together with every input outside the prefix, and merge the results. Names are relative to the directory given, for example org/acme/web/. Taint cannot pass between two such classes through a shared helper, and the work grows linearly with their number.",
          "default": "none: one analysis over all inputs",
          "commands": [
            "forge scan"
          ]
        },
        {
          "name": "engine-json",
          "arg": "<file>",
          "description": "Also write the engine's own keryn.dev/forge-scan/v1 document (every flow and unknown verdict, per-rule coverage), the form the benchmark scorer reads.",
          "default": "not written",
          "commands": [
            "forge scan"
          ]
        },
        {
          "name": "accept-missing-deps",
          "arg": "<all|prefix,...>",
          "description": "Treat referenced classes that are not among the inputs as outside the analysed program: all, or a comma list of internal-name prefixes (org/springframework/). Echoed in coverage; calls into them that no model covers stay unknown.",
          "default": "none: a missing dependency makes the run incomplete",
          "commands": [
            "forge scan"
          ]
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn forge scan build/libs/app.jar --accept-missing-deps all --sarif forge.sarif",
          "note": "Flows from request values to sinks in the application's own classes, libraries treated as outside it."
        }
      ],
      "exit": {
        "0": "the gate passed, with no finding at or above --fail-on and any incomplete coverage accepted",
        "1": "a flow at or above --fail-on",
        "2": "usage error or an input that cannot be read",
        "3": "incomplete: an unknown pair, a rule cut short, a missing dependency, an unread input (all accepted by --allow-incomplete), or the analysis budget",
        "4": "engine failure, or the forge module is not built",
        "10": "with --exit-warn, the gate passed with warnings or accepted incomplete coverage"
      },
      "notes": [
        "An unknown verdict is never shown as clean: it is counted in coverage with its reason.",
        "Line numbers need debug information in the compiled inputs."
      ],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "forge capabilities",
      "summary": "frontends and features this build has, with their status",
      "usage": "keryn forge capabilities",
      "args": [],
      "flags": [],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn forge capabilities",
          "note": "What this build can analyse."
        }
      ],
      "exit": {
        "0": "ok",
        "2": "usage error",
        "4": "internal error or forge exports not built"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "forge analyze",
      "summary": "read files into fact bundles and print {bundles, stats, unclaimed}",
      "usage": "keryn forge analyze <path...> [--bundle <bundles.json>...] [--out <bundles.json>]",
      "args": [
        {
          "name": "path",
          "description": "Files or folders to read.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "bundle",
          "arg": "<bundles.json>",
          "description": "A pre-made fact bundle to add to the analysis.",
          "default": "none",
          "repeatable": true,
          "commands": [
            "forge analyze"
          ]
        },
        {
          "name": "out",
          "arg": "<bundles.json>",
          "description": "Write the bundles here (summary on stderr) so query and export can read them.",
          "default": "stdout",
          "commands": [
            "forge analyze"
          ]
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn forge analyze src --out bundles.json",
          "note": "Build bundles for later queries."
        }
      ],
      "exit": {
        "0": "ok",
        "2": "usage or caller error",
        "3": "budget exhausted",
        "4": "internal error"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "forge query",
      "summary": "run a KSQL rule over the graph rebuilt from the bundles",
      "usage": "keryn forge query <bundles.json> <rule.ksql> [--limits <limits.json>]",
      "args": [
        {
          "name": "bundles.json",
          "description": "From forge analyze.",
          "required": true
        },
        {
          "name": "rule.ksql",
          "description": "Rule file.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "limits",
          "arg": "<limits.json>",
          "description": "JSON file of analysis limits.",
          "default": "built-in limits",
          "commands": [
            "forge query",
            "forge scan"
          ]
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn forge query bundles.json rule.ksql",
          "note": "A keryn.dev/ksql-result/v1 document: flow, unknown, no_flow. Unknown is never clean."
        }
      ],
      "exit": {
        "0": "ok",
        "2": "usage or caller error",
        "3": "budget exhausted",
        "4": "internal error"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "forge dfd",
      "summary": "the data-flow and authority projection and the trust-canvas document",
      "usage": "keryn forge dfd <bundles.json>",
      "args": [
        {
          "name": "bundles.json",
          "description": "From forge analyze.",
          "required": true
        }
      ],
      "flags": [],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn forge dfd bundles.json",
          "note": "{projection, trust_model}."
        }
      ],
      "exit": {
        "0": "ok",
        "2": "usage or caller error",
        "4": "internal error"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "forge export",
      "summary": "the canonical keryn.dev/forge-graph/v1 document",
      "usage": "keryn forge export <bundles.json>",
      "args": [
        {
          "name": "bundles.json",
          "description": "From forge analyze.",
          "required": true
        }
      ],
      "flags": [],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn forge export bundles.json > graph.json",
          "note": "Byte-identical across native and wasm."
        }
      ],
      "exit": {
        "0": "ok",
        "2": "usage or caller error",
        "4": "internal error"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "authority propose",
      "summary": "staged runtime policy proposed from a scan report with cross-file analysis, at the authority each finding's sink proves",
      "usage": "keryn authority propose <seceng-report.json> [--out <policy.json>] [--enforce] [--min-blast-radius <n>] [--policy-version <v>]",
      "args": [
        {
          "name": "report",
          "description": "A Deep scan report.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "out",
          "arg": "<policy.json>",
          "description": "Where propose writes the staged policy.",
          "default": "stdout",
          "commands": [
            "authority propose"
          ]
        },
        {
          "name": "enforce",
          "description": "Propose an enforcing policy instead of an observing one.",
          "default": "off",
          "commands": [
            "authority propose"
          ]
        },
        {
          "name": "min-blast-radius",
          "arg": "<n>",
          "description": "Smallest blast radius a finding needs to produce a rule.",
          "default": "the engine default",
          "commands": [
            "authority propose"
          ]
        },
        {
          "name": "policy-version",
          "arg": "<v>",
          "description": "Version string written into the policy.",
          "default": "the engine default",
          "commands": [
            "authority propose"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn authority propose report.json --out policy.json",
          "note": "Staged policy for review."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error or unreadable input"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "authority decide",
      "summary": "one tool-call verdict from a policy and a request",
      "usage": "keryn authority decide --policy <policy.json> --request <request.json> [--now <unix-seconds>]",
      "args": [],
      "flags": [
        {
          "name": "policy",
          "arg": "<policy.json>",
          "description": "Policy to decide against.",
          "default": "required",
          "commands": [
            "authority decide"
          ]
        },
        {
          "name": "request",
          "arg": "<request.json>",
          "description": "The tool-call request.",
          "default": "required",
          "commands": [
            "authority decide"
          ]
        },
        {
          "name": "now",
          "arg": "<unix-seconds>",
          "description": "Clock for budgets. Budgets use this, never the system clock, when given.",
          "default": "the current time",
          "commands": [
            "authority decide"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn authority decide --policy policy.json --request request.json",
          "note": "Allowed, blocked or held for approval."
        }
      ],
      "exit": {
        "0": "allowed",
        "1": "blocked or held for approval",
        "2": "usage error"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "authority verify",
      "summary": "verify a hash-chained decision log",
      "usage": "keryn authority verify <records.json|.jsonl>",
      "args": [
        {
          "name": "records",
          "description": "Decision log.",
          "required": true
        }
      ],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn authority verify decisions.jsonl",
          "note": "Exit 1 on any break in the chain."
        }
      ],
      "exit": {
        "0": "chain intact",
        "1": "a break was found",
        "2": "usage error"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "authority compile",
      "summary": "lint a policy, count its rules and print the digest an operator can pin",
      "usage": "keryn authority compile <policy.json>",
      "args": [
        {
          "name": "policy.json",
          "description": "Policy file.",
          "required": true
        }
      ],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn authority compile policy.json",
          "note": "Digest to pin."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error or unreadable input"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "authority vocabulary",
      "summary": "capabilities, guards, trust labels and the embedded sink registry",
      "usage": "keryn authority vocabulary",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn authority vocabulary",
          "note": "What a policy can name."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error or unreadable input"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "mcp inventory",
      "summary": "MCP tools from a tools/list response judged for risk (schema, permissions, side effects, poisoning) -> findings, gate",
      "usage": "keryn mcp inventory <tools-list.json> [--requests <server-url>] [options]\n       keryn mcp inventory --example",
      "args": [
        {
          "name": "tools-list.json",
          "description": "A saved tools/list response. The server is never contacted.",
          "required": false
        }
      ],
      "flags": [
        {
          "name": "example",
          "description": "Judge the tool list of the Keryn demo MCP server (api.keryn.app/demo/mcp): one poisoned, one over-broad and one clean tool.",
          "default": "off",
          "commands": [
            "mcp inventory"
          ]
        },
        {
          "name": "requests",
          "arg": "<server-url>",
          "description": "Also print, as JSON, the JSON-RPC requests ZAP's MCP importer would send for the tool list. Nothing is sent.",
          "default": "none",
          "commands": [
            "mcp inventory"
          ]
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn mcp inventory --example",
          "note": "Judge the Keryn demo MCP server on a first run."
        },
        {
          "command": "keryn mcp inventory tools.json --sarif mcp.sarif",
          "note": "Gate a saved tool list."
        }
      ],
      "exit": {
        "0": "pass: nothing at or above --fail-on, coverage complete",
        "1": "violations: findings at or above --fail-on, or a policy violation",
        "2": "usage or configuration error",
        "3": "coverage incomplete: a rule was unsupported, partial or timed out (--allow-incomplete opts out)",
        "4": "internal error or timeout",
        "10": "pass with warnings (only with --exit-warn)"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": [
        "KERYN_MCP_GUARD"
      ]
    },
    {
      "path": "mcp pin",
      "summary": "write keryn-mcp.lock.json: SHA-256 of each tool's name, description and schema",
      "usage": "keryn mcp pin <tools-list.json> [--server <name>] [--lock <file>]",
      "args": [
        {
          "name": "tools-list.json",
          "description": "A tools list, or {mcpServers:{name:{tools}}}.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "lock",
          "arg": "<file>",
          "description": "Lock file for pin and check.",
          "default": "keryn-mcp.lock.json",
          "commands": [
            "mcp pin",
            "mcp check"
          ]
        },
        {
          "name": "server",
          "arg": "<name>",
          "description": "Name of the single server a tools list belongs to.",
          "default": "none",
          "commands": [
            "mcp pin",
            "mcp check"
          ]
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn mcp pin tools.json --server search",
          "note": "Pin one server's tools."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error or unreadable input"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": [
        "KERYN_MCP_GUARD"
      ]
    },
    {
      "path": "mcp check",
      "summary": "compare a tools list with the lock: added, removed or changed tools",
      "usage": "keryn mcp check <tools-list.json> [--server <name>] [--lock <file>] [options]",
      "args": [
        {
          "name": "tools-list.json",
          "description": "Current tools list.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "lock",
          "arg": "<file>",
          "description": "Lock file for pin and check.",
          "default": "keryn-mcp.lock.json",
          "commands": [
            "mcp pin",
            "mcp check"
          ]
        },
        {
          "name": "server",
          "arg": "<name>",
          "description": "Name of the single server a tools list belongs to.",
          "default": "none",
          "commands": [
            "mcp pin",
            "mcp check"
          ]
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn mcp check tools.json --server search",
          "note": "A changed description is an error (rug pull); other drift is a warning."
        }
      ],
      "exit": {
        "0": "pass: nothing at or above --fail-on, coverage complete",
        "1": "violations: findings at or above --fail-on, or a policy violation",
        "2": "usage or configuration error",
        "3": "coverage incomplete: a rule was unsupported, partial or timed out (--allow-incomplete opts out)",
        "4": "internal error or timeout",
        "10": "pass with warnings (only with --exit-warn)"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": [
        "KERYN_MCP_GUARD"
      ]
    },
    {
      "path": "mcp manifest",
      "summary": "screen an MCP registry server.json or a Claude Desktop extension manifest.json",
      "usage": "keryn mcp manifest <server.json|manifest.json> [--kind registry|dxt] [options]",
      "args": [
        {
          "name": "manifest",
          "description": "server.json or manifest.json.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "kind",
          "arg": "registry|dxt",
          "description": "Manifest kind.",
          "default": "detected",
          "commands": [
            "mcp manifest"
          ]
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn mcp manifest server.json",
          "note": "Shape, unpinned packages, plain-http or unauthenticated remotes, broad permissions."
        }
      ],
      "exit": {
        "0": "pass: nothing at or above --fail-on, coverage complete",
        "1": "violations: findings at or above --fail-on, or a policy violation",
        "2": "usage or configuration error",
        "3": "coverage incomplete: a rule was unsupported, partial or timed out (--allow-incomplete opts out)",
        "4": "internal error or timeout",
        "10": "pass with warnings (only with --exit-warn)"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": [
        "KERYN_MCP_GUARD"
      ]
    },
    {
      "path": "mcp servers",
      "summary": "list the MCP servers a repository's client configs name",
      "usage": "keryn mcp servers <dir>",
      "args": [
        {
          "name": "dir",
          "description": "Repository folder.",
          "required": true
        }
      ],
      "flags": [],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn mcp servers .",
          "note": "From .mcp.json, .cursor/mcp.json, .vscode/mcp.json and the like."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error or unreadable input"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": [
        "KERYN_MCP_GUARD"
      ]
    },
    {
      "path": "mcp audit",
      "summary": "audit the MCP servers the AI clients on this machine would start; never writes or starts anything",
      "usage": "keryn mcp audit [<home dir>] [outputs]",
      "args": [
        {
          "name": "home dir",
          "description": "Another home directory to audit, such as a mounted profile.",
          "required": false
        }
      ],
      "flags": [],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn mcp audit",
          "note": "Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Gemini CLI, Continue."
        }
      ],
      "exit": {
        "0": "pass: nothing at or above --fail-on, coverage complete",
        "1": "violations: findings at or above --fail-on, or a policy violation",
        "2": "usage or configuration error",
        "3": "coverage incomplete: a rule was unsupported, partial or timed out (--allow-incomplete opts out)",
        "4": "internal error or timeout",
        "10": "pass with warnings (only with --exit-warn)"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": [
        "KERYN_MCP_GUARD"
      ]
    },
    {
      "path": "mcp wrap",
      "summary": "print a client config with every stdio server behind keryn mcp guard",
      "usage": "keryn mcp wrap <config.json> --policy <file> [--log <file>] [-o <out.json>]",
      "args": [
        {
          "name": "config.json",
          "description": "MCP client config.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "policy",
          "arg": "<file>",
          "description": "Guard policy file (for wrap and guard).",
          "default": "required",
          "commands": [
            "mcp wrap",
            "mcp guard"
          ]
        },
        {
          "name": "log",
          "arg": "<file>",
          "description": "Decision log written by the guard.",
          "default": "~/.keryn/mcp-decisions.jsonl",
          "commands": [
            "mcp wrap"
          ]
        },
        {
          "name": "out",
          "short": "o",
          "arg": "<out.json>",
          "description": "Write the wrapped client config here. The input is never overwritten.",
          "default": "stdout",
          "commands": [
            "mcp wrap"
          ]
        },
        {
          "name": "keryn",
          "arg": "<path>",
          "description": "The keryn executable the wrapped servers call.",
          "default": "the running keryn",
          "commands": [
            "mcp wrap"
          ]
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn mcp wrap ~/.cursor/mcp.json --policy policy.json -o mcp.guarded.json",
          "note": "Remote servers are listed and left alone."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error or unreadable input"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": [
        "KERYN_MCP_GUARD"
      ]
    },
    {
      "path": "mcp guard",
      "summary": "stdio proxy that checks every tools/call against a policy; fails open unless told otherwise",
      "usage": "keryn mcp guard --policy <file> [guard options] -- <server command...>",
      "args": [],
      "flags": [
        {
          "name": "policy",
          "arg": "<file>",
          "description": "Guard policy file (for wrap and guard).",
          "default": "required",
          "commands": [
            "mcp wrap",
            "mcp guard"
          ]
        }
      ],
      "acceptsScanFlags": true,
      "examples": [
        {
          "command": "keryn mcp guard --policy policy.json -- npx -y @acme/server",
          "note": "Run a server behind the guard. Guard options: keryn-mcp-guard --help."
        }
      ],
      "exit": {
        "0": "the proxied server exited cleanly",
        "2": "usage error",
        "4": "guard could not start"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": [
        "KERYN_MCP_GUARD"
      ]
    },
    {
      "path": "graph",
      "summary": "Throughline graph pipeline over an evidence project: attack paths, defensive breakpoints, report (local only)",
      "usage": "keryn graph [arguments and flags: keryn graph --help]",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn graph --help",
          "note": "Arguments and flags, from the keryn-native binary that runs this command."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [
        "Runs in keryn-native, which ships beside keryn in the release archives. Without it the command exits 2 with a hint."
      ],
      "runsIn": "keryn-native",
      "environment": []
    },
    {
      "path": "diff-scan",
      "summary": "attack paths introduced or resolved between two git refs of a repository",
      "usage": "keryn diff-scan [arguments and flags: keryn diff-scan --help]",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn diff-scan --help",
          "note": "Arguments and flags, from the keryn-native binary that runs this command."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [
        "Runs in keryn-native, which ships beside keryn in the release archives. Without it the command exits 2 with a hint."
      ],
      "runsIn": "keryn-native",
      "environment": []
    },
    {
      "path": "report",
      "summary": "final report artifacts (report.md, manifest, split reports) from an existing scan output directory",
      "usage": "keryn report [arguments and flags: keryn report --help]",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn report --help",
          "note": "Arguments and flags, from the keryn-native binary that runs this command."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [
        "Runs in keryn-native, which ships beside keryn in the release archives. Without it the command exits 2 with a hint."
      ],
      "runsIn": "keryn-native",
      "environment": []
    },
    {
      "path": "evidence",
      "summary": "build or inspect the evidence bundle of a finding",
      "usage": "keryn evidence [arguments and flags: keryn evidence --help]",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn evidence --help",
          "note": "Arguments and flags, from the keryn-native binary that runs this command."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [
        "Runs in keryn-native, which ships beside keryn in the release archives. Without it the command exits 2 with a hint."
      ],
      "runsIn": "keryn-native",
      "environment": []
    },
    {
      "path": "validate",
      "summary": "generate or check a local-only validation plan for a finding candidate",
      "usage": "keryn validate [arguments and flags: keryn validate --help]",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn validate --help",
          "note": "Arguments and flags, from the keryn-native binary that runs this command."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [
        "Runs in keryn-native, which ships beside keryn in the release archives. Without it the command exits 2 with a hint."
      ],
      "runsIn": "keryn-native",
      "environment": []
    },
    {
      "path": "triage",
      "summary": "apply the false-positive downgrade rules to a candidate finding",
      "usage": "keryn triage [arguments and flags: keryn triage --help]",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn triage --help",
          "note": "Arguments and flags, from the keryn-native binary that runs this command."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [
        "Runs in keryn-native, which ships beside keryn in the release archives. Without it the command exits 2 with a hint."
      ],
      "runsIn": "keryn-native",
      "environment": []
    },
    {
      "path": "verify",
      "summary": "reproduce a finding in a hardened sandbox container: Confirmed, Refuted or Indeterminate",
      "usage": "keryn verify [arguments and flags: keryn verify --help]",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn verify --help",
          "note": "Arguments and flags, from the keryn-native binary that runs this command."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [
        "Runs in keryn-native, which ships beside keryn in the release archives. Without it the command exits 2 with a hint."
      ],
      "runsIn": "keryn-native",
      "environment": []
    },
    {
      "path": "adjudicate",
      "summary": "run a reviewer over ledger findings, see the queue, inspect one finding per reviewer (claims, never decisions)",
      "usage": "keryn adjudicate [arguments and flags: keryn adjudicate --help]",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn adjudicate --help",
          "note": "Arguments and flags, from the keryn-native binary that runs this command."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [
        "Runs in keryn-native, which ships beside keryn in the release archives. Without it the command exits 2 with a hint."
      ],
      "runsIn": "keryn-native",
      "environment": []
    },
    {
      "path": "remediate",
      "summary": "propose fixes for ledger findings and check the code each one names is there (never writes a repository)",
      "usage": "keryn remediate [arguments and flags: keryn remediate --help]",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn remediate --help",
          "note": "Arguments and flags, from the keryn-native binary that runs this command."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [
        "Runs in keryn-native, which ships beside keryn in the release archives. Without it the command exits 2 with a hint."
      ],
      "runsIn": "keryn-native",
      "environment": []
    },
    {
      "path": "explore",
      "summary": "read the ledger: findings, scans, targets, judgements, fixes, retests, rulings, disclosures (JSON)",
      "usage": "keryn explore [arguments and flags: keryn explore --help]",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn explore --help",
          "note": "Arguments and flags, from the keryn-native binary that runs this command."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [
        "Runs in keryn-native, which ships beside keryn in the release archives. Without it the command exits 2 with a hint."
      ],
      "runsIn": "keryn-native",
      "environment": []
    },
    {
      "path": "measure",
      "summary": "measure the estate: coverage, observation-to-disclosure funnel, reviewer spend, source value",
      "usage": "keryn measure [arguments and flags: keryn measure --help]",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn measure --help",
          "note": "Arguments and flags, from the keryn-native binary that runs this command."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [
        "Runs in keryn-native, which ships beside keryn in the release archives. Without it the command exits 2 with a hint."
      ],
      "runsIn": "keryn-native",
      "environment": []
    },
    {
      "path": "retention",
      "summary": "enforce a retention window on the local profile, or erase it",
      "usage": "keryn retention [arguments and flags: keryn retention --help]",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn retention --help",
          "note": "Arguments and flags, from the keryn-native binary that runs this command."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [
        "Runs in keryn-native, which ships beside keryn in the release archives. Without it the command exits 2 with a hint."
      ],
      "runsIn": "keryn-native",
      "environment": []
    },
    {
      "path": "analyze",
      "summary": "enrich one partner finding from a JSON file (the POST /v1/analysis engine)",
      "usage": "keryn analyze [arguments and flags: keryn analyze --help]",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn analyze --help",
          "note": "Arguments and flags, from the keryn-native binary that runs this command."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [
        "Runs in keryn-native, which ships beside keryn in the release archives. Without it the command exits 2 with a hint."
      ],
      "runsIn": "keryn-native",
      "environment": []
    },
    {
      "path": "dom-analysis",
      "summary": "captured DOM -> AI overread, PII exposure and prompt injection report",
      "usage": "keryn dom-analysis [arguments and flags: keryn dom-analysis --help]",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn dom-analysis --help",
          "note": "Arguments and flags, from the keryn-native binary that runs this command."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [
        "Runs in keryn-native, which ships beside keryn in the release archives. Without it the command exits 2 with a hint."
      ],
      "runsIn": "keryn-native",
      "environment": []
    },
    {
      "path": "doctor",
      "summary": "check (and safely fix) the local Keryn environment",
      "usage": "keryn doctor [arguments and flags: keryn doctor --help]",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn doctor --help",
          "note": "Arguments and flags, from the keryn-native binary that runs this command."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [
        "Runs in keryn-native, which ships beside keryn in the release archives. Without it the command exits 2 with a hint."
      ],
      "runsIn": "keryn-native",
      "environment": []
    },
    {
      "path": "attest",
      "summary": "sign evidence, a Verify packet or an AI-BOM as an in-toto statement in a DSSE envelope; attest keygen",
      "usage": "keryn attest [arguments and flags: keryn attest --help]",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn attest --help",
          "note": "Arguments and flags, from the keryn-native binary that runs this command."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [
        "Runs in keryn-native, which ships beside keryn in the release archives. Without it the command exits 2 with a hint."
      ],
      "runsIn": "keryn-native",
      "environment": []
    },
    {
      "path": "verify-attestation",
      "summary": "verify an attestation signature and that the evidence in hand is what was signed",
      "usage": "keryn verify-attestation [arguments and flags: keryn verify-attestation --help]",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn verify-attestation --help",
          "note": "Arguments and flags, from the keryn-native binary that runs this command."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [
        "Runs in keryn-native, which ships beside keryn in the release archives. Without it the command exits 2 with a hint."
      ],
      "runsIn": "keryn-native",
      "environment": []
    },
    {
      "path": "oscal",
      "summary": "OSCAL 1.2 assessment results for a scan result (observations only, not a compliance determination)",
      "usage": "keryn oscal [arguments and flags: keryn oscal --help]",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn oscal --help",
          "note": "Arguments and flags, from the keryn-native binary that runs this command."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [
        "Runs in keryn-native, which ships beside keryn in the release archives. Without it the command exits 2 with a hint."
      ],
      "runsIn": "keryn-native",
      "environment": []
    },
    {
      "path": "nday-db",
      "summary": "update the known-fix (n-day) signature database from a signed release",
      "usage": "keryn nday-db [arguments and flags: keryn nday-db --help]",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn nday-db --help",
          "note": "Arguments and flags, from the keryn-native binary that runs this command."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [
        "Runs in keryn-native, which ships beside keryn in the release archives. Without it the command exits 2 with a hint."
      ],
      "runsIn": "keryn-native",
      "environment": []
    },
    {
      "path": "sca-assess",
      "summary": "assess OSV records and package queries from one bounded JSON batch on stdin",
      "usage": "keryn sca-assess [arguments and flags: keryn sca-assess --help]",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn sca-assess --help",
          "note": "Arguments and flags, from the keryn-native binary that runs this command."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [
        "Runs in keryn-native, which ships beside keryn in the release archives. Without it the command exits 2 with a hint."
      ],
      "runsIn": "keryn-native",
      "environment": []
    },
    {
      "path": "sca-inventory",
      "summary": "inventory lockfile/metadata text from stdin (no files, network or state; 1 MiB cap)",
      "usage": "keryn sca-inventory [arguments and flags: keryn sca-inventory --help]",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn sca-inventory --help",
          "note": "Arguments and flags, from the keryn-native binary that runs this command."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [
        "Runs in keryn-native, which ships beside keryn in the release archives. Without it the command exits 2 with a hint."
      ],
      "runsIn": "keryn-native",
      "environment": []
    },
    {
      "path": "sca-match",
      "summary": "match lockfile/metadata text from stdin against supplied OSV records",
      "usage": "keryn sca-match [arguments and flags: keryn sca-match --help]",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn sca-match --help",
          "note": "Arguments and flags, from the keryn-native binary that runs this command."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [
        "Runs in keryn-native, which ships beside keryn in the release archives. Without it the command exits 2 with a hint."
      ],
      "runsIn": "keryn-native",
      "environment": []
    },
    {
      "path": "sca-requirements",
      "summary": "check installed npm declarations in a package-lock v2/v3 on stdin",
      "usage": "keryn sca-requirements [arguments and flags: keryn sca-requirements --help]",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn sca-requirements --help",
          "note": "Arguments and flags, from the keryn-native binary that runs this command."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [
        "Runs in keryn-native, which ships beside keryn in the release archives. Without it the command exits 2 with a hint."
      ],
      "runsIn": "keryn-native",
      "environment": []
    },
    {
      "path": "sca-project-assets",
      "summary": "observe one recorded NuGet graph from a bounded project.assets.json on stdin",
      "usage": "keryn sca-project-assets [arguments and flags: keryn sca-project-assets --help]",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn sca-project-assets --help",
          "note": "Arguments and flags, from the keryn-native binary that runs this command."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [
        "Runs in keryn-native, which ships beside keryn in the release archives. Without it the command exits 2 with a hint."
      ],
      "runsIn": "keryn-native",
      "environment": []
    },
    {
      "path": "fw-policy-observe",
      "summary": "observe fixed package-firewall predicates from bounded raw job JSON on stdin",
      "usage": "keryn fw-policy-observe [arguments and flags: keryn fw-policy-observe --help]",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn fw-policy-observe --help",
          "note": "Arguments and flags, from the keryn-native binary that runs this command."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [
        "Runs in keryn-native, which ships beside keryn in the release archives. Without it the command exits 2 with a hint."
      ],
      "runsIn": "keryn-native",
      "environment": []
    },
    {
      "path": "jvm-liveness",
      "summary": "physical-cell liveness of one method in JVM class or JAR bytes on stdin",
      "usage": "keryn jvm-liveness [arguments and flags: keryn jvm-liveness --help]",
      "args": [],
      "flags": [],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn jvm-liveness --help",
          "note": "Arguments and flags, from the keryn-native binary that runs this command."
        }
      ],
      "exit": {
        "0": "success",
        "2": "usage error",
        "4": "internal error"
      },
      "notes": [
        "Runs in keryn-native, which ships beside keryn in the release archives. Without it the command exits 2 with a hint."
      ],
      "runsIn": "keryn-native",
      "environment": []
    },
    {
      "path": "evidence-import modelscan",
      "summary": "Import a ModelScan report bound to exact artifact bytes.",
      "usage": "keryn evidence-import modelscan <sidecar.json> --native <report.json> --artifact <file> --out <new-directory>",
      "args": [],
      "flags": [
        {
          "name": "native",
          "arg": "<report.json>",
          "description": "Exact native assessment to bind.",
          "default": "required"
        },
        {
          "name": "artifact",
          "arg": "<local-file>",
          "description": "Hash artifact bytes without loading or executing them.",
          "default": "required for modelscan"
        },
        {
          "name": "config",
          "arg": "<config-file>",
          "description": "Hash promptfoo config; never execute it.",
          "default": "required for promptfoo"
        },
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "include-content",
          "description": "Include exchange content in the local export; may contain secrets.",
          "default": "off"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn evidence-import modelscan model-evidence.json --native native.json --artifact model.pkl --out model-evidence",
          "note": "Validate caller-attested binding and retain a separate receipt."
        }
      ],
      "exit": {
        "0": "Evidence recorded; no proof promotion or release approval is issued.",
        "1": "Model scanner reported issues; evidence retained.",
        "2": "Invalid input or binding.",
        "3": "Artifact unassessed."
      },
      "notes": [
        "Requires the next CLI release after 0.5.2. No scanner or model loader executes. Unsupported, failed or incomplete inspections remain unassessed."
      ],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "evidence-import promptfoo",
      "summary": "Import pinned dynamic-test evidence without changing proof or verdict.",
      "usage": "keryn evidence-import promptfoo <sidecar.json> --native <report.json> --config <file> --out <new-directory> [--include-content]",
      "args": [],
      "flags": [
        {
          "name": "native",
          "arg": "<report.json>",
          "description": "Exact native assessment to bind.",
          "default": "required"
        },
        {
          "name": "artifact",
          "arg": "<local-file>",
          "description": "Hash artifact bytes without loading or executing them.",
          "default": "required for modelscan"
        },
        {
          "name": "config",
          "arg": "<config-file>",
          "description": "Hash promptfoo config; never execute it.",
          "default": "required for promptfoo"
        },
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "include-content",
          "description": "Include exchange content in the local export; may contain secrets.",
          "default": "off"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn evidence-import promptfoo dynamic-evidence.json --native native.json --config promptfooconfig.yaml --out dynamic-evidence",
          "note": "Keep producer outcomes as linked claims; do not promote proof."
        }
      ],
      "exit": {
        "0": "Evidence recorded; no proof promotion or release approval is issued.",
        "1": "Model scanner reported issues; evidence retained.",
        "2": "Invalid input or binding.",
        "3": "Artifact unassessed."
      },
      "notes": [
        "Requires the next CLI release after 0.5.2. Exact target/report/config and finding bindings are required; exchange content is omitted by default. No provider, assertion or plugin executes."
      ],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "evidence-import candidate",
      "summary": "Validate an unverified proposal for the shared local verifier.",
      "usage": "keryn evidence-import candidate <candidate.json> --native <report.json> --out <new-directory>",
      "args": [],
      "flags": [
        {
          "name": "native",
          "arg": "<report.json>",
          "description": "Exact native assessment to bind.",
          "default": "required"
        },
        {
          "name": "artifact",
          "arg": "<local-file>",
          "description": "Hash artifact bytes without loading or executing them.",
          "default": "required for modelscan"
        },
        {
          "name": "config",
          "arg": "<config-file>",
          "description": "Hash promptfoo config; never execute it.",
          "default": "required for promptfoo"
        },
        {
          "name": "out",
          "arg": "<new-directory>",
          "description": "Directory to write artifacts to. Must not exist or must be empty.",
          "default": "required"
        },
        {
          "name": "json",
          "description": "Print the machine-readable receipt or result as JSON on stdout.",
          "default": "off"
        },
        {
          "name": "include-content",
          "description": "Include exchange content in the local export; may contain secrets.",
          "default": "off"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn evidence-import candidate candidate.json --native native.json --out candidate-evidence",
          "note": "Record a proposal; verification is a separate explicit step."
        }
      ],
      "exit": {
        "0": "Evidence recorded; no proof promotion or release approval is issued.",
        "1": "Model scanner reported issues; evidence retained.",
        "2": "Invalid input or binding.",
        "3": "Artifact unassessed."
      },
      "notes": [
        "Requires the next CLI release after 0.5.2. Review the exact patch and rationale in Finding detail, then choose the matching original snapshot and run the verifier. No build or test command executes."
      ],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "revalidate inputs",
      "summary": "Derive the build inventory and the affected packages from a Keryn result JSON, bound to a build.",
      "usage": "keryn revalidate inputs <result.json> <binding.json> [--out <file>]",
      "args": [],
      "flags": [
        {
          "name": "now",
          "arg": "<iso-time>",
          "description": "The time the explanation or verdict is made at. Evidence older than 72 hours before it is not used.",
          "default": "required for affectedness and intervention"
        },
        {
          "name": "vex",
          "arg": "<file>",
          "description": "A supplier VEX document, kept as attributed claims beside the edges; repeatable. It changes no edge.",
          "default": "none"
        },
        {
          "name": "out",
          "arg": "<file>",
          "description": "Write the JSON result to this file instead of standard output.",
          "default": "none"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn revalidate inputs result.json binding.json --out inputs.json",
          "note": "Then: keryn revalidate affectedness inputs.json observation.json --now <iso-time>."
        }
      ],
      "exit": {
        "0": "Computed, and the result is complete.",
        "2": "Unreadable or malformed input.",
        "3": "Computed, and the result says it is incomplete: a plan that could not bound an affected set, a subject still stale, a verdict that is inconclusive or not comparable.",
        "4": "Internal error."
      },
      "notes": [
        "Requires the next CLI release after 0.5.2. Offline and read-only: reads JSON files and writes JSON. Nothing is scanned, sent, executed or approved, and no release decision changes.",
        "The binding is {tenant, product, build: {sha256, revision}, origin}: what a scan cannot know about the build. Components are the result's locked packages with an exact identity; affected packages are its dependency findings, one per advisory. A package whose ecosystem has no purl type is listed as unresolved and left out (exit 3), never given a guessed identity. `keryn revalidate affectedness` accepts the file this writes in place of the inventory and affected files."
      ],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "revalidate affectedness",
      "summary": "Explain which deployment an advisory may affect: advisory to component to build to observed deployment, each edge with how it is known.",
      "usage": "keryn revalidate affectedness <inventory.json> <affected.json> [<observation.json>...] --now <iso-time> [--vex <file>]... [--out <file>]",
      "args": [],
      "flags": [
        {
          "name": "now",
          "arg": "<iso-time>",
          "description": "The time the explanation or verdict is made at. Evidence older than 72 hours before it is not used.",
          "default": "required for affectedness and intervention"
        },
        {
          "name": "vex",
          "arg": "<file>",
          "description": "A supplier VEX document, kept as attributed claims beside the edges; repeatable. It changes no edge.",
          "default": "none"
        },
        {
          "name": "out",
          "arg": "<file>",
          "description": "Write the JSON result to this file instead of standard output.",
          "default": "none"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn revalidate affectedness inventory.json affected.json observation.json --now 2026-11-18T12:00:00Z --out affectedness.json",
          "note": "One build, the packages advisories name, one deployed-assets observation."
        }
      ],
      "exit": {
        "0": "Computed, and the result is complete.",
        "2": "Unreadable or malformed input.",
        "3": "Computed, and the result says it is incomplete: a plan that could not bound an affected set, a subject still stale, a verdict that is inconclusive or not comparable.",
        "4": "Internal error."
      },
      "notes": [
        "Requires the next CLI release after 0.5.2. Offline and read-only: reads JSON files and writes JSON. Nothing is scanned, sent, executed or approved, and no release decision changes.",
        "The inventory is keryn.dev/build-inventory/v1; each observation holds a keryn.dev/deployed-assets/v1 receipt. Edges are exact, inferred, ambiguous, contradiction or unknown. A near identity (another version, ecosystem or qualifier) is listed and never matched; a failed join never removes an advisory. A match says the captured assets are this build, not that anything is reachable or exploitable."
      ],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "revalidate plan",
      "summary": "Turn a changed advisory, build or deployment binding, or authority into a bounded list of checks to run again.",
      "usage": "keryn revalidate plan <input.json> [--out <file>]",
      "args": [],
      "flags": [
        {
          "name": "now",
          "arg": "<iso-time>",
          "description": "The time the explanation or verdict is made at. Evidence older than 72 hours before it is not used.",
          "default": "required for affectedness and intervention"
        },
        {
          "name": "vex",
          "arg": "<file>",
          "description": "A supplier VEX document, kept as attributed claims beside the edges; repeatable. It changes no edge.",
          "default": "none"
        },
        {
          "name": "out",
          "arg": "<file>",
          "description": "Write the JSON result to this file instead of standard output.",
          "default": "none"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn revalidate plan changes.json --out retest-plan.json",
          "note": "Plan only; running the checks is a separate, authorized step."
        }
      ],
      "exit": {
        "0": "Computed, and the result is complete.",
        "2": "Unreadable or malformed input.",
        "3": "Computed, and the result says it is incomplete: a plan that could not bound an affected set, a subject still stale, a verdict that is inconclusive or not comparable.",
        "4": "Internal error."
      },
      "notes": [
        "Requires the next CLI release after 0.5.2. Offline and read-only: reads JSON files and writes JSON. Nothing is scanned, sent, executed or approved, and no release decision changes.",
        "The input is {tenant, events, subjects, providers}. The plan (keryn.dev/retest-plan/v1) authorizes nothing: every item says authorization is checked again at execution. Duplicate, older and out-of-order events change nothing. An affected set that cannot be bounded gives explicit full rechecks and exit 3, never an empty plan."
      ],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "revalidate apply",
      "summary": "Say which planned subjects were really retested by a set of results.",
      "usage": "keryn revalidate apply <plan.json> <results.json> [--out <file>]",
      "args": [],
      "flags": [
        {
          "name": "now",
          "arg": "<iso-time>",
          "description": "The time the explanation or verdict is made at. Evidence older than 72 hours before it is not used.",
          "default": "required for affectedness and intervention"
        },
        {
          "name": "vex",
          "arg": "<file>",
          "description": "A supplier VEX document, kept as attributed claims beside the edges; repeatable. It changes no edge.",
          "default": "none"
        },
        {
          "name": "out",
          "arg": "<file>",
          "description": "Write the JSON result to this file instead of standard output.",
          "default": "none"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn revalidate apply retest-plan.json results.json",
          "note": "Exit 3 while any planned subject is still stale."
        }
      ],
      "exit": {
        "0": "Computed, and the result is complete.",
        "2": "Unreadable or malformed input.",
        "3": "Computed, and the result says it is incomplete: a plan that could not bound an affected set, a subject still stale, a verdict that is inconclusive or not comparable.",
        "4": "Internal error."
      },
      "notes": [
        "Requires the next CLI release after 0.5.2. Offline and read-only: reads JSON files and writes JSON. Nothing is scanned, sent, executed or approved, and no release decision changes.",
        "The results file is {plannedAt, results}. A carried or cached result, a result from before the plan, another check, profile or version, and a check that did not complete (tool unavailable, authorization lost, interrupted, out of scope, human handoff) leave the subject stale. The release decision is never changed."
      ],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "revalidate intervention",
      "summary": "Judge a proposed breakpoint against a baseline run, a run after the change and an optional run after a rollback.",
      "usage": "keryn revalidate intervention <input.json> --now <iso-time> [--out <file>]",
      "args": [],
      "flags": [
        {
          "name": "now",
          "arg": "<iso-time>",
          "description": "The time the explanation or verdict is made at. Evidence older than 72 hours before it is not used.",
          "default": "required for affectedness and intervention"
        },
        {
          "name": "vex",
          "arg": "<file>",
          "description": "A supplier VEX document, kept as attributed claims beside the edges; repeatable. It changes no edge.",
          "default": "none"
        },
        {
          "name": "out",
          "arg": "<file>",
          "description": "Write the JSON result to this file instead of standard output.",
          "default": "none"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn revalidate intervention intervention.json --now 2026-11-18T12:00:00Z",
          "note": "Exit 3 when the verdict is inconclusive or not comparable."
        }
      ],
      "exit": {
        "0": "Computed, and the result is complete.",
        "2": "Unreadable or malformed input.",
        "3": "Computed, and the result says it is incomplete: a plan that could not bound an affected set, a subject still stale, a verdict that is inconclusive or not comparable.",
        "4": "Internal error."
      },
      "notes": [
        "Requires the next CLI release after 0.5.2. Offline and read-only: reads JSON files and writes JSON. Nothing is scanned, sent, executed or approved, and no release decision changes.",
        "The input is {record, baseline, after, rollback, retest, alternativePaths}; the record is keryn.dev/intervention/v1. Outcomes: still observed, verified within the tested scope, mitigated within the tested scope with the source defect retained, not comparable, inconclusive, reappeared. A prediction, a pass label or a tool assertion establishes nothing, and one path stopping never closes the path family."
      ],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "detection replay",
      "summary": "Replay one Sigma single-event rule against supplied events into a sealed receipt with precision and recall over the labelled events.",
      "usage": "keryn detection replay <input.json> | --rule <rule.yml> --observations <batch.json>... [--labels <file>] [--save-input <file>] [--receipt <file|->] [--export <file>] [--timeout <seconds>]",
      "args": [
        {
          "name": "input.json",
          "description": "{rule, mapping: {id, observed}, events: [{id, event, label?}], source_complete?, cohort?}; or use --rule with --observations",
          "required": false
        }
      ],
      "flags": [
        {
          "name": "receipt",
          "arg": "<file|->",
          "description": "Write the sealed receipt; - prints it to stdout and the summary to stderr.",
          "default": "none: only the summary is printed",
          "commands": [
            "detection replay"
          ]
        },
        {
          "name": "export",
          "arg": "<file>",
          "description": "Write the receipt as evidence: one item of a keryn-export/1 file, whose id is the sha256 of the receipt.",
          "default": "none",
          "commands": [
            "detection replay"
          ]
        },
        {
          "name": "rule",
          "arg": "<rule.yml>",
          "description": "A Sigma rule to replay over --observations.",
          "default": "none",
          "commands": [
            "detection replay"
          ]
        },
        {
          "name": "observations",
          "arg": "<batch.json>",
          "description": "An AI observation batch (keryn.dev/ai-observations/v1) replayed under the ai-observations-sigma/0 mapping.",
          "default": "none",
          "commands": [
            "detection replay"
          ],
          "repeatable": true
        },
        {
          "name": "labels",
          "arg": "<file>",
          "description": "JSON object of event id (run/case/trial/sequence) to match or no_match, for precision and recall.",
          "default": "none: every event unlabelled",
          "commands": [
            "detection replay"
          ]
        },
        {
          "name": "save-input",
          "arg": "<file>",
          "description": "Write the replay input composed from --observations, for validate.",
          "default": "none",
          "commands": [
            "detection replay"
          ]
        },
        {
          "name": "timeout",
          "arg": "<seconds>",
          "description": "Stop the replay after this many seconds; it runs in a worker that is terminated, and no receipt is written.",
          "default": "60 (at most 3600)"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn detection replay replay-input.json --receipt receipt.json",
          "note": "Replay a labelled cohort and keep its receipt."
        },
        {
          "command": "keryn detection replay --rule outbound.yml --observations observations-0001.json --save-input input.json --receipt receipt.json",
          "note": "Replay a rule over the AI observation batches keryn ai-test saved."
        }
      ],
      "exit": {
        "0": "every event decided; receipt written",
        "2": "bad usage or an input the engine refuses to read",
        "3": "rule refused, an event incomplete or refused, the source declared incomplete, or the run stopped at --timeout (no receipt)"
      },
      "notes": [
        "Profile sigma-replay-spike/0 (sigma-rust 0.7.0): aggregation, correlation and time windows are refused. Every event is match, no match, incomplete or refused; a no-match over an incomplete source is provisional. Quality counts labelled events only and names its denominators. A fixture cohort supports no production detection claim."
      ],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "detection validate",
      "summary": "Check that a receipt is exactly the one its inputs give (re-runs the replay; any edit breaks its seal).",
      "usage": "keryn detection validate <input.json> <receipt.json | export.json>",
      "args": [
        {
          "name": "input.json",
          "description": "The replay input.",
          "required": true
        },
        {
          "name": "receipt.json",
          "description": "The receipt to check, or the keryn-export/1 file that carries it.",
          "required": true
        }
      ],
      "flags": [
        {
          "name": "timeout",
          "arg": "<seconds>",
          "description": "Stop the replay after this many seconds; it runs in a worker that is terminated, and no receipt is written.",
          "default": "60 (at most 3600)"
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn detection validate replay-input.json detection-receipt.json",
          "note": "Confirm a receipt someone handed you."
        }
      ],
      "exit": {
        "0": "valid",
        "1": "not the receipt these inputs give",
        "2": "an input or receipt that cannot be read"
      },
      "notes": [],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "aspm snapshot",
      "summary": "record what is known about one application now, from ledgers and scanner reports",
      "usage": "keryn aspm snapshot --estate <file> --app <id> --store <store> [--at <time>] [--ledger [<component>=]<ledger.json>]... [--report <stage>=<file>[:<parser>]]... [--run <dir>]... [--revision <revision>]... [--build <id>] [--paths <file>]",
      "args": [],
      "flags": [
        {
          "name": "estate",
          "arg": "<file>",
          "description": "The estate file (keryn.dev/estate/v1, YAML or JSON): applications, their components, owners, criticality and exposure.",
          "default": "required",
          "commands": [
            "snapshot",
            "gate",
            "priority",
            "report"
          ]
        },
        {
          "name": "app",
          "arg": "<id>",
          "description": "The application, by its id in the estate file.",
          "default": "required",
          "commands": [
            "snapshot",
            "compare",
            "gate",
            "priority"
          ]
        },
        {
          "name": "store",
          "arg": "<dir|sqlite:file>",
          "description": "Where snapshots are kept. A directory of snapshot files, or sqlite:<file> for one SQLite file. Both only ever gain snapshots.",
          "default": "required; compare and gate can take --before and --after instead"
        },
        {
          "name": "at",
          "arg": "<time>",
          "description": "The time the snapshot is taken, or the time gate, priority and report are worked out for: an ISO 8601 time, for example 2026-11-18T09:00:00Z.",
          "default": "now",
          "commands": [
            "snapshot",
            "gate",
            "priority",
            "report"
          ]
        },
        {
          "name": "ledger",
          "arg": "<[component=]ledger.json>",
          "description": "A findings ledger (keryn ledger build) to record. component= names the repository component the ledger is a scan of; needed when the application has several. An evidence.json beside ledger.json is digested when it matches.",
          "default": "none",
          "repeatable": true,
          "commands": [
            "snapshot"
          ]
        },
        {
          "name": "report",
          "arg": "<stage=file[:parser]>",
          "description": "An outside scanner report to record as the named stage, in any format keryn import reads. Name the parser when more than one claims the file; it is not guessed.",
          "default": "none",
          "repeatable": true,
          "commands": [
            "snapshot"
          ]
        },
        {
          "name": "run",
          "arg": "<dir>",
          "description": "A scanner run directory with a scan-run.json (keryn.dev/scan-run/v1): every step is recorded, including those that failed or were refused.",
          "default": "none",
          "repeatable": true,
          "commands": [
            "snapshot"
          ]
        },
        {
          "name": "revision",
          "arg": "<revision|component=revision>",
          "description": "The revision examined: one for the whole application, or one per component. A repair is verified only for a component whose revision both snapshots name.",
          "default": "unknown",
          "repeatable": true,
          "commands": [
            "snapshot"
          ]
        },
        {
          "name": "build",
          "arg": "<id>",
          "description": "The build examined, when the snapshot is of a built artifact.",
          "default": "unknown",
          "commands": [
            "snapshot"
          ]
        },
        {
          "name": "paths",
          "arg": "<file>",
          "description": "JSON object of stage name to {include, exclude} path selectors the stage was limited to, so a narrowed scan is not compared as a full one.",
          "default": "none: each stage covers its whole scope",
          "commands": [
            "snapshot"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn aspm snapshot --estate estate.yml --app shop --store aspm-store --ledger web=ledger.json --revision 4f2a9c1",
          "note": "Record the shop from the ledger of its web repository at one revision. Recording the same thing twice writes nothing."
        }
      ],
      "exit": {
        "0": "recorded, or already recorded",
        "2": "usage error, an unreadable input, or an input that does not belong to the application"
      },
      "notes": [
        "A directory of snapshot files, or sqlite:<file> for one SQLite file. Both only ever gain snapshots.",
        "A stage that did not complete is recorded as such with no entries, so its absence is visible later.",
        "At least one of --ledger, --report or --run is required."
      ],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "aspm compare",
      "summary": "say what happened to each earlier entry, without calling absence a repair",
      "usage": "keryn aspm compare --app <id> --store <store> | --before <snapshot.json> --after <snapshot.json> [--interventions <file>] [--decisions <file>] [--json]",
      "args": [],
      "flags": [
        {
          "name": "app",
          "arg": "<id>",
          "description": "The application, by its id in the estate file.",
          "default": "required",
          "commands": [
            "snapshot",
            "compare",
            "gate",
            "priority"
          ]
        },
        {
          "name": "store",
          "arg": "<dir|sqlite:file>",
          "description": "Where snapshots are kept. A directory of snapshot files, or sqlite:<file> for one SQLite file. Both only ever gain snapshots.",
          "default": "required; compare and gate can take --before and --after instead"
        },
        {
          "name": "before",
          "arg": "<snapshot.json>",
          "description": "The earlier snapshot file, to compare two files instead of the last two in a store.",
          "default": "the second-latest snapshot in --store",
          "commands": [
            "compare",
            "gate"
          ]
        },
        {
          "name": "after",
          "arg": "<snapshot.json>",
          "description": "The later snapshot file. Given together with --before.",
          "default": "the latest snapshot in --store",
          "commands": [
            "compare",
            "gate"
          ]
        },
        {
          "name": "interventions",
          "arg": "<file>",
          "description": "JSON list of changes made (repair or mitigation), each with the entry ids it addresses and the receipt that validates it. A claim without a receipt verifies nothing.",
          "default": "none",
          "commands": [
            "compare",
            "gate"
          ]
        },
        {
          "name": "decisions",
          "arg": "<file>",
          "description": "The decisions file (keryn.dev/decisions/v1, as keryn decide writes it). Live acceptances are shown as accepted residual risk; nothing is accepted here.",
          "default": "none",
          "commands": [
            "compare",
            "gate",
            "priority"
          ]
        },
        {
          "name": "json",
          "description": "Print the result as JSON instead of text: keryn.dev/outcome-comparison/v1, keryn.dev/gate-result/v1, keryn.dev/priority/v1 or keryn.dev/estate-report/v1.",
          "default": "off",
          "commands": [
            "compare",
            "gate",
            "priority",
            "report"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn aspm compare --app shop --store aspm-store",
          "note": "The last two snapshots of the shop: verified repair, mitigated, accepted, not observed, indeterminate, persists and new, with the reason for each."
        }
      ],
      "exit": {
        "0": "compared; the later snapshot has no new entries",
        "1": "the later snapshot has new entries",
        "2": "usage error, unreadable input, or fewer than two snapshots"
      },
      "notes": [
        "An entry that stops appearing is a verified repair only when the same stages ran again on the same inputs and scope and an intervention's validation receipt names it and what the later snapshot examined.",
        "Gone under the same looking with no receipt is 'not observed'. Gone when a stage is missing, failed, or had its inputs or scope changed is 'indeterminate', and the last supported claim stands.",
        "Every row carries its change class from the metric contract (introduced, newly-detected, continuing, reopened, cleared, not-comparable)."
      ],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "aspm gate",
      "summary": "a check a pipeline can stop on: fail, blocked or pass, where a stage that did not run is never a pass",
      "usage": "keryn aspm gate --estate <file> --app <id> --store <store> | --estate <file> --before <snapshot.json> --after <snapshot.json> [--policy <file>] [--interventions <file>] [--decisions <file>] [--epss <file>] [--kev <file>] [--at <time>] [--json]",
      "args": [],
      "flags": [
        {
          "name": "estate",
          "arg": "<file>",
          "description": "The estate file (keryn.dev/estate/v1, YAML or JSON): applications, their components, owners, criticality and exposure.",
          "default": "required",
          "commands": [
            "snapshot",
            "gate",
            "priority",
            "report"
          ]
        },
        {
          "name": "app",
          "arg": "<id>",
          "description": "The application, by its id in the estate file.",
          "default": "required",
          "commands": [
            "snapshot",
            "compare",
            "gate",
            "priority"
          ]
        },
        {
          "name": "store",
          "arg": "<dir|sqlite:file>",
          "description": "Where snapshots are kept. A directory of snapshot files, or sqlite:<file> for one SQLite file. Both only ever gain snapshots.",
          "default": "required; compare and gate can take --before and --after instead"
        },
        {
          "name": "at",
          "arg": "<time>",
          "description": "The time the snapshot is taken, or the time gate, priority and report are worked out for: an ISO 8601 time, for example 2026-11-18T09:00:00Z.",
          "default": "now",
          "commands": [
            "snapshot",
            "gate",
            "priority",
            "report"
          ]
        },
        {
          "name": "before",
          "arg": "<snapshot.json>",
          "description": "The earlier snapshot file, to compare two files instead of the last two in a store.",
          "default": "the second-latest snapshot in --store",
          "commands": [
            "compare",
            "gate"
          ]
        },
        {
          "name": "after",
          "arg": "<snapshot.json>",
          "description": "The later snapshot file. Given together with --before.",
          "default": "the latest snapshot in --store",
          "commands": [
            "compare",
            "gate"
          ]
        },
        {
          "name": "interventions",
          "arg": "<file>",
          "description": "JSON list of changes made (repair or mitigation), each with the entry ids it addresses and the receipt that validates it. A claim without a receipt verifies nothing.",
          "default": "none",
          "commands": [
            "compare",
            "gate"
          ]
        },
        {
          "name": "decisions",
          "arg": "<file>",
          "description": "The decisions file (keryn.dev/decisions/v1, as keryn decide writes it). Live acceptances are shown as accepted residual risk; nothing is accepted here.",
          "default": "none",
          "commands": [
            "compare",
            "gate",
            "priority"
          ]
        },
        {
          "name": "policy",
          "arg": "<file>",
          "description": "A gate policy file (keryn.dev/aspm-gate/v1, YAML or JSON): new_act_tier and fixed_without_repair (fail, warn or off), looking_reduced, inputs_changed and expected_kinds (fail or warn). An unknown key or value is refused. No key covers a stage that did not run: that always blocks.",
          "default": "new_act_tier, fixed_without_repair, looking_reduced and expected_kinds fail; inputs_changed warns",
          "commands": [
            "gate"
          ]
        },
        {
          "name": "epss",
          "arg": "<file>",
          "description": "EPSS scores: the daily CSV FIRST publishes (cve,epss,percentile). Without it exploitation likelihood is unknown and says so.",
          "default": "not supplied",
          "commands": [
            "gate",
            "priority",
            "report"
          ]
        },
        {
          "name": "kev",
          "arg": "<file>",
          "description": "The CISA Known Exploited Vulnerabilities catalogue (known_exploited_vulnerabilities.json). Without it known exploitation is unknown and says so.",
          "default": "not supplied",
          "commands": [
            "gate",
            "priority",
            "report"
          ]
        },
        {
          "name": "json",
          "description": "Print the result as JSON instead of text: keryn.dev/outcome-comparison/v1, keryn.dev/gate-result/v1, keryn.dev/priority/v1 or keryn.dev/estate-report/v1.",
          "default": "off",
          "commands": [
            "compare",
            "gate",
            "priority",
            "report"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn aspm gate --estate estate.yml --app shop --store aspm-store",
          "note": "The last two snapshots of the shop. Fails on a new act-tier entry or a decision that says fixed without a verified repair; blocked when a stage did not run again, did not finish or had its reach cut. Here the source stage of the recorded run did not finish, so the answer is blocked, exit 3."
        }
      ],
      "exit": {
        "0": "pass: nothing shown broken, and every stage ran to its end on both sides",
        "1": "fail: a new act-tier entry, or a decision that says fixed without a verified repair",
        "2": "usage error, unreadable input, an unknown policy key, or fewer than two snapshots",
        "3": "blocked: nothing was shown broken, and the looking was not whole"
      },
      "notes": [
        "A scan that failed reports nothing new. The gate is then blocked, not passed, and no policy setting changes that.",
        "Blocked by default as well: a narrowed scope, a coverage record showing less was run or read, and a stage kind the application expects that nothing examined. A changed tool, rule pack or advisory database is a warning by default.",
        "A new entry settled by a live acceptance is a warning; it fails again when the acceptance has expired.",
        "A pass says what the two snapshots support. It is not a release decision: a person makes that."
      ],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "aspm priority",
      "summary": "the ordered work list of an application, with the basis of every position",
      "usage": "keryn aspm priority --estate <file> --app <id> --store <store> [--at <time>] [--epss <file>] [--kev <file>] [--decisions <file>] [--json]",
      "args": [],
      "flags": [
        {
          "name": "estate",
          "arg": "<file>",
          "description": "The estate file (keryn.dev/estate/v1, YAML or JSON): applications, their components, owners, criticality and exposure.",
          "default": "required",
          "commands": [
            "snapshot",
            "gate",
            "priority",
            "report"
          ]
        },
        {
          "name": "app",
          "arg": "<id>",
          "description": "The application, by its id in the estate file.",
          "default": "required",
          "commands": [
            "snapshot",
            "compare",
            "gate",
            "priority"
          ]
        },
        {
          "name": "store",
          "arg": "<dir|sqlite:file>",
          "description": "Where snapshots are kept. A directory of snapshot files, or sqlite:<file> for one SQLite file. Both only ever gain snapshots.",
          "default": "required; compare and gate can take --before and --after instead"
        },
        {
          "name": "at",
          "arg": "<time>",
          "description": "The time the snapshot is taken, or the time gate, priority and report are worked out for: an ISO 8601 time, for example 2026-11-18T09:00:00Z.",
          "default": "now",
          "commands": [
            "snapshot",
            "gate",
            "priority",
            "report"
          ]
        },
        {
          "name": "decisions",
          "arg": "<file>",
          "description": "The decisions file (keryn.dev/decisions/v1, as keryn decide writes it). Live acceptances are shown as accepted residual risk; nothing is accepted here.",
          "default": "none",
          "commands": [
            "compare",
            "gate",
            "priority"
          ]
        },
        {
          "name": "epss",
          "arg": "<file>",
          "description": "EPSS scores: the daily CSV FIRST publishes (cve,epss,percentile). Without it exploitation likelihood is unknown and says so.",
          "default": "not supplied",
          "commands": [
            "gate",
            "priority",
            "report"
          ]
        },
        {
          "name": "kev",
          "arg": "<file>",
          "description": "The CISA Known Exploited Vulnerabilities catalogue (known_exploited_vulnerabilities.json). Without it known exploitation is unknown and says so.",
          "default": "not supplied",
          "commands": [
            "gate",
            "priority",
            "report"
          ]
        },
        {
          "name": "json",
          "description": "Print the result as JSON instead of text: keryn.dev/outcome-comparison/v1, keryn.dev/gate-result/v1, keryn.dev/priority/v1 or keryn.dev/estate-report/v1.",
          "default": "off",
          "commands": [
            "compare",
            "gate",
            "priority",
            "report"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn aspm priority --estate estate.yml --app shop --store aspm-store",
          "note": "Act, attend and track tiers from the latest snapshot. Each row says what put it there and what was not known."
        }
      ],
      "exit": {
        "0": "listed; nothing is in the act tier",
        "1": "at least one entry is in the act tier",
        "2": "usage error, unreadable input, or no snapshot of the application"
      },
      "notes": [
        "An order, not a score: the Risk Index (keryn-score/1) stays the only published number.",
        "Unknown exposure, criticality or exploitation is shown as unknown and is never read as the safe case.",
        "The table that orders the tiers is keryn-priority-table/1; it is judgment and is named in the JSON output."
      ],
      "runsIn": "keryn",
      "environment": []
    },
    {
      "path": "aspm report",
      "summary": "one row per application of the estate, with what is not known beside every count",
      "usage": "keryn aspm report --estate <file> --store <store> [--at <time>] [--epss <file>] [--kev <file>] [--checkout <provider>:<owner>/<repo>=<dir>]... [--json]",
      "args": [],
      "flags": [
        {
          "name": "estate",
          "arg": "<file>",
          "description": "The estate file (keryn.dev/estate/v1, YAML or JSON): applications, their components, owners, criticality and exposure.",
          "default": "required",
          "commands": [
            "snapshot",
            "gate",
            "priority",
            "report"
          ]
        },
        {
          "name": "store",
          "arg": "<dir|sqlite:file>",
          "description": "Where snapshots are kept. A directory of snapshot files, or sqlite:<file> for one SQLite file. Both only ever gain snapshots.",
          "default": "required; compare and gate can take --before and --after instead"
        },
        {
          "name": "at",
          "arg": "<time>",
          "description": "The time the snapshot is taken, or the time gate, priority and report are worked out for: an ISO 8601 time, for example 2026-11-18T09:00:00Z.",
          "default": "now",
          "commands": [
            "snapshot",
            "gate",
            "priority",
            "report"
          ]
        },
        {
          "name": "epss",
          "arg": "<file>",
          "description": "EPSS scores: the daily CSV FIRST publishes (cve,epss,percentile). Without it exploitation likelihood is unknown and says so.",
          "default": "not supplied",
          "commands": [
            "gate",
            "priority",
            "report"
          ]
        },
        {
          "name": "kev",
          "arg": "<file>",
          "description": "The CISA Known Exploited Vulnerabilities catalogue (known_exploited_vulnerabilities.json). Without it known exploitation is unknown and says so.",
          "default": "not supplied",
          "commands": [
            "gate",
            "priority",
            "report"
          ]
        },
        {
          "name": "checkout",
          "arg": "<provider:owner/repo=dir>",
          "description": "A local checkout of a repository component (github: or gitlab:). Code owners are read from the CODEOWNERS file committed at its HEAD.",
          "default": "none: code owners are those the estate file declares",
          "repeatable": true,
          "commands": [
            "report"
          ]
        },
        {
          "name": "json",
          "description": "Print the result as JSON instead of text: keryn.dev/outcome-comparison/v1, keryn.dev/gate-result/v1, keryn.dev/priority/v1 or keryn.dev/estate-report/v1.",
          "default": "off",
          "commands": [
            "compare",
            "gate",
            "priority",
            "report"
          ]
        }
      ],
      "acceptsScanFlags": false,
      "examples": [
        {
          "command": "keryn aspm report --estate estate.yml --store aspm-store",
          "note": "Markdown: owner, criticality, tier counts and snapshot date for every application, and what is missing or not done for each."
        }
      ],
      "exit": {
        "0": "reported; no application has an act-tier entry",
        "1": "at least one application has an act-tier entry",
        "2": "usage error or unreadable input"
      },
      "notes": [
        "An application with no snapshot is a row, not an omission.",
        "The report holds no assignees, due dates or ticket states; hand-off goes to your tracker through keryn's connectors."
      ],
      "runsIn": "keryn",
      "environment": []
    }
  ]
}
