CLI overview
Belay ships as a single static Rust binary — belay — that dispatches every
subcommand. There is no separate helper to install and no runtime Python dependency.
Every subcommand runs as the invoking user (never root).
belay <subcommand> [flags]
When to use
Start here when you want a map of everything the binary can do. Each subcommand has its own guide; this page is the index. If you are setting Belay up for the first time, the fastest path is the wizard:
belay setup
setup detects installed agents, protects the ones you choose, and optionally configures
the firewall, the AI explainer, messaging channels, a vuln-scan schedule, and the
boot-start service. It is also run automatically by the installer. To wire an agent by
hand instead, follow the short path: detect -> protect <agent> --observe ->
protect <agent>.
The subcommands
Core runtime
| Subcommand | One-line description |
|---|---|
daemon | Run the always-on resident daemon (the policy core and IPC endpoint). |
hook | Thin PreToolUse/PostToolUse client that talks to the daemon over its local socket. |
gate | One-shot stdin -> stdout verdict (hook in pipe mode, no persistent socket). |
mcp-proxy | Wrap any MCP server so every tools/call is gated; fail-closed. |
serve | Local JSON + SSE API backend on 127.0.0.1:8787 (the Desktop App is the UI). |
Setup & lifecycle
| Subcommand | One-line description |
|---|---|
setup | Interactive first-run wizard: detect, protect, and configure everything. |
detect | Auto-detect installed AI coding agents and their risky flags. |
protect | Wire Belay into an agent at the tool-call boundary. |
unprotect | Remove Belay's integration and restore the agent's original config. |
install-service | Register Belay as a boot-start service (systemd / launchd / Windows SCM). |
uninstall | Stop the service, remove the unit and staged binary; --purge also wipes ~/.belay. |
Audit, scan & evidence
| Subcommand | One-line description |
|---|---|
scan | Static pre-install scanner for a path, file, git URL, or zip; emits JSON or SARIF. |
status | Print the last 20 audit rows (ts verdict tool rules). |
logs | Print the last N audit rows. |
evidence | Build or verify a tamper-evident SHA-256 evidence pack. |
channels | Print guidance on the messaging / approval channels. |
Host protection
| Subcommand | One-line description |
|---|---|
posture | Check host / VPS security posture; exits non-zero on a critical finding. |
monitor | Continuously monitor host posture, writing an audit row per finding. |
host-scan | Scan the local host for malware (home / downloads / full). |
quarantine | Manage quarantined files (list, restore <id>, delete <id>). |
harden | Host hardening checks and SSH-guard controls. |
vuln | Vulnerability scan against the bundled advisory DB. |
firewall | Native Rust firewall management (propose / apply / confirm / revert / status). |
egress | App-aware egress control (allow / deny / mode). |
serve is a JSON + SSE API only — it is not a web dashboard. The user-facing UI is
the Desktop App. See Local backend & Desktop App.
Command notes
daemon
Runs the resident core: the audit writer, the deterministic policy engine
(rules -> decide -> correlate -> allowlist), the local IPC socket, the MCP proxy shim,
the messaging ASK fan-out, and the honeypot canaries. The hook and gate clients
connect to it. It runs as the invoking user, and its socket (belayd.sock) and audit
log live under that user's ~/.belay.
belay daemon
setup
belay setup # interactive wizard
belay setup --yes # apply Quick defaults non-interactively
The 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. See Detect & protect.
posture
belay posture # exits non-zero if any critical posture finding is present
Useful as a CI gate or a pre-flight check on a fresh VPS.
status & logs
belay status # last 20 audit rows: ts verdict tool rules
belay logs -n 100 # last 100 audit rows (default 50)
The audit view is belay status / belay logs. There is no belay audit command.
monitor
belay monitor # loop every 60s, one audit row per finding
belay monitor --interval 300 # every 5 minutes
belay monitor --once # single pass, then exit
host-scan
belay host-scan # scan the home directory (default)
belay host-scan --scope downloads # scan ~/Downloads
belay host-scan --scope full # scan from /
belay quarantine list # manage anything the scan quarantined
belay quarantine delete <id>
harden & vuln
belay harden check # host hardening findings
belay harden ssh-guard --enable # arm the SSH brute-force guard (needs daemon)
belay vuln scan # scan installed packages against the bundled DB
belay vuln list # list cached advisories
The advisory database is bundled per-ecosystem in the binary — end users never set an NVD key. Vuln reports surface CISA KEV (known-exploited) badges and EPSS exploit-probability percentages.
firewall & egress
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)
belay egress list
belay egress allow <binary> <dest>
belay egress mode block on
The firewall is native Rust (via rustables) — there is no shell-out to
nft/iptables. apply pins your current SSH source and auto-reverts after the confirm
window so you cannot lock yourself out of a headless VPS.
install-service
# Preview the unit without writing anything (no privilege needed):
belay install-service --print
# Install + enable the boot-start service:
sudo belay install-service --enable
The unit runs the daemon as the invoking user (never root) so the daemon's socket/audit paths match where the per-user hook connects.
On Linux this writes a systemd unit; on macOS a launchd job. On Windows it
registers an auto-start service via the Service Control Manager and needs an elevated
(Run as Administrator) shell instead of sudo.
uninstall
belay uninstall # stop + remove the service, unit, and staged binary
belay uninstall --purge # also delete ~/.belay (config, rules cache, audit log, keys)
On Windows, deregister the SCM service with belay install-service --uninstall.