Skip to main content

CLI Commands

Belay is a single static Rust binary with all of its subcommands built in. Every command below is invoked as belay <subcommand>. There is no runtime Python dependency, and the binary always runs as the invoking user, never root.

When to use this​

Use this page as the command reference once you are past the Quickstart. Each entry gives a synopsis, the common flags, and one worked example.

note

Flags evolve between releases. The authoritative list for any command is always belay <subcommand> --help. Most commands accept --home <path> to point at an alternate home directory (where ~/.belay/ and agent configs live) — useful for testing or multi-profile setups.

setup​

Interactive first-run wizard. Detects installed agents, asks Quick vs Custom, then protects the chosen agents and optionally configures the firewall, the AI explainer, messaging channels, a vuln-scan schedule, and the boot-start service. This is also what the installer runs automatically after placing the binary.

  • Flags: --yes (apply Quick defaults non-interactively), --quick, --home <path>
belay setup          # interactive
belay setup --yes    # non-interactive Quick defaults

daemon​

Run the always-on resident daemon (was the belayd bin): the audit writer, the deterministic engine (rules, decide, correlate, allowlist), the local IPC socket (~/.belay/belayd.sock), the MCP proxy shim, the messaging fan-out, and the honeypot. Most users install it as a boot-start service rather than running it by hand (see install-service).

belay daemon

hook [EVENT]​

Thin PreToolUse / PostToolUse client that talks to the daemon over its local socket. The tool-call event is read from stdin as JSON. This is the integration style for Claude Code / Codex where a persistent daemon is running. The hook command string installed into settings.json is belay hook pretooluse / belay hook posttooluse.

  • Args: optional pretooluse / posttooluse
echo "$TOOL_EVENT_JSON" | belay hook pretooluse

gate​

One-shot gate verdict from stdin JSON — the hook in pipe mode, for integrations that prefer a self-contained stdin/stdout call over connecting to the daemon socket.

echo "$TOOL_EVENT_JSON" | belay gate

scan <path>​

Static pre-install scanner. Runs deterministic analyzers (patterns, AST, taint, YARA, OSV) over a path, file, git URL, or zip, and prints a provenance-weighted score, severity, and install/run recommendation.

  • Flags: --llm (enable the optional LLM cascade to filter false positives), --format json|sarif
belay scan ./some-package --format sarif > results.sarif

serve​

Run the local API + Server-Sent-Events backend. Binds 127.0.0.1:8787 by default.

  • Flags: --addr 127.0.0.1:8787, --audit <path>
belay serve --addr 127.0.0.1:8787
warning

serve is a JSON/SSE API only — it is not a web dashboard and serves no HTML. The desktop app is the user interface; it connects to this backend to render its views. Pointing a browser at the port shows raw API responses.

channels​

Prints guidance on notification / approval channels. Channels run inside daemon via the ASK fan-out; there is no standalone channels server. Configure them through the setup wizard or the desktop Messaging tab.

belay channels
note

Messaging channels support two-way approvals: Telegram, Discord, WhatsApp, Matrix, Mattermost, and Slack (Block Kit buttons) can take an Allow/Deny reply back; ntfy, Microsoft Teams, WeCom, generic webhook, and the terminal are notify-only. Approvers enroll by DMing a one-time pair <code> to the bot (owner-gated, default-deny). See Configuration.

posture​

Check host / VPS security posture. Exits non-zero (1) on any critical finding, so it is CI-friendly.

  • Flags: --home <path>
belay posture

detect​

Detect installed AI coding agents and their risky flags, in a fixed detector order. Reports each agent's config paths, risky flags, and how Belay would intercept it (hook, MCP proxy, or config policy). Auto-detects Claude Code, Codex, Cursor, Cline, Roo, Gemini CLI, Goose, OpenClaw, Hermes, Antigravity, opencode, and more.

  • Flags: --home <path>, --json
belay detect --json

protect <agent>​

Wire Belay into an agent's tool-call boundary. Interception is agent-correct: Claude Code / Codex get JSON hooks in settings.json, Cursor gets Cursor hooks, Hermes gets its YAML pre_tool_call hooks, OpenClaw gets an exec-policy, and MCP-server agents get the mcp-proxy gate.

  • Flags: --observe (log-only dry run, no blocking), --home <path>
belay protect claude-code --observe   # dry-run first
belay protect claude-code             # then enforce

unprotect <agent>​

Cleanly remove Belay's interception for an agent and restore its original configuration.

  • Flags: --home <path>
belay unprotect claude-code

status​

Print the last 20 audit rows (ts verdict tool rules) — a quick glance at recent decisions.

  • Flags: --home <path>
belay status
note

There is no belay audit command. Use belay status (last 20 rows) or belay logs (last N rows) to view the audit log.

logs​

Print the last N audit rows.

  • Flags: -n <count> (default 50), --home <path>
belay logs -n 100

evidence <build|verify>​

Build or verify a tamper-evident SHA-256 evidence pack over findings + SARIF. build writes the pack and a manifest.json of per-file hashes; verify recomputes and compares.

  • Flags: --out <path>, --dir <path>, --home <path>
belay evidence build --out ./evidence
belay evidence verify --dir ./evidence

mcp-proxy -- <cmd> [args…]​

Run a real MCP server behind the gate. Belay intercepts every tools/call and applies the same deterministic verdicts. Fail-closed: a headless proxy denies anything that is not an explicit allow (an unanswered ask, or any error, becomes a deny).

  • Args: everything after -- is the wrapped server command.
belay mcp-proxy -- npx -y @modelcontextprotocol/server-filesystem /work

monitor​

Continuously monitor host posture, writing an audit row per finding.

  • Flags: --interval <secs> (default 60), --once, --home <path>
belay monitor --interval 300

host-scan​

Run a local malware scan over the host — a native, pure-Rust scan (no clamd shell-out). Reports findings against the same severity model as the pre-install scanner.

belay host-scan

quarantine​

Isolate a flagged file or artifact so it can no longer be read or executed by an agent, pending review.

belay quarantine list               # manage anything the scan quarantined
belay quarantine delete <id>

harden​

Run host-hardening checks and report weak spots (permissions, exposed services, misconfigurations) with actionable guidance.

belay harden check               # host hardening findings
belay harden ssh-guard --enable  # arm the SSH brute-force guard (needs daemon)

vuln​

Report known vulnerabilities against your dependencies using the bundled, per-ecosystem advisory database — no NVD key is ever required. Reports now surface CISA KEV (known-exploited) badges and EPSS exploit-probability percentages.

belay vuln scan                  # scan installed packages against the bundled DB
belay vuln list                  # list cached advisories

firewall​

Inspect and manage the native Rust firewall (implemented via rustables — no shell-out to nft/iptables). Supports manual rules plus a one-click auto setup that previews then confirms before applying anything.

belay firewall propose           # preview a least-privilege ruleset
belay firewall apply             # apply with a dead-man's switch (auto-revert)
belay firewall confirm           # keep the applied rules (disarm auto-revert)

egress​

View and manage the outbound egress allowlist. When egress destination enrichment is enabled, destinations are annotated with a hostname · AS<n> <name> · <cc> chip. Enrichment is display-only and never gates a decision.

belay egress list
belay egress allow <binary> <dest>
belay egress mode block on

install-service​

Install the resident daemon as a boot-start service — systemd on Linux, launchd on macOS. It stages the binary to a stable location, writes and enables the unit, re-points the agent hook at the staged binary, and waits for the daemon socket. The service runs as the invoking user (never root) so its socket and audit paths match where the per-user hook connects. On Windows it registers an auto-start service via the Service Control Manager (needs an elevated / Run-as-Administrator shell instead of sudo).

  • Flags: --enable, --print (preview the unit, no privileges needed), --user, --exec-path <path>, --repoint-hook, --wait-socket
sudo belay install-service --enable
belay install-service --print          # preview only

sweep-now​

Run an agent-surface sweep immediately, in this process, instead of waiting for the daemon's periodic loop (every 6h by default, and off entirely when skill-watch is disabled or the rescan interval is 0). Writes one record to the same history sweep-history and sweep-compare read, tagged trigger: "manual" so it stays distinguishable from the daemon's own sweeps.

  • Flags: --format <text|json>
belay sweep-now
belay sweep-now --format json
caution

On-demand use only. The alert dedup state is per-process, so running this from cron re-alerts items that are still flagged instead of standing in for the disabled loop.

sweep-history​

Show recent sweeps: what each one examined, and what it could not reach. The skipped list is the point — a sweep that silently missed a directory is otherwise indistinguishable from a clean one.

  • Flags: --limit <N>, --format <text|json>
belay sweep-history
belay sweep-history --limit 5 --format json

sweep-compare​

Compare two sweeps and classify every item as new, persisting, changed, resolved, or unknown. Defaults to the two most recent.

  • Flags: --from <sweep_id>, --to <sweep_id>, --format <text|json>
belay sweep-compare
belay sweep-compare --from <sweep_id> --to <sweep_id>

See Agent-Surface Sweeps for what each record contains and why unknown is its own class.

skill-watch <on|off>​

Toggle the proactive skill directory watcher. The watcher polls installed skill directories roughly every 30s and auto-quarantines DO_NOT_INSTALL verdicts; this is the off-switch for that behavior. Persisted to ~/.belay/skill_watch.json and read once at watch-loop setup, so it takes effect on the next belay daemon start.

belay skill-watch off
belay skill-watch on

skill-approve <skill>​

Re-approve an installed skill: snapshot its current SKILL.md manifest as the approved baseline and clear any drift alert. Accepts an installed skill name or a path to the skill directory.

belay skill-approve my-skill
belay skill-approve ~/.claude/skills/my-skill

uninstall​

Stop and remove the boot-start service, its unit/plist, and the staged binary.

  • Flags: --purge (also delete ~/.belay — config, rules cache, audit log, keys), --yes
belay uninstall
belay uninstall --purge   # also wipe ~/.belay