CLI reference

keyhog scan [PATH]...

The main subcommand. Scans one or more PATH roots (default: current directory) and emits findings. Pass several roots in a single run (keyhog scan src/ tests/ config/) and each is walked as its own source; a root nested inside another is folded into its covering parent (announced on stderr) so no subtree is scanned twice. Exit code: 0 clean, 1 findings present, 2 user error, 3 system error, 10 live credential, 11 scanner panic, 12 selected or required GPU unavailable, 13 requested source failed or coverage incomplete.

Input selection

Output

Verification and HTTP transport

Performance

Source Limits

Every limit below also has a [limits] key in .keyhog.toml with the same name minus the limit- prefix and with dashes changed to underscores.

Detector tuning

Scan controls

Hyperscan database cache location is explicit scan configuration: use keyhog scan --cache-dir <DIR> or .keyhog.toml [system].cache_dir. Autoroute calibration evidence is also explicit scan configuration: use keyhog scan --autoroute-cache <PATH|off> or .keyhog.toml [system].autoroute_cache. GPU MoE readback timeout is explicit scanner tuning: .keyhog.toml [tuning].gpu_moe_timeout_ms. GPU region-presence parity/debug recall-floor runs use .keyhog.toml [tuning].gpu_recall_floor = true.

Custom S3 and GCS endpoints never receive ambient cloud credentials unless the operator explicitly passes --allow-s3-credential-forward or --allow-gcs-token-forward. Private cloud endpoints additionally require --allow-private-cloud-endpoint (or [http].allow_private_endpoint = true).

keyhog config --effective [SCAN FLAGS]

Prints the resolved scan and report policy and exits without scanning. This is the operator-visible way to prove what KeyHog would run after compiled defaults, .keyhog.toml, and CLI overrides are merged. The output includes report format, severity floor, dedup scope, secret visibility, client-safe/test-fixture policy, and lockdown alongside backend, detector, scanner, source-limit, verification, and cache settings.

config --effective accepts the same config-affecting flags as scan, including --config, --fast, --deep, --precision, source limits, detector paths, confidence floors, and the positional path shorthand.

keyhog config --effective
keyhog config --effective --config .keyhog.toml --precision .
keyhog config --effective --limit-stdin-bytes 32MB --no-ml

keyhog detectors

Lists every detector in the embedded corpus.

keyhog detectors                  # human-readable, grouped by service
keyhog detectors --format json    # one JSON array of detector objects
keyhog detectors --format json | jq length
keyhog detectors --search aws     # id/name/service/keyword substring filter
keyhog detectors --search aws --verbose  # full matching specs
keyhog detectors --audit          # validate the loaded corpus; errors exit 3
keyhog detectors --fix --dry-run  # preview safe verifier-template rewrites

--fix only performs the mechanically safe single-brace to double-brace verification-template rewrite; other audit findings require an explicit edit. --format is mutually exclusive with --audit and --fix.

keyhog explain <DETECTOR_ID>

Explain the loaded detector. Includes keywords, patterns, companion rules, verification endpoint, and detector-owned entropy/BPE/length/suppression policy.

keyhog explain stripe-secret-key

keyhog watch [PATH]...

Foreground subcommand that watches one or more directories for file changes and re-scans each changed file. Useful for IDE-side feedback. It does not connect to or appear in keyhog daemon status; the independent keyhog daemon is a Unix-socket service used only by eligible keyhog scan --daemon requests. Pass several roots to monitor them with a single watcher; nested or duplicate roots fold into their covering parent, mirroring keyhog scan. Every root must be a directory.

keyhog watch src/                 # watch the source tree
keyhog watch src/ config/         # watch several roots in one process
keyhog watch                      # watch the current directory

keyhog hook <install|uninstall>

Manages the git pre-commit hook. See Pre-commit hook for usage.

keyhog daemon <start|stop|status> (Unix only)

The daemon holds a compiled scanner and initialized accelerator state for eligible stdin and single-file scans. Directory, Git, remote, baseline, verification, explicit backend/calibration, and incompatible policy requests use the in-process pipeline in auto mode; --daemon=on fails if the exact daemon route cannot be honored.

daemon start --request-timeout-secs <N> sets how long one client connection may sit without completing a request frame before the daemon closes it and reclaims the connection slot. Default: 300.

Default socket path: $XDG_RUNTIME_DIR/keyhog.sock when that directory is set; otherwise the OS user cache directory (~/.cache/keyhog/server.sock on Linux or ~/Library/Caches/keyhog/server.sock on macOS), with the OS temporary directory plus keyhog/server.sock as the last fallback. Every daemon command and scan client resolves the same default.

On Windows: every daemon subcommand and explicit scan --daemon=auto|on prints a Unix-only error and exits non-zero. No Windows daemon transport ships; an absent daemon flag or explicit --daemon=off runs the in-process scanner.

