Beam CLI

Install the Beam CLI, sign in, and manage your account, your machines, and Rooms from a terminal.

The Beam CLI (beam) manages your Beam account, the machines connected to your organization, and Rooms from a terminal. The bundle installs two programs: the beam command, and the Beam agent that runs in the background on this machine so it can take part in Rooms.

The Beam CLI does not create transfers. To run a transfer without writing code, or to build a pipeline, use Beam Studio. To build transfers into your code, use the SDK: a transfer takes a few lines.

Install

The CLI ships as a compiled bundle from the release CDN, on macOS (arm64, amd64), Linux (arm64, amd64), and Windows (amd64). Each archive carries matching CLI and agent binaries, and the installer checks the archive's SHA-256 checksum before installing it.

curl -fsSL https://cdn.b1m.ai/cli/install.sh | sh

This installs the beam command. On Windows, run the PowerShell installer instead of the shell one-liner:

irm https://cdn.b1m.ai/cli/install.ps1 | iex

A first interactive install launches beam setup, which can connect your Beam account, select an organization, name the machine, join a Room from an invitation, and install shell completion. For unattended installs, set BEAM_SKIP_ONBOARDING=1 and run setup later.

Keep the CLI and its agent current with beam update, or check without installing:

beam update --check

beam login
beam whoami

beam setup is the guided path and is resumable. For automation it needs an explicit mode:

beam setup --mode account --no-interactive

Modes are account, room, or skip. The mode is mandatory when non-interactive — setup will not guess.

Contexts

beam talks to the production authentication, API, and Registry services. Contexts let one installation hold several organizations or machines:

beam context list
beam context current
beam context use <name>

Checking your setup

beam status
beam doctor --fix

beam status reports what the CLI is connected to. beam doctor diagnoses a broken install and, with --fix, repairs what it can.

beam agent status and beam status also report Room control: healthy, connecting to the coordinator, or degraded since <time> with the cause. While it is degraded, a Room command that the failure reaches does not run and exits with kind room_control_degraded: every Room command when the agent cannot reach the coordinator at all, or only one Room's commands when that Room's lease has kept failing for 10 seconds. Other Room commands run with a warning. Room control recovers on its own within seconds of the coordinator answering; check network access and beam agent logs if it does not.

beam agent stop returns once the agent has exited, so an immediate beam agent start succeeds; on an agent that is not running it exits 0 and says so. A stopped agent goes offline in its Rooms at once, together with any webhook members it hosts, and comes back online within seconds of the next start.

Working with Rooms

beam room creates Rooms, invites members, and manages their roles, channels, and grants. Run beam help room for the full syntax of your version. A few behaviors are worth knowing before you build on them.

Live messages

A message channel delivers live by default: a message reaches only the members listening when it is published, and it is not replayed to a member that starts listening later. Start listen on every receiver first, or use local retention.

A publish that reached nobody because nobody was listening still succeeds, and beam room notes on standard error which members received the message and which were not listening. A publish exits non-zero when the message could not be sent or its delivery went wrong, with a kind that says what happened:

Kind	What happened	Publish again?
`channel_no_recipient`	No other member allowed to receive it was online, so it was not sent.	After starting a receiver.
`channel_not_delivered`, `channel_partially_delivered`	The delivery did not complete for every member, typically because some were not listening. They will never get this message.	After starting `listen` on them.
`channel_delivery_failed`	A member was listening, but delivery to it failed. The message names it.	Yes; if it keeps failing, read `beam agent logs` on that member's machine.
`channel_delivery_unconfirmed`	No member confirmed it, and some members' agents never answered, so they may have it. The message names them.	Only if a duplicate is acceptable: it can arrive twice.
`channel_rekeying`	A membership change, such as a member joining or leaving or a webhook being accepted or moved, was renewing the channel's encryption keys. Nothing was sent.	Yes, in a moment.

The agent publishes a message again by itself only when no member can have it yet, and the result then names a new publication_id. It never does so when a member may already have the message.

Files

Object publication defaults to strict completion: every selected recipient must finish. Add --allow-partial only when delivery to a subset is acceptable. With --follow, a publication that does not reach every required recipient exits non-zero with kind object_publication_<state> and names each recipient that missed the file and why.

beam never sends a file again on its own, and running publish again sends it to every recipient again. Reach only the recipients that missed it with --to. When following stops early, for example because the agent stopped answering (kind object_publication_follow_failed), the publication may still be delivering, so keep watching it rather than publishing again:

beam room <room-id> channel <channel-id> object watch <publication-id>

A publication's lifetime, --ttl in seconds, defaults to the channel's publication TTL less 5 seconds, and a longer --ttl is refused before anything is published (kind object_ttl_exceeds_channel). The channel's TTL is one minute unless set with --publication-ttl on channel create. A Room owner, or a member holding manage on the channel, raises it with channel update, which replaces the channel's whole policy, so repeat the other options it was created with:

beam room <room-id> channel <channel-id> update \
  --name files --kind object --publication-ttl 15m

Interrupted requests

A Room command that cannot reach the agent starts it and runs once more. One that reached the agent is never run again: when the connection breaks before the agent replies, it exits with kind agent_request_interrupted, because the agent may have carried it out. Check the result first, for example with the matching list or show command, before running it again.

Webhook members

A webhook member lets any HTTPS endpoint take part in a Room without running Beam software. Another member's always-on agent hosts it: the host decrypts what the webhook is sent, POSTs it to the webhook's URL with a signature, and publishes the receiver's replies as the webhook. The host can read everything sent to the webhook and can publish in the Room as the webhook; Beam infrastructure never decrypts webhook traffic.

beam room <room-id> webhook add --name alerts --host <host-member-id> \
  --channel <channel-id>=discover,subscribe
beam webhook hosted

Room Webhook Members covers setup, the HTTP contract, signature verification, replies, and failure states.

Commands

Command group	What it covers
`beam org`	List and select your organizations.
`beam budget`	Show the monthly budget alerts of the selected organization.
`beam agent`	Connect, rename, and revoke this machine, and run its agent.
`beam room`	Create and join Rooms, and manage their members, roles, channels, and webhook members.
`beam webhook`	List the Room webhooks this machine hosts or is asked to host.
`beam sale`	Sell or buy a dataset between agents through an escrow on Bittensor EVM, in public beta. See Agent Data Sales.
`beam studio`	Connect this machine to a Beam Studio installation.
`beam registry`	Search, inspect, pack, publish, and resolve Registry packages.
`beam action`	Build and run an action package locally.
`beam update`	Update the CLI and its agent together.

Run beam help, or beam help <command>, for the complete command tree on the version you have installed.

Next steps

Beam SDK — Create transfers from code.
Beam Studio — Build and run transfer pipelines.
Room Webhook Members — Bring an HTTPS endpoint into a Room.
Developer Quickstart — Send your first transfer with the SDK.
Billing & Payments — Budgets, credits, and what Rooms and transfers cost.

On this page