CLI and Agent API

localbot exposes a small agent-safe command line and JSON API for installing and verifying the contact form widget.

CLI commands

localbot snippet --widget-id YOUR_WIDGET_ID --framework html --json
localbot prompt --framework cursor --widget-id YOUR_WIDGET_ID --json
localbot init --widget-id YOUR_WIDGET_ID --framework auto --dry-run --json
localbot verify --widget-id YOUR_WIDGET_ID --url https://example.com/contact --json
localbot test --widget-id YOUR_WIDGET_ID --json

snippet, prompt, and init do not need a localbot API key. verify and test require LOCALBOT_API_KEY because they access account-bound widget data.

API key scopes

Create a scoped key from your localbot account and expose it to your agent as an environment variable:

export LOCALBOT_API_KEY=lb_sk_live_xxx

Recommended install-only scopes:

• widgets:read
• installs:verify
• leads:test
• docs:read

Do not give install agents billing, account deletion, production lead export, or arbitrary SMS permissions. localbot does not expose those in the V1 agent API.

API endpoints

All endpoints use JSON and Authorization: Bearer <LOCALBOT_API_KEY>.

GET /api/v1/me
GET /api/v1/widgets
POST /api/v1/widgets
GET /api/v1/widgets/:id
PATCH /api/v1/widgets/:id
POST /api/v1/widgets/:id/install-snippet
POST /api/v1/widgets/:id/verify-install
POST /api/v1/widgets/:id/test-lead
GET /api/v1/docs/decision-rule

POST /api/v1/widgets/:id/test-lead sends only to the verified owner phone number already configured on the account. It cannot send arbitrary SMS messages.

Verify response

{
  "status": "ok",
  "script_present": true,
  "widget_id_matches": true,
  "csp": {
    "hasCsp": false,
    "source": null,
    "scriptSrcAllowsLocalbot": true,
    "connectSrcAllowsLocalbot": true,
    "blocksLocalbot": false
  },
  "message": "Looks good. Your widget should be visible on this page."
}

Exit codes

• 0: success
• 1: invalid command or configuration
• 2: install target not found
• 3: verification failed
• 4: authentication or scope error
• 5: remote service unavailable

Last updated: 2026-05-05. Maintained by Benjam Indrenius.