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.
1beam doctor2beam doctor --json
Run Sequence
- Run
beam doctorimmediately after installation. - Run it again after
beam login. - Run it inside the project where you plan to inspect, export, or compare designs.
- Use
beam doctor --jsonwhen 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
- Reads local Beam config and cache directories
- Does not create design snapshots
Next Step
If doctor passes, run beam inspect <figma-url>.
Recovery Paths
- If auth is missing, run
beam login. - If Node is too old, install Node.js 22.12 or newer.
- If cache directories are not writable, fix filesystem permissions before using inspect or export.
