# CLI quickstart

> Install Beam, run beam setup, see your agents in the dashboard. Two commands, about two minutes.

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

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):

```sh
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:

```sh
curl -fsSL https://agentbeam.com/install.sh | bash
```

```sh
export PATH="$HOME/.local/bin:$PATH"
```

On **Windows**, in PowerShell:

```powershell
irm https://agentbeam.com/install.ps1 | iex
```

Whichever you used, check it worked:

```sh
beam --version
```

A version number means Beam is installed and you can run `beam` from any folder.

## Step 2 — Connect it

```sh
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.

> **You're connected — now watch it live.** Open **[app.agentbeam.com/dashboard/activity](https://app.agentbeam.com/dashboard/activity)** to see what your agents do, as they do it. This machine is listed on the [Agents page](https://app.agentbeam.com/dashboard/agents).

## Step 3 — Check your dashboard

```sh
beam whoami
```

Prints the ID this machine was given and the workspace it joined. If that matches what you see on the [Agents page](https://app.agentbeam.com/dashboard/agents), 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](https://app.agentbeam.com/dashboard/activity) within seconds — and on this machine in Studio:

```sh
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.

> **Prefer npm if you have Node.js.** The standalone installer serves a pinned binary [release](https://github.com/whyashthakker/beam-cli/releases), which can trail the current npm version. The npm package is what `beam update` tracks.

Setting up a Raspberry Pi? Follow the [Raspberry Pi guide](https://docs.agentbeam.com/agent-cli/raspberry-pi).

## 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](#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](https://docs.agentbeam.com/agent-cli/agent-hooks) — per-assistant hook details
- [Scan skills & MCP configs](https://docs.agentbeam.com/agent-cli/scanning) — offline scanning with `beam scan`
- [Scan npm & PyPI packages](https://docs.agentbeam.com/agent-cli/package-scanning) — check a package before installing it with `beam add package`
- [Workspace policies](https://docs.agentbeam.com/agent-cli/policies) — what to observe, warn about, or restrict
- [Run in the background](https://docs.agentbeam.com/agent-cli/service) — manage the Beam service
- [Data, redaction & export](https://docs.agentbeam.com/agent-cli/data-privacy) — what leaves the machine once connected
- [Connect a workspace](https://docs.agentbeam.com/agent-cli/connect) — enrollment codes, re-pairing, self-hosted
- [CLI troubleshooting](https://docs.agentbeam.com/agent-cli/troubleshooting) — the longer list