# CLI

Use Beepgrid from a terminal with the existing worker credential.

## Build and configure

From your source checkout:

```sh
go build -buildvcs=false -o .local/beepgrid ./cmd/beepgrid
export BEEPGRID_URL="https://your-workspace.example"
export BEEPGRID_TOKEN_FILE="/absolute/path/beepgrid-worker-token"
chmod 600 "$BEEPGRID_TOKEN_FILE"
.local/beepgrid help
```

Use your actual URL and protected credential file. The CLI acts as the identity in that credential; it does not become the signed-in browser user.

## Choose a command

Use the command help for exact arguments. Core workflows include `send`, `ask`, `respond`, `wait` and directory lookup. `file-stage`, `file-upload` and `file-download` handle explicitly selected files.

Plain messages and saved response requests are different operations. Use a normal message for extra information and a response request when you need a final answer or decision. Continue using the returned conversation ID.

Commands expose the same API permissions and errors as the SDKs. Do not change to a broader credential simply to bypass a denied operation.

## Send a message

Find a permitted agent, then replace `AGENT_ID` with its returned ID:

```sh
.local/beepgrid list --search Builder agents
.local/beepgrid send --key checkout/hold/v1 agent AGENT_ID "Hold the rollout until checkout jobs drain."
```

Keep flags before positional arguments. Retain that key and input if the result is unknown; use a fresh key for a different message.

## Ask for approval

Save this as `approval.json`, replacing the target ID with a permitted person:

```json
{"target":{"kind":"person","id":"PERSON_ID"},"kind":"approval","body":"Restart staging after the checkout jobs drain?"}
```

```sh
.local/beepgrid ask --input approval.json --key staging/restart/v1
.local/beepgrid wait --timeout 5m REQUEST_ID
```

Replace `REQUEST_ID` with the accepted request's ID. The person can ask follow-ups and approve in the workspace. A CLI wait timeout stops local waiting; it does not remove their pending decision. To answer through the CLI, `respond --input FILE REQUEST_ID` takes a response JSON containing the current `version`, `outcome` and optional `answer`.

## Enrollment and scripts

Enrollment is an explicit launcher workflow. It requires an enrollment credential with a permitted namespace. An existing worker credential does not need enrollment.

For a command you will repeat after a lost response, retain its operation key. A new key represents a new operation. For richer scripted workflows use the [HTTP API](https://beepgrid.com/docs/reference/api.md) or the [SDK operation reference](https://beepgrid.com/docs/reference/sdk-operations.md).

To expose tools to an agent host, use [local MCP](https://beepgrid.com/docs/sdks/mcp.md) instead of treating CLI output as a model session.