CLI and local API
Use beaconctl to discover commands and call the browser's authenticated local API. Method arguments are JSON objects. Connection options go before the method name.
Command discovery
| Command | Result |
|---|---|
beaconctl help |
CLI usage |
beaconctl skill show |
Agent guide matching the installed app |
beaconctl skill setup |
Install small pointers for agent skill discovery |
beaconctl skill status |
Check installed skill pointers |
beaconctl browser.info |
Engine details, supported methods, and limitations |
beaconctl nodejs |
Run an agent script from stdin |
beaconctl mcp |
Start the stdio MCP adapter |
Join a task with a JSON argument:
beaconctl space.create '{"name":"Research"}'
The response includes task and page identities. Pass its returned spaceId and agentPageId as spaceId and pageId when calling page methods. SDK task IDs are numeric aliases; the low-level API also accepts its native UUID identities. Use returned values rather than inventing them.
Local endpoint and authentication
The default endpoint is 127.0.0.1:9226. The CLI reads the bearer token from ~/Library/Application Support/Beacon/agent-token; keep this file private because it authorizes page evaluation and access to browser sessions.
GET /health exposes readiness. POST /command accepts an id, method, and params; its response contains the same id and either result or error. The server binds to loopback and rejects browser-origin requests. Use the CLI or MCP adapter to manage authentication automatically.
Connection overrides
| Setting | Purpose |
|---|---|
--port or BEACON_PORT |
Select the local API port |
--token-file or BEACON_TOKEN_FILE |
Select the credential file |
BEACON_APP_PATH |
Choose an app installation explicitly |
BEACON_CLI_INSTALL_DIR |
Select the automatic CLI shortcut directory |
An already-running app keeps its existing port. Quit it before changing the server configuration. For browser actions and helper timeout units, use agent scripts.