See Daemon and warm scans for the complete auto / on / off contract, request eligibility, warm autoroute behavior, and socket security semantics.

keyhog diff <FILE_A> <FILE_B>

Compare two scan outputs (JSON or NDJSON). Useful for “did this PR introduce a new finding?” gating in CI.

keyhog scan . --format json > baseline.json
git checkout pr-branch
keyhog scan . --format json > pr.json
keyhog diff baseline.json pr.json

Pass --hide-unchanged to omit the unchanged section from human output, or --json for a stable CI-readable comparison.

keyhog calibrate

Show or update the per-detector Bayesian (Beta-α/β) calibration counters. Used to teach the scorer that detector X has produced N true positives and M false positives in your environment. Scans use the counters only when --calibration-cache <PATH> or [system].calibration_cache explicitly points at the file.

keyhog calibrate --show                       # print current counters
keyhog calibrate --tp stripe-secret-key       # record one TP
keyhog calibrate --fp generic-api-key         # record one FP

Pass --cache <PATH> to point at a non-default counter file (the default lives under the platform cache directory, normally $XDG_CACHE_HOME/keyhog/calibration.json). Existing corrupted or schema-incompatible cache files fail closed and are not overwritten.

keyhog calibrate-autoroute

Runs the local stdin/filesystem scan-policy and workload-bucket sweep, verifies backend parity, and persists fastest-correct routing evidence for those normal auto scans. Git, container, web, and other environment-backed source classes remain in the installer’s calibration sweep. --autoroute-cache <PATH> selects the evidence file; off is rejected because calibration must persist its result. --quiet suppresses per-probe progress but still prints the final summary.

keyhog backend

Prints hardware probe results and a diagnostic per-tier heuristic matrix: which SIMD ISA was detected and whether Hyperscan, CUDA, or wgpu initialized. The matrix is not the scan --backend auto decision; normal automatic scans use persisted fastest-correct calibration. Use keyhog backend --autoroute to inspect that evidence, including distinct cold-aware one-shot and warm-daemon routes, and --probe-bytes only for heuristic what-if work.

keyhog backend

--probe-bytes <N> and --patterns <N> are what-if inputs to the diagnostic heuristic matrix only; neither changes the corpus nor predicts persisted autoroute. On an eligible GPU host, --self-test reports three named probes: moe_kernel for GPU confidence scoring, vyre_literal_set for VYRE’s direct match-triple diagnostic, and gpu_region_presence for the production scan route. The last probe owns scan eligibility. A direct-mode limitation is reported as known when classified and warning otherwise, but only a production-path or required GPU capability failure makes the health report fail. When no eligible physical GPU exists, the normal self-test emits one gpu_adapter probe with status skip and exits 0; --require-gpu changes that probe to fail and exits 4. --no-gpu explicitly requests the skip without initializing a GPU. --json is available for self-test and autoroute inspection output. A failed self-test emits the complete report and exits 4; a normal scan whose selected GPU route fails exits 12.

keyhog scan-system

Recursive system-wide credential audit. Walks every mounted drive (skipping pseudo-filesystems and, by default, network mounts), discovers every .git repository on the way, and runs the same scan + git-history pipeline that keyhog scan --git-history uses on each. Honors a hard --space <N> ceiling on total bytes scanned so it cannot accidentally exhaust a CI runner. Does NOT honor .gitignore unless --respect-gitignore is passed (an attacker stashing leaked keys would .gitignore them).

keyhog scan-system                                  # local mounts, git history on
keyhog scan-system --include-network                # also walk NFS/SMB/sshfs
keyhog scan-system --space 50G --no-git-history     # cap + skip history walks
keyhog scan-system --lockdown                       # forbids --include-network

keyhog completion <bash|zsh|fish|powershell|elvish>

Emits a shell-completion script. Pipe into the shell’s completion location.

keyhog completion bash > /etc/bash_completion.d/keyhog
keyhog completion zsh > "${fpath[1]}/_keyhog"
keyhog completion fish > ~/.config/fish/completions/keyhog.fish
keyhog completion powershell >> $PROFILE
keyhog completion elvish > ~/.config/elvish/lib/keyhog.elv

Install maintenance

Linux uses one GPU-capable artifact that probes CUDA and WGPU at runtime. These commands therefore have no backend or artifact-variant selector. Implicit resolution excludes drafts and prereleases and requires the binary, checksum, signature, GPU-literal sidecar, sidecar checksum, and sidecar signature. An explicit --version may select a published prerelease but never a draft.

Root options

These are root-command options. --version and --full are not scan flags; they print identity information and exit. Each subcommand also has its own --help.

Display controls are command-specific: scan --no-color disables report and summary ANSI output, while detectors --verbose prints full matching detector specifications.