Unified CLI
The Molar CLI (@molar/cli) is the operator interface for local development and
CI. npx molar-agent is its zero-dependency bootstrap: it provides init
and task-oriented docs, then delegates other commands when molar is installed.
Note:
This page lists shipped commands only. Cartographer URL generation and several scenario helpers are available via MCP (molar_generate_scenarios_from_url, etc.), not the CLI today.
Shipped commands
Onboarding & auth
| Command | Description |
|---|---|
molar init [--path] | Scaffold .molar/, config, agent hints (default path: current directory) |
molar login [--api-url] [--token] | Validate a PAT and save to ~/.config/molar/config.toml |
molar agent signup --human-email --name | Agent self-serve registration (see agent signup) |
molar agent signup verify --code | Submit human verification code |
molar agent signup status [--json] | Claim status, scopes, and product entitlements |
Flags for agent signup: --api-url, --human-email, --name, --harness (cursor | claude-code | codex), --note-to-human, --json.
Create PATs at app.molar.it → Settings → Tokens, or use agent signup for coding agents.
Scenarios
| Command | Description |
|---|---|
molar scenarios validate [glob] [--json] | Lint frontmatter + step grammar (default glob: .molar/scenarios/*.molar.md) |
molar scenarios compile [glob] [--out-dir] [--force] [--json] | Compile .molar.md → Playwright .spec.ts (default out-dir: .molar/.compiled) |
molar scenarios validate && molar scenarios compile && molar run
Running tests
| Command | Description |
|---|---|
molar run [pattern] [--watch] [--ci] [--against] [--json] | Run compiled scenarios via the Guard runner |
Pass Playwright flags after --: molar run checkout -- --reporter=html
--against accepts local, preview, or staging.
Universal automation & verification
Drive any website directly — not just compiled scenarios. See Universal automation for the full model.
| Command | Description |
|---|---|
molar run "<task>" --url <u> [--execution auto|local|hosted] [--json] | Execute a plain-English task in a real browser; localhost/private targets default to the local daemon |
molar extract "<schema>" --url <u> [--json] | Return structured JSON matching a schema (or description) |
molar verify "<claim>" --url <u> [--execution auto|local|hosted] [--json] | Browser-backed claim check → { pass, evidence, execution_mode } — the agent self-check gate |
--execution auto is the default. Loopback, .localhost, link-local, and
RFC1918/RFC4193 targets run through the authenticated local CloakBrowser daemon
without hosted credentials. Public URLs run through hosted Cartographer. Use
--execution local or --execution hosted to override this choice.
Local results write owner-only screenshot, WebM recording, and HAR evidence
under ~/.molar/artifacts/ and return those paths in JSON. Automatic hosted
fallback is allowed only when the daemon or browser fails before navigation;
Molar never retries a task whose side-effect outcome may be unknown.
Local browser daemon
Low-latency local browser control (Browser Use technique) — one warm Chromium reused across isolated named sessions and ephemeral natural-language task contexts. Auto-starts an owner-only Unix-socket daemon beside CloakBrowser on first use.
| Command | Description |
|---|---|
molar browser open [--session <name>] [--url <u>] | Open (or resume) a named browser session |
molar browser state [--session <name>] [--json] | Bounded, token-efficient a11y/element snapshot with stable refs |
molar browser click <ref> [--session <name>] | Click a ref returned by state |
molar browser input <ref> <value> [--session <name>] | Type into a ref (typed values are never echoed back) |
molar browser sessions [--json] | List active sessions |
molar browser close [--session <name>] | Close a session |
Refs are revision-bound and URL secrets / raw selectors are stripped from output — safe for agent consumption.
Clones (local)
| Command | Description |
|---|---|
molar clone <kind> --start [--seed] | Start stripe, twilio, email, auth, or s3 clone |
molar clone <kind> --stop | Stop the clone |
Requires @molar/clones installed. Cloud clone lifecycle uses MCP (molar_clone_spawn, molar_clone_world, etc.) or the dashboard.
Traces
| Command | Description |
|---|---|
molar trace open <target> [--local] | Open a hosted trace ID or local trace.zip |
Hosted traces require MOLAR_API_URL. Local files open via npx playwright show-trace.
MCP & utilities
| Command | Description |
|---|---|
molar mcp serve [--cloud-access] [--surfaces] [--transport] [--port] | Local MCP server (default surfaces: cartographer, clones, guards, trace) |
molar doctor [--json] | Dependency health check |
molar upgrade [--check] [--force] | Self-update from GitHub releases |
mcp serve transport defaults to stdio when piped and http on port 4200 in a TTY. Set MOLAR_MCP_TRANSPORT or pass --transport stdio|http.
Not in CLI yet (use MCP or dashboard)
| Capability | Use instead |
|---|---|
| Generate scenarios from URL | MCP molar_generate_scenarios_from_url |
| List/add/migrate scenarios | Dashboard or MCP molar_list_scenarios |
| Clone snapshot/restore (cloud) | MCP molar_clone_world or Clones dashboard |
| Guard PR gate setup | app.molar.it → GitHub App |
Configuration
| File | Purpose |
|---|---|
~/.config/molar/config.toml | User API URL, token |
.molar/config.toml | Project overrides |
.molar/scenarios/*.molar.md | Scenario source |
Distribution
Bootstrap with npx molar-agent init --json, then install the full command set
with npm i -g @molar/cli.
Telemetry is off by default (MOLAR_TELEMETRY=1 to enable).