# CLI command reference

> Find the exact command for setup, capture, scans, services, identity, rules, and removal.

Source: https://docs.agentbeam.com/agent-cli/commands

Run `beam --help` or a command's `--help` to inspect the installed release. This reference follows the command definitions in the current Beam CLI source. Some command descriptions still say “observe only”; connected policy behavior is documented separately in [Policies](https://docs.agentbeam.com/agent-cli/policies).

## Setup and identity

| Command                               | Behavior                                                                    |
| ------------------------------------- | --------------------------------------------------------------------------- |
| `beam setup`                          | Interactive hook setup, browser connection, and optional background service |
| `beam connect`                        | Open browser pairing and wait for workspace authorization                   |
| `beam enroll --code CODE [--url URL]` | Enroll with an administrator-provided code                                  |
| `beam whoami`                         | Display locally stored device enrollment                                    |
| `beam account`                        | Fetch user, workspace, and device status from the remote API                |
| `beam sync`                           | Fetch and cache workspace policy                                            |
| `beam logout`                         | Attempt remote revocation, then remove local identity                       |
| `beam --version`                      | Print installed package version                                             |

## Capture and scanning

| Command                           | Behavior                                                            |
| --------------------------------- | ------------------------------------------------------------------- |
| `beam start [-p, --port PORT]`    | Start the loopback collector and attempt detected-agent hook wiring |
| `beam studio`                     | Open the local activity interface with browser pairing              |
| `beam token`                      | Print the collector pairing token; treat stdout as sensitive        |
| `beam import FILE`                | Send a JSON/NDJSON file to local ingestion                          |
| `beam hook [AGENT]`               | Read a hook payload from stdin; default agent is `claude-code`      |
| `beam scan FILE [--mcp] [--save]` | Scan offline, or persist through the collector with `--save`        |

`scan` prints JSON on successful completion; findings do not automatically cause a nonzero exit. The CLI banner goes to stderr. Extraction preview includes a trailing human-readable summary, so its whole output is not a single JSON value.

## Package scanning

