CLI Reference

Every command Beekeeper ships, grouped by area. Commands marked Linux only print a "not supported" message on other platforms. Input for beekeeper check is always read from stdin. There is no --input flag.

beekeeper version

Print version, commit, and build date. No flags.

beekeeper version

beekeeper init

Create the state directory and configure editor protection. Detects installed editors and offers to disable extension auto-update and register watch dirs.

beekeeper init [--yes] [--no-editors]

• --yes: auto-consent to all prompts
• --no-editors: skip editor detection (scripted installs)

beekeeper check

Evaluate a tool call. The hook handler reads a tool-call JSON object from stdin; you can also build the call from flags (--tool / --args), which is the portable way to run it from PowerShell or cmd (which cannot reliably pipe to a native program's stdin).

# stdin form (bash): how a harness hook feeds the call
echo '{"tool_name":"Bash","tool_input":{"command":"..."}}' | beekeeper check --hook claude-code

# flag form (PowerShell, cmd, POSIX): no stdin needed
beekeeper check --hook claude-code --tool Bash --args "cat ~/.ssh/id_rsa"

• --hook <harness>: render harness-specific deny output; on block exits 2, reason to stderr, deny JSON to stdout
• --tool <name> / --args <arg>, shim path: build a tool call from flags
• Without --hook: exits 0 (allow/warn) or 1 (block) and writes the raw Decision JSON to stdout
• Exit codes: 0 = allow/warn, 2 = block (with --hook), 1 = block (without)

beekeeper catalogs

Manage cached threat-intel catalogs.

beekeeper catalogs sync   # fetch + cache + build the mmap index (interval-gated)

catalogs sync is interval-gated: it fetches only when catalog_sync.interval (default 2h) has elapsed since the last success. Use --force to sync now. It also runs a bounded, off-hot-path adjudication batch over the local corpus and applies any confirmed-malicious feedback (quarantine card, detection-only Sentry watch, and a local catalog overlay) as the no-daemon fallback for the background sync. See Security.

beekeeper catalogs sync --background   # scheduled mode: hide console (Windows) + log to <state>/logs/sync.log

--background is what the installed daemon runs. It hides the console window on Windows so the hourly heartbeat does not flash a blank terminal, and tees every run to a rotating sync.log on all platforms.

beekeeper catalogs status   # last run result, counts, next-due, daemon state, log path

catalogs status reads the persisted summary of the most recent run: the result (synced, unchanged, skipped, disabled, or error), the entry count, how many installed packages matched the catalog and how many were quarantined or pending, the next-due time, whether the daemon is registered, and the sync.log path. It is read-only.

beekeeper catalogs watch   # poll sources; re-scan on delta (Ctrl+C)

beekeeper catalogs verify --source <name>   # clear degraded mode after review

beekeeper catalogs diff   # per-source delta vs last-synced state

beekeeper catalogs daemon install     # install the unprivileged background sync schedule

beekeeper catalogs daemon uninstall   # remove the background sync schedule

beekeeper catalogs daemon status   # installed state + last sync time

• catalogs daemon installs a per-user, unprivileged background sync that runs catalogs sync on an interval (default 2h, clamped to a 2h–24h range), using conditional ETag requests so an unchanged feed costs almost nothing. It is a systemd user timer on Linux, a LaunchAgent on macOS, and a current-user scheduled task on Windows (no elevation). Configure it with the catalog_sync block; see Configuration.

beekeeper audit

Inspect the audit log.

beekeeper audit tail [--no-follow]

beekeeper audit query --since <dur|RFC3339> --agent <a> --tool <t> --decision <allow|warn|block> --limit <N>

beekeeper audit export --format <ndjson|csv|otlp> [--since ...] [--agent ...] [--tool ...] [--decision ...]

• audit tail streams the live log; --no-follow dumps existing records and exits
• audit query filters records; audit export requires --format

beekeeper selftest

Run the embedded adversarial corpus as a sanity check. No flags.

beekeeper selftest

beekeeper watch

Watch extension directories for new installations (Ctrl+C to stop). No flags.

beekeeper watch

beekeeper scan

Scan installed extensions against the catalog and release-age policy.

beekeeper scan [--deep]

• --deep: deep scan (passes --profile deep --root <home> to the scanner)

beekeeper quarantine

Manage quarantined extensions.

beekeeper quarantine list

beekeeper quarantine restore <id>

beekeeper quarantine purge [--yes]

• purge --yes removes ALL quarantined extensions without confirmation

beekeeper hooks

Install or uninstall Beekeeper hooks for agent CLIs.

beekeeper hooks install --target <harness> [--dry-run] [--force]

beekeeper hooks uninstall --target <harness> [--dry-run]

• --target is required; --dry-run prints without modifying; --force overwrites without prompting
• First install also enables install posture at the hook (three warn-by-default rules; see Configuration)
• Hook-file targets: claude-code, codex, cursor, augment, codebuddy, qwen, gemini, copilot, antigravity, windsurf, hermes, cline, opencode
• kilo, trae, continue, and openclaw integrate through the MCP gateway: the installer prints gateway configuration instructions instead of writing a hook file
• See Integration for the full 17-harness tier table and the per-harness caveats

beekeeper gateway

Manage the MCP gateway daemon. Binds 127.0.0.1:7837 by default.

beekeeper gateway --upstream <url> [--port 7837] [--bind 127.0.0.1] [--allow-remote]

beekeeper gateway token   # print the current session bearer token

beekeeper gateway status   # running status, bound address, masked token

• --upstream is required at runtime
• See the Integration gateway section for the --bind 0.0.0.0 exposure caveat

beekeeper shim

Manage PATH shims for package managers and toolchains (advanced).

beekeeper shim install

beekeeper shim uninstall

beekeeper shim status

beekeeper protect

Manage the Beekeeper Sentry daemon via systemd. Linux only (requires root/sudo); prints "not supported" on other platforms.

beekeeper protect install   # install + start Sentry via systemd

beekeeper protect uninstall   # stop + remove the daemon

beekeeper protect status   # IPC status + baseline state

beekeeper sentry

The Sentry daemon itself (normally invoked by systemd ExecStart). Linux only.

beekeeper sentry   # run the daemon directly (testing)

beekeeper sentry rules list

beekeeper sentry rules enable <id>

beekeeper sentry rules disable <id>

beekeeper llamafirewall

Manage the LlamaFirewall prompt-injection sidecar (opt-in, experimental).

beekeeper llamafirewall enable

beekeeper llamafirewall disable

beekeeper llamafirewall status   # PID, uptime, sample rate, fail mode, degraded

install bootstraps the runtime: a CPU-only Python venv under the state directory, pinned dependencies, and the gated 22M PromptGuard 2 model. Accept the Llama license and run huggingface-cli login first, or the download fails. Native Windows cannot complete the install (CodeShield's semgrep has no Windows build; use WSL or a Linux/macOS host). See Security for the full posture.

beekeeper llamafirewall install

beekeeper llamafirewall install --model <hf-repo>

beekeeper dashboard

Open the real-time TUI dashboard.

beekeeper dashboard [--admin]

• --admin enables the editing and destructive actions: the policy editor, the first-responder settings editor, and quarantine restore/purge. The viewer is read-only without it.
• Triggering a scan is not gated by --admin: open the command palette (:) and run scan now, scan --quick, or scan history. This is the dashboard equivalent of beekeeper scan.
• Press p for the policy editor and s for first-responder settings (auto_quarantine and corpus knobs); both edit real config under --admin and validate before writing. Press ? for the keybinding list, and : for the command palette.
• See TUI Dashboard for every panel, keybinding, and the structured audit-log viewer.

beekeeper policy

Manage and test declarative policy files in ~/.beekeeper/policies/.

beekeeper policy validate <file>

beekeeper policy test <file> [--tool-call <path|->]

beekeeper policy list

• policy validate schema-checks a file (non-zero exit on errors)
• policy test dry-runs against a tool-call JSON (default stdin), no live catalog

beekeeper diag

Show system health: hook latency (p95/p99), sidecar latency, catalog freshness, ETW loss. No flags. This is the primary diagnostic command.

beekeeper diag

beekeeper posture

Inspect and override the install posture (see Configuration for the three rules and the boundary statement).

beekeeper posture          # each PM's install posture side-by-side with Beekeeper's enforced posture (read-only, machine-wide); names the gaps

beekeeper posture --full   # print the full enforcement-boundary statement

Grant a scoped, audited exception to the install posture:

beekeeper posture allow <package> [flags]

• --once allows the next matching install, then warns again (all rules; not combinable with --rule)
• --always records a standing exception (requires --reason)
• --rule <rule> scopes an --always exception to one rule: release-age | lifecycle | git-remote
• --ecosystem <eco> scopes to one ecosystem (e.g. npm); empty matches any
• --reason "<text>" is the recorded justification (required for --always)

posture allow is posture-scoped: it silences a posture warn for the package but never downgrades a catalog malware block. Each invocation writes a distinct posture_override audit record.

Set a posture rule's action (opt a rule up from the default warn):

beekeeper posture enforce <rule>   # rule is one of: release-age | lifecycle | git-remote

• --block blocks a definite violation of the rule (opts it up from warn)
• --warn lowers the rule back to the default warn

The unknown / fail-soft path always warns: a registry outage never blocks an install even under --block.

beekeeper config

Manage Beekeeper configuration. There are currently no settable keys via config set (the nudge.* keys were removed in v1.1.0). An unknown key is rejected fail-closed with no write; the command and its audit plumbing are retained for a future setting. Install-posture overrides are made with beekeeper posture, not config set.

beekeeper config set <key> <value>   # currently rejects every key fail-closed

Internal / Plumbing Commands

These are invoked by installer scripts or internal mechanisms, not typically run directly: