CLI command reference

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.

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.

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 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 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 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.
`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 for the managed, user and project layers.

Agent adapters

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

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.