How the CLI and app share state
Beam Bench's agent-state model. What the CLI sees, what the app sees, and where they meet.
The Beam Bench CLI and the desktop app are two clients of the same backend. They can both inspect the same project, the same machine connection, and the same camera state. Knowing how they share that state is useful when you want to drive the app from a script.
The model
There is a single source of truth inside Beam Bench that owns:
- The active project.
- The machine connection.
- The camera state.
- The agent capability / state surface.
The desktop app's UI is one consumer of that state. The CLI is another. The HTTP / WebSocket API is the same surface.
What the CLI can do
beambench-cli agent state --json returns the current state of project, machine, selection, and camera, in a stable JSON schema. Use this to inspect what the app currently has loaded.
beambench-cli agent capabilities --json returns a registry of what operations are available, which CLI subcommands map to which backend operations.
beambench-cli agent guide --json returns a workflow hint for an external agent (like Claude) on how to drive the app.
What the CLI cannot do
The CLI does not have its own UI state. It cannot select a tool, open a panel, or open a dialog. Those are app-side actions; do them in the app, not from the CLI.
When the CLI needs the app running
Some operations require the app to do real work (rendering the canvas with overlay, capturing a camera frame). The CLI sends the request through and the app does the work; the result flows back to the CLI.
The camera overlay render command works this way. The CLI blocks until the app completes or times out (15 s).
Headless vs needs-app commands
| Need app running? | Examples |
|---|---|
| No (headless) | beambench-cli design render --png, beambench-cli project save, beambench-cli export svg, beambench-cli agent state |
| Yes | beambench-cli camera overlay render, beambench-cli camera capture (when using native camera), any UI-state inspection |