CLI reference
The essential belay commands for day-to-day use. All commands run locally — nothing is sent to an external service.
Setup and configuration
belay setup
Guard a project. Starts the daemon, detects and configures your agent integrations, discovers databases, and prints next steps. Safe to re-run after an upgrade.
$ belay setup
Flags:
| Flag | What it does |
|---|---|
| --all | Wire all four supported agent integrations without prompting. |
| --surfaces <list> | Wire specific agents only. E.g. --surfaces claude,cursor. |
belay scan
Re-discover the databases your project connects to. Re-reads .env files, Docker Compose, and Prisma schema. Read-only — never opens a connection.
$ belay scan
belay config validate
Validate belay.config.json against the schema. Reports every issue with a location and message. Use this whenever you have edited the config file manually.
$ belay config validate
Evaluating and testing
belay try
Preview what Belay would decide for a command. Runs the command through the full decision process without executing anything. Safe to use with any command, including destructive ones.
$ belay try "<command>"
Approvals
belay pending
List all actions currently held for your approval. Read-only — listing is not approving.
$ belay pending
belay approve
Approve or reject a pending action. When one action is pending, resolves it interactively. When multiple are pending, requires --id to avoid ambiguity.
$ belay approve $ belay approve --id <id> $ belay approve --id <id> --decision reject
Audit and verification
belay verify
Verify the signed audit log on your machine. Confirms the integrity of every decision record. Exits 0 if the log is intact, 1 if verification fails, 2 if the log is missing.
$ belay verify
Health and diagnostics
belay doctor
Run every health check and print a [ok] / [warn] / [fail] result for each one, with the exact fix for anything that needs attention. The first command to run when something seems wrong.
$ belay doctor
belay daemon status | stop | restart
Manage the local guardrail process. status checks whether the daemon is running. stop shuts it down gracefully. restart stops and restarts it.
$ belay daemon status $ belay daemon stop $ belay daemon restart
belay channels test
Test your configured notification channels (e.g. Telegram). Sends a test message and confirms that Belay can receive replies. Reports what is working and what needs attention.
$ belay channels test
belay connect telegram
Interactive setup for Telegram approval notifications. See Telegram for details.
$ belay connect telegram
Quick reference
| Command | What it does |
|---|---|
| belay setup | Guard a project. Starts the daemon, wires agent integrations, discovers databases. |
| belay scan | Re-discover database connections in the current project (read-only). |
| belay try "<cmd>" | Preview a decision without executing anything. Safe with any command. |
| belay pending | List actions waiting for your approval (read-only). |
| belay approve | Approve or reject a held action. |
| belay verify | Verify the integrity of the signed audit log. |
| belay doctor | Run all health checks. The first tool to reach for when something seems wrong. |
| belay daemon status | Check whether the guardrail daemon is running. |
| belay daemon stop | Stop the guardrail daemon. |
| belay daemon restart | Restart the guardrail daemon. |
| belay config validate | Validate belay.config.json against the schema. |
| belay channels test | Test configured notification channels. |
| belay connect telegram | Interactive Telegram approval setup. |