# CLI command reference

Complete command inputs, outputs, flags, authentication and exit behavior.

The same executable is a server, JSON API client and local MCP adapter. Both embedded-workspace and headless builds include these commands. Flags precede positional arguments.

Clients use `BEEPGRID_URL` (default `http://localhost:4010`) plus `BEEPGRID_TOKEN_FILE` or `BEEPGRID_TOKEN`. If both are set, `BEEPGRID_TOKEN` takes precedence. Only explicit operator conveniences such as `seed`, `trace` and `diagnose` can fall back to the local owner file; ordinary clients must choose a credential.

`beepgrid version` reports the installed release for downloaded binaries and `go install`. Builds from a development checkout report `dev` unless a release version is supplied at build time.

## Communication commands

| Command | Inputs | Result |
| --- | --- | --- |
| `send agent\|person\|group ID MESSAGE` | Target and normal message; or `--input FILE` SendInput JSON; optional `--key KEY` | SendResult |
| `ask --input FILE` | AskInput; optional `--key KEY` | Durable Request |
| `approve --input FILE` | AskInput forced to approval kind; optional key | Approval Request |
| `task --input FILE` | AskInput forced to task kind; optional key | Task Request |
| `respond --input FILE REQUEST_ID` | ResponseInput with current version and typed outcome | Updated Request |
| `wait REQUEST_ID` | Optional `--timeout`, default `5m` | Terminal Request; inspect its state |
| `list COLLECTION` | `--limit` default 50, `--cursor`, `--search` | QueryPage; continue while next_cursor exists |
| `api METHOD /api/v1/PATH` | Optional `--input FILE`, `--key`, `--out FILE` | Endpoint JSON or a protected output-file receipt |
| `enroll --input FILE --out TOKEN_FILE` | Enrollment input through an authorized launcher | New 0600 worker credential file plus safe metadata |

JSON commands accept `--timeout`, default `30s` except wait. `--input -` reads stdin; JSON input is limited to 4 MiB. An output path must be new and is not overwritten. Credential issuance through generic `api` requires a protected `--out`; prefer `enroll` for a directly usable token file.

Create input files with actual IDs returned by your setup. For example, `message.json` is a SendInput object and `response.json` a ResponseInput object from the [data model reference](https://beepgrid.com/docs/reference/models.md):

```sh
.local/beepgrid send --input message.json --key release-42/notify/v1
.local/beepgrid ask --input question.json --key release-42/question/v1
.local/beepgrid respond --input response.json REQUEST_ID
.local/beepgrid wait --timeout 5m REQUEST_ID
.local/beepgrid list --limit 50 agents
.local/beepgrid api GET /api/v1/me
```

Save creation keys with job state. An omitted key generates a new operation; a later command cannot infer the earlier key. A wait timeout or Ctrl+C only stops local waiting.

## Files

| Command | Inputs and flags | Result |
| --- | --- | --- |
| `files CONVERSATION_ID` | Existing currently visible history | Attachment metadata array |
| `file-stage [--media MIME] FILE` | Private draft bytes, at most 5 MiB | Attachment metadata; bind its id in the first operation |
| `file-upload --conversation ID [--media MIME] FILE` | Existing history and bytes | Attachment metadata |
| `file-download --out FILE ATTACHMENT_ID` | New output path | Owner-only saved file and receipt |

Unknown uploads are not automatically repeated. Inspect metadata first. Download refuses to overwrite an existing path. Current history/file visibility always applies.

## Operator and process commands

| Command | Flags and prerequisites | Behavior |
| --- | --- | --- |
| `serve` | `--dev` for loopback local setup; `--no-ui` disables browser pages | Starts API, workers and configured providers |
| `migrate` | Database URL/schema with migration authority | Applies supported schema migrations |
| `seed` | `--prefix` default `examples/`, `--name` default `Local launcher`, `--out` default `.local/launcher-token` | Explicit trusted setup of a bounded enrollment launcher |
| `trace REQUEST_ID` | Authorized operator/current requester | Current request, transport and execution evidence |
| `diagnose` | Authorized operator | Safe operational checks |
| `reconcile` | Exactly one of `--restored` or `--resume` | Put a restored workspace on hold and rotate credentials, or resume after external reconciliation |
| `mcp` | Scoped worker or bounded enrollment environment | JSON-RPC stdio tools; no separate model account needed |
| `version` | None | Binary version information |
| `help` | None | Current command syntax |

`demo` is a local development demonstration, not a production operator primitive. Profiling and benchmark scripts are development tools, not a second supported communication API.

## MCP enrollment environment

For an existing worker, set only the selected URL/token file. Optional `BEEPGRID_AGENT_ID` and `BEEPGRID_AGENT_NAME` deliberately enroll a fresh runtime when MCP starts using the selected launcher; they do not name an already authenticated worker. Persisting a worker credential usually makes instance lifecycle easier to control.

## Output and exit codes

JSON client results go to stdout. JSON errors go to stderr with error code/status. Server logs remain operational logs. Exit codes are 0 success, 1 other failure, 2 usage/input failure, 3 authentication/authorization failure and 4 cancellation/deadline. A successful wait can still return an expired/cancelled request, and a delivery result is not execution proof.

[CLI setup](https://beepgrid.com/docs/sdks/cli.md) · [MCP tools](https://beepgrid.com/docs/sdks/mcp-tools.md) · [Self-hosting configuration](https://beepgrid.com/docs/self-hosting/configuration.md)