Beam logoBeam

CLI Command

beam doctor

Check whether the local machine is ready to use Beam safely and reliably.

beam doctor is the first support command. Run it after install, after login, and whenever inspect, export, compare, or MCP startup behaves unexpectedly.

Doctor checks the Node.js version, Beam version, local Beam directories, credential presence, cache access, project readiness, and basic configuration state. It should avoid hidden network work unless the command clearly documents it.

Human output should be direct and actionable. If auth is missing, the next step is beam login. If a Figma call is blocked, Beam should explain access, scope, or rate-limit state instead of returning a generic failure.

--json is intended for scripts, CI checks, and support tooling. It should use structured statuses that are stable enough for automation.

bash
1beam doctor2beam doctor --json

Run Sequence

  1. Run beam doctor immediately after installation.
  2. Run it again after beam login.
  3. Run it inside the project where you plan to inspect, export, or compare designs.
  4. Use beam doctor --json when capturing diagnostics for automation.

Expected Output

A healthy run should show passed checks for Beam version, Node.js version, local directories, credential state, cache access, and project readiness.

Files And Artifacts

  1. Reads local Beam config and cache directories
  2. Does not create design snapshots

Next Step

If doctor passes, run beam inspect <figma-url>.

Recovery Paths

  1. If auth is missing, run beam login.
  2. If Node is too old, install Node.js 22.12 or newer.
  3. If cache directories are not writable, fix filesystem permissions before using inspect or export.