Packages and every dependency are fetched without running any of their code, scanned for malware shapes, and checked for known vulnerabilities when the machine is connected. See [Scan npm & PyPI packages](https://docs.agentbeam.com/agent-cli/package-scanning).

| Command | Behavior |
| --- | --- |
| `beam add package SPEC [-D] [-g] [--scan-only] [--force] [--no-cve] [--json]` | Scan an npm package and its dependency tree, then install the scanned version with the project's package manager; exit 2 and install nothing on a critical finding. |
| `beam add package SPEC --pip [--python PATH]` | The same for a PyPI requirement (`name==1.2.3`), installed with pip. |
| `beam packages scan [DIR] [--no-cve] [--json]` | Scan what's installed in `node_modules` and `.venv`/`venv`/`env`, or one package folder; exit 2 on a critical finding. |

## Optional Jev judgments

Jev is disabled by default. A key alone does not enable it. See [Jev action judging](https://docs.agentbeam.com/agent-cli/jev) for data transfer, key handling, thresholds, and the difference between hook mode and explicit command exit status.

| Command | Behavior |
| --- | --- |
| `beam jev configure [--key-stdin] [--mode observe\|enforce] [--primitive noul\|score\|both] [--model MODEL]` | Enable remote checks; default to observation, both primitives, and `jev-latest`. |
| `beam jev status` | Show settings and key presence without exposing the key. |
| `beam jev judge FILE --dry-run` | Print redacted request data locally; no API call. |
| `beam jev judge FILE` | Judge the action without executing it; exit 0 for allow, 2 for review/deny, 1 for error. |
| `beam jev disable` | Disable checks, reset settings, and remove the stored key. |

Configuration must be run directly by the operator. Existing local policy takes precedence. Observation preserves the local hook decision, including on Jev failure; blocking requires explicit enforcement configuration.

## Optional judging with any model

Off by default, like Jev. See [Judge actions with any LLM or decision service](https://docs.agentbeam.com/agent-cli/decision-models) for the decision contract and safety behavior.

| Command | Behavior |
| --- | --- |
| `beam judge configure [--provider llm\|http] [--url URL] [--model MODEL] [--mode observe\|enforce] [--timeout-ms MS] [--key-stdin]` | Enable checks with an OpenAI-compatible model (default `gpt-4.1-nano` on OpenAI) or your decision service. |
| `beam judge status` | Show settings and key presence without exposing the key. |
| `beam judge check FILE [--dry-run]` | Judge an action file; exit 0 allow, 2 review/deny, 1 error. `--dry-run` prints the redacted request. |
| `beam judge disable` | Disable checks and remove the stored key. |

## App monitoring and dependency checks

Both need App monitoring turned on by an owner or admin, and either an app token in `BEAM_APP_TOKEN` or a machine connected with `beam connect`. See [App monitoring and dependency checks](https://docs.agentbeam.com/agent-cli/app-monitoring) for levels, data handling, alerts and LLM review.

| Command | Behavior |
| --- | --- |
| `beam monitor --file PATH [--file PATH...]` | Follow log files and access logs; send redacted findings. Waits while App monitoring is off. |
| `beam monitor --stdin [--no-echo]` | Read piped output, echoing it to stdout by default; exits when the pipe closes. |
| `beam monitor --app DIR` | Also check `DIR`'s lockfiles for known vulnerabilities at start and daily. |
| `beam monitor` | With no sources, watch what the settings files say (see `configure`). |
| `beam monitor --llm PROVIDER` | Review flagged lines with your own key: `openai`, `anthropic`, `gemini`, `groq`, `openrouter`, `mistral`, `deepseek`, `xai`, `ollama` or `custom`; `beam` uses the workspace's setting. |
| `beam monitor --max-cpu PERCENT` | The most of one core detection may use, 1–100 (default 25); past it, lines are skipped and counted until the next minute. |
| `beam monitor --config FILE` | Use this project settings file instead of `./beam.monitor.json`. |
| `beam monitor --deny-file PATH [--auth-deny-file PATH] [--llm-deny-file PATH] [--deny-format nginx\|plain] [--reload CMD]` | Write the addresses the workspace pauses to deny lists for your web server, and run `CMD` after each change. See [pausing attackers](https://docs.agentbeam.com/agent-cli/app-monitoring#pausing-attackers). |
| `beam monitor pause TARGET [--for 1h] [--scope all\|auth\|llm] [--reason TEXT]` | Pause an address, a range (up to /16, IPv6 /32) or `user:ID` for this app, whatever the pausing mode. Up to 7 days. |
| `beam monitor unpause TARGET [--scope SCOPE]` | Lift a pause now. It isn't paused automatically again for a day. |
| `beam monitor paused [--json]` | List what's paused for this app, and what a dry run would have paused. |
| `beam monitor configure [options]` | Save settings to `~/.beam/monitor.json` (0600): `--llm`, `--model`, `--base-url`, `--key-env NAME`, `--key-stdin`, `--forget-key`, `--file`, `--no-files`, `--app`, `--no-app`, `--max-cpu`, `--deny-file`, `--auth-deny-file`, `--llm-deny-file`, `--deny-format`, `--reload`, `--no-deny`. With no options, show the effective settings and which layer each came from. |
| `beam monitor configure --check` | Validate every settings layer (managed, user, project); exit 1 on a problem. |
| `beam monitor test [--llm PROVIDER]` | Send one test finding; it appears on the dashboard and goes through your alert workflows whatever the level. With `--llm`, also make one LLM check to prove the key works. |
| `beam monitor status [--llm PROVIDER]` | Show the app, on/off, level, LLM in use and where its key comes from, live alert workflows, the pausing mode and how many senders are paused, this month's usage, and where each setting came from. |
| `beam cve check [DIR] [--fail-on SEVERITY] [--depth N] [--json]` | Check lockfiles for known vulnerabilities; exit 0 clean, 2 found, 1 error. |

`beam monitor` never blocks or changes the application; with `--deny-file` it writes a deny list your web server reads. Its key for `--llm` comes from the variable you already use (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, ...) and goes only to that provider. See [settings files](https://docs.agentbeam.com/agent-cli/app-monitoring#settings-files) for the managed, user and project layers.

## Agent adapters

```sh
beam agent list
beam agent install claude-code
beam agent install-all
beam agent extract codex --limit 20
beam agent extract codex --save
```

`agent ls` aliases `agent list`. Extraction currently supports Claude Code and Codex. `--limit` applies to preview output, defaults to 200, and does not replace the scanner's source-file bounds.

## Rules and background services

```sh
beam rule list
beam rule reload
beam service install --port 4319
beam service status
beam service stop
beam service start
beam service logs
beam service uninstall
```

`rule ls` aliases `rule list`. Rule reload requires the running collector. Services support macOS launchd and Linux user systemd; Windows uses foreground `beam start`.

## Full removal

`beam uninstall` asks before removing the background service, Beam hook entries, local data, workspace registration, and global packages. `--keep-package` retains installed packages. `--yes` skips the interactive confirmation and should only be used in an already-approved offboarding workflow. Local deletion cannot remove historical data retained by a workspace.