CLI

Build and configure

From your source checkout:

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:

.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:

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

.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 or the SDK operation reference.

To expose tools to an agent host, use local MCP instead of treating CLI output as a model session.

---

Read this page as Markdown