CLI quickstart
Install Beam, run beam setup, see your agents in the dashboard. Two commands, about two minutes.
On this page
Every command on this page is typed into a terminal — the Terminal app on macOS (Applications → Utilities) or Windows Terminal / PowerShell on Windows. Copy a command, paste it, press Enter.
Step 1 — Install Beam
If you have Node.js (version 20.17 or newer — type node --version to check):
npm i -g @agent-beam/beam
No Node.js? Use the standalone installer instead. It brings everything it needs with it.
On macOS or Linux, run these two lines:
curl -fsSL https://agentbeam.com/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"
On Windows, in PowerShell:
irm https://agentbeam.com/install.ps1 | iex
Whichever you used, check it worked:
beam --version
A version number means Beam is installed and you can run beam from any folder.
Step 2 — Connect it
beam setup
Beam finds the AI coding assistants on your machine, asks which ones to watch, then opens your browser so you can sign in and pick your workspace. Approve it there and the terminal continues on its own — leave the window open until it prints its summary.
Step 3 — Check your dashboard
beam whoami
Prints the ID this machine was given and the workspace it joined. If that matches what you see on the Agents page, you are set.
Step 4 — See your first event
Open one of the assistants Beam is now watching and ask it to do something harmless, like listing the files in a project. It shows up on your dashboard's Activity page within seconds — and on this machine in Studio:
beam studio
That's the whole setup. Everything below is detail you only need if something looks off.
What beam setup asks you
Five prompts. Nothing is changed without your confirmation.
| Prompt | What happens if you say yes |
|---|---|
| Pick your agents | Adds Beam's hook to each assistant you check, keeping any configuration those assistants already had, and routes local MCP servers through Beam |
| Connect to your dashboard? | Opens a one-time link in your browser. Sign in, pick the workspace, approve — there is no code to type |
| — | Downloads your workspace's policy to this machine |
| Start the background service? | Beam keeps running after you close the terminal or restart the machine |
| — | Prints a summary of hooks, dashboard, policy, and service |
Said no to something? You can do it later: beam connect pairs with the dashboard, beam agent install <agent> adds a hook, beam service install runs Beam in the background, beam start runs it in the current terminal window.
If your browser does not open by itself, setup prints the link — open it manually. Treat that link like a password; do not paste it into a ticket or chat.
Where Beam gets installed
With npm, Beam goes wherever your global npm packages live (npm prefix -g). The standalone installer puts it in ~/.local/bin on macOS and Linux, or %LOCALAPPDATA%\Programs\Beam on Windows, and adds that folder to your PATH so the beam command is found. Set BEAM_INSTALL_DIR first to choose a different folder.
The export PATH line in Step 1 only applies to the terminal window you typed it in. Add the same line to your shell profile (~/.zshrc or ~/.bashrc) so new windows find beam too.
Setting up a Raspberry Pi? Follow the Raspberry Pi guide.
If something looks wrong
| What you see | What to do |
|---|---|
beam: command not found | The install folder is not on your PATH — see where Beam gets installed above |
node: command not found | You do not have Node.js. Use the standalone installer in Step 1 |
| Machine missing from the dashboard | Run beam setup again and approve the browser prompt in the workspace you expected |
| No activity showing up | beam agent list shows which assistants are hooked, beam service status shows whether Beam is running |
A PreToolUse event is an action your assistant proposed. It does not prove the action ran or succeeded.
Next steps
- Connect coding assistants — per-assistant hook details
- Scan skills & MCP configs — offline scanning with
beam scan - Scan npm & PyPI packages — check a package before installing it with
beam add package - Workspace policies — what to observe, warn about, or restrict
- Run in the background — manage the Beam service
- Data, redaction & export — what leaves the machine once connected
- Connect a workspace — enrollment codes, re-pairing, self-hosted
- CLI troubleshooting — the longer list
Set this up with your coding agent
Install the agentbeam-setup skill for Claude Code, Codex, Cursor, Gemini CLI, OpenCode and Copilot, then ask your agent to set up AgentBeam on this machine. Beam scans the skill before it installs.
npx -y @agent-beam/beam add skill agentbeam-setup -g --all-agents