CLI and Agent API

localbot exposes a small agent-safe command line and JSON API for floating-form installation and account-bound verification.

Choose the lead source before using commands

If the site already has a contact form, add localbot's email address as another notification recipient through the dashboard guidance. The localbot init and snippet commands do not create the existing-form connection address.

If the owner wants the full localbot form for the better intake experience, use the floating-form commands and API endpoints below.

The current API names still use widgets names and scopes such as widgets:read because the original install surface was the floating form. Treat the widget ID as the localbot workspace/configuration ID. Widget endpoints belong under the floating-form path unless the endpoint explicitly documents existing-form behavior.

CLI commands

The local CLI is not distributed through npx localbot. That npm package name belongs to an unrelated project. Use these commands only when the site owner has explicitly provided the localbot CLI; otherwise use the embed snippet and Agent API calls below.

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 generate floating-form guidance and do not need a localbot API key. verify and test require LOCALBOT_API_KEY because they access account-bound configuration 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 saves a simulated lead for install verification. It does not send an owner SMS and 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. The floating localbot form 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-23. Maintained by Benjam Indrenius.