Using the CLI

Drive Beam Bench from a terminal. Open projects, render canvases, inspect state, export files.

The beambench-cli binary is built alongside the Beam Bench app. Use it for scripting, batch operations, and headless rendering.

What you need

Beam Bench installed (or the repo checked out, if you build from source).
A terminal (Terminal on macOS, PowerShell on Windows, any shell on Linux).
For some commands: the app running. Most do not require it.

Where to find it

The binary is named beambench-cli and is installed alongside the desktop app. The exact path depends on the platform's bundle layout for your current build; check the install directory.

You may want to put it on your PATH, or alias it for brevity:

alias bb=beambench-cli

The examples below use the full beambench-cli name.

Steps

1. Verify the CLI works

beambench-cli --help

Lists all subcommands. Each subcommand has its own --help.

2. Inspect agent state

beambench-cli agent state --json

Returns a JSON dump of the current project, machine connection, selection, and camera state. Useful for scripting and debugging.

3. Render the canvas to a PNG (headless)

beambench-cli design render --png /tmp/out.png --pixels-per-mm 4

Renders the current project's design (no camera overlay) to a PNG. Works without the GUI running.

4. Render with camera overlay (requires GUI)

beambench-cli camera overlay render --output /tmp/overlay.png --view fit

Captures the canvas with the current camera overlay frame. Requires the desktop app to be running, the CLI sends a reverse-RPC to the app, which does the render and writes the file.

5. Open a project

beambench-cli project open /abs/path/to/project.lzrproj

The path is positional. To save back, use beambench-cli project save (no args, overwrites the open file) or beambench-cli project save-as /abs/path/to/new.lzrproj.

6. Export files

beambench-cli export svg --path /abs/path/out.svg
beambench-cli export gcode /abs/path/to/project.lzrproj /abs/path/out.gcode

SVG, DXF, PDF, EPS, and AI exports take --path. G-code takes two positional arguments: input .lzrproj and output .gcode.

7. Inspect ports / capabilities

beambench-cli ports
beambench-cli agent capabilities --json
beambench-cli agent guide --json

agent capabilities returns the schema of what the CLI can do. agent guide returns a bootstrap workflow for external agents.

What the CLI cannot do

Select a canvas tool.
Open or close a panel / dialog.
Trigger a hotkey.
Drag-and-drop on the canvas.

For those, drive the GUI directly (e.g. via computer-use or AppleScript), not via the CLI.

Examples

Batch-render every project in a folder

for f in /path/to/projects/*.lzrproj; do
  beambench-cli project open "$f"
  beambench-cli design render --png "${f%.lzrproj}.png" --pixels-per-mm 4
done

Snapshot machine state every minute

while true; do
  beambench-cli agent state --json > "/tmp/state-$(date +%s).json"
  sleep 60
done

Verify it worked

beambench-cli --help runs without error.
A design render produces a non-zero-size PNG.
agent state returns valid JSON.

Using the CLI

On this page