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 read from stdin. This is the core hook handler.

echo '{"tool_name":"Bash","tool_input":{"command":"..."}}' \
  | beekeeper check --hook claude-code

• --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

catalogs sync 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 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 supply-chain enforcement (nudge.mode=block)
• Target values: claude-code, cursor, codex, augment, codebuddy, qwen, continue, opencode, openclaw; kilo / trae print MCP gateway configuration instructions (see Integration)

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: it creates a CPU-only Python venv under the state directory, installs pinned dependencies (no CUDA wheels), and pre-pulls the gated 22M PromptGuard 2 model into a pinned cache. Accept the Llama license and run huggingface-cli login first, or the model download fails. This step is per-operator and one-time per machine (the Llama license is accepted per user and the weights are not redistributable, so it cannot be bundled). On native Windows the install cannot complete because CodeShield's semgrep dependency has no Windows build; use WSL or a Linux/macOS host.

beekeeper llamafirewall install

beekeeper llamafirewall install --model <hf-repo>

beekeeper dashboard

Open the real-time TUI dashboard.

beekeeper dashboard [--admin]

• --admin enables policy toggle, quarantine restore/purge, and scan trigger

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 nudge

Inspect and test the package-manager nudge.

beekeeper nudge status   # current PM state + active nudge config

beekeeper nudge check "<command>"   # dry-run (the command is NEVER executed)

beekeeper nudge audit [--since <dur|RFC3339>]

beekeeper config

Manage Beekeeper configuration. config set is scoped to five nudge.* keys (validated fail-closed; every change is audit-logged).

beekeeper config set nudge.enabled <true|false>

beekeeper config set nudge.mode <soft|hard|block>

beekeeper config set nudge.require_hardened <true|false>

beekeeper config set nudge.preferred <pnpm|bun>

beekeeper config set nudge.check_socket_scanner <true|false>

See Configuration for what each key does.

Internal / Plumbing Commands

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