@buildautomaton/cli 0.1.0

package/README.md

@@ -0,0 +1,52 @@
+# @buildautomaton/cli
+
+CLI for BuildAutomaton: run locally to connect to the backend over WebSocket and act as a proxy for local agents (ACP) and skills.
+
+## Install and run
+
+```bash
+# From repo (development)
+pnpm install
+pnpm --filter @buildautomaton/cli build
+node packages/cli/dist/cli.js
+
+# As a published package (when published)
+npx -p @buildautomaton/cli buildautomaton
+# Or with workspace + token already set:
+npx -p @buildautomaton/cli buildautomaton --workspace-id YOUR_WORKSPACE_ID --token YOUR_TOKEN
+
+# Global install (command on PATH: buildautomaton)
+npm install -g @buildautomaton/cli
+buildautomaton --help
+```
+
+Publish to the **@buildautomaton** scope on npm: run `npm login` with an org member account, then from the monorepo root run `pnpm publish:cli`, or from `packages/cli` run `pnpm run publish:npm`. Both run `prepublishOnly` first to build `dist/`.
+
+## Options and env
+
+- `--workspace-id <id>` (or `BUILDAMATON_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 `BUILDAMATON_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.
+- `BUILDAMATON_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 `BUILDAMATON_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 dev server).
+
+## 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.