The CLI at a glance

The microlab CLI offers from the terminal everything a user can do in the desktop app: manage the catalog (micros, scenarios, mocks, settings), start and stop scenarios, observe status and logs, and import/export. UI and CLI share the same engine through the operations registry, so they don’t diverge.

Run

The CLI needs the compiled engine (npm run build:electron).

node bin/microlab.js <command>   # direct
npm run cli -- <command>          # via npm (note the -- separator)
microlab <command>                # if you registered the global with npm link

Global flags

Flag	Effect
--json	JSON output on one line, for scripts. Errors go to stderr as {"error": "..."}.
-p, --project <path>	MicroLab project root (the folder with .microlab/).
-V, --version	Version.
-h, --help	Help (all subcommands have it).

Exit codes

Code	Meaning
0	Success.
1	Execution error (the operation failed).
2	Usage error (invalid command/flags).
3	The command requires a live engine and there is none.
4	Timeout (for example waiting for the micros to be healthy).
5	Requires a paid plan the account doesn’t have.

Paid access

If the project configures login, the CLI (capability cli), the MCP (mcp) and the copilot (chat) are paid and independent. The entitlement is obtained by signing in to the app at least once. In projects without login, the CLI has no restrictions. See Capabilities.

Live engine vs in-proc

The micros are child processes of the engine, so something must stay alive after microlab start. The CLI resolves each command like this:

1. If there is a live engine (the app open or the headless daemon the CLI itself launches), the command runs against it over HTTP: the CLI sees and governs the same state as the UI.
2. If there isn’t, the stateless operations (catalog, mocks on disk, settings, bundles) run in-proc over .microlab/. Those requiring live state fail with exit 3.

microlab start launches the daemon automatically if needed; microlab daemon stop shuts it down.

See also

• Commands by group · Control server · Typical flows