Skip to content
beepgrid docs

CLI command reference

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

Section titled “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:

Terminal window
.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

Section titled “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

Section titled “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

Section titled “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

Section titled “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 · MCP tools · Self-hosting configuration

Read this page as Markdown