Using the CLI

Inspect and edit the running app through its local API, or export G-code directly.

The beambench-cli binary is distributed alongside the desktop app. Most project, design, machine, profile, and state commands are clients of the app's local API. They require the app to be running with Settings > General > Local API enabled.

Keep Allow network devices to connect off for scripts running on the same computer. The CLI reads the configured API port from app settings; the default is 5900.

Find available commands

beambench-cli --help
beambench-cli agent capabilities --json
beambench-cli agent guide --json

Help works without the app. Capabilities and live state use the API. Run a subcommand with --help to see its parameters for the installed version.

Open and inspect a project

beambench-cli project open /abs/path/project.lzrproj
beambench-cli agent state --json

Opening a project changes the project in the desktop app. Save work before running scripts that replace or edit it.

beambench-cli project save
beambench-cli project save-as /abs/path/copy.lzrproj

Render and export

beambench-cli design render --png /tmp/design.png --pixels-per-mm 4
beambench-cli export svg --path /tmp/design.svg

These commands use the running app's project through the API. Design rendering does not require a visible canvas, but it still requires the server.

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

Camera-overlay rendering also requires the app's frontend to service the render request. It is not a headless replacement for the camera workflow.

Commands that work without the app

Serial-port listing, help, and the positional G-code export have direct local paths:

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

Standalone G-code export uses a locally saved machine profile and the desktop's planning and output checks. It cannot read a live machine position. Read G-code output for profile and placement requirements.

Automation and conflicts

Design transactions use the current project revision. If another edit, project switch, or close invalidates the captured project, the transaction is rejected. Refresh state and reassess the operation before retrying; do not overwrite concurrent user edits with an old snapshot.

Commands that can move the machine, fire the laser, send raw G-code, or change air assist require their corresponding confirmation flags. Inspect the command help and intended action before supplying them.

The CLI does not select canvas tools, rearrange panels, or trigger shortcuts. Those are desktop UI actions.