@buildautomaton/cli

CLI for BuildAutomaton: run locally to connect to the backend over WebSocket and act as a proxy for local agents over ACP.

Install and run

# From repo (development)
pnpm install
pnpm --filter @buildautomaton/cli build
node packages/cli/dist/cli.js

# As a published package (when published)
npx @buildautomaton/cli
# Or with workspace + token already set:
npx @buildautomaton/cli --workspace-id YOUR_WORKSPACE_ID --token YOUR_TOKEN

Options and env

• --workspace-id <id> (or BUILDAUTOMATON_WORKSPACE_ID) – optional. If omitted and no token, the CLI opens the browser so you can sign in and pick a workspace; a token is then created and sent to the CLI.
• -n, --name <name> – optional. When creating a new bridge via the browser flow, use this as the bridge name. Must be alphanumeric and underscores only (e.g. dev_machine_1). If omitted, a random name is chosen.
• --api-url <url> (or BUILDAUTOMATON_API_URL) – default https://localhost:8787 (wrangler dev; HTTP and WebSocket use this port)
• --token <token> (or BUILDAUTOMATON_AUTH_TOKEN) – optional; bridge token from the dashboard (Bridges page) or from a previous browser sign-in. When set with a workspace, the CLI connects immediately.
• BUILDAUTOMATON_APP_URL (or APP_URL) – used when no token/workspace to open the browser for the sign-in flow (e.g. https://app.example.com).
• --agent <command> (or BUILDAUTOMATON_AGENT_CMD) – optional; run an ACP agent (e.g. cursor agent). Prompts received over the bridge are forwarded to this agent.

Authentication

• Primary (browser): Run the CLI with no --workspace-id and no --token. It connects to the backend, opens your browser to the dashboard bridges/connect page, and you sign in. If you have one workspace it is used automatically; if you have several, you pick one. A bridge access token and refresh token are created and sent to the CLI; the CLI saves them under ~/.buildautomaton/config.json keyed by API URL so localhost and production keep separate credentials. On subsequent runs the CLI loads the entry for the current --api-url and connects immediately. If the access token is rejected, the CLI tries POST /api/bridges/tokens/refresh with the saved refresh token before asking you to sign in again. Use --no-config to ignore saved auth and go through the browser flow again.
• Backup (token): On the dashboard, go to Bridges and create a bridge token. Use that value as --token with --workspace-id to connect without opening the browser. New tokens include a refresh token in the API response (shown once); browser-linked CLIs store it automatically in config.

Features

1. WebSocket bridge – Connects to the backend at /ws/workspace/:workspaceId. The UI can send prompts, skill calls, and proxy requests through this connection.

2. ACP client – By default the CLI is set up to run an Agent Client Protocol client that talks to one or more local agents (e.g. Cursor CLI, Claude Code). Prompts sent over the bridge can be forwarded to the local agent; responses are streamed back.

3. Local proxy – Requests from the backend to “call a local URL” are executed on the machine running the CLI (e.g. GET http://localhost:3000/api/status). Only localhost is allowed.

4. Skills – Each skill defines operations (with English descriptions and params). The UI/backend can invoke them; the CLI runs the operation locally.

   • preview – Start/stop/status for a local preview server (e.g. Next.js preview environment).

Adding a local agent in the UI

Open Bridges, click a bridge, then the Overview tab. Under Local agents, add a type (Cursor, Codex, or Claude Code). The backend registers that agent for that bridge; when this CLI is connected with a matching --agent command, prompts can be routed to the local tool over ACP.