CLI automation and coding agents

The CLI is optimized for coding agents and short automation workflows. It is not a substitute for a production SDK: long-running applications should call REST directly.

Agent operating contract

Give the agent these boundaries:

Use the official Contact Button CLI and API documentation.
Read existing resources before writing.
Keep CONTACTBUTTON_TOKEN in the host secret manager and out of chat.
Use --format json for every parsed response.
Show me every mutation with --dry-run first.
Use stable idempotency keys.
Run the approved request with --confirm only after I approve it.
Ask again before publishing, changing DNS, buying anything, placing a call,
sending a message, making a booking, or requesting a callback.

The flag --confirm records intent at the CLI boundary; the agent must not add it automatically merely because a request failed with confirmation_required.

Inventory before setup

set -euo pipefail

contactbutton workspaces list --format json > workspaces.json
WORKSPACE_ID="$(jq -r '.data[] | select(.name == "Acme") | .id' workspaces.json)"

test -n "$WORKSPACE_ID"
test "$WORKSPACE_ID" != "null"

contactbutton api get "/workspaces/$WORKSPACE_ID/pages" --format json
contactbutton api get "/workspaces/$WORKSPACE_ID/buttons" --format json
contactbutton api get "/workspaces/$WORKSPACE_ID/forms" --format json
contactbutton api get "/workspaces/$WORKSPACE_ID/apps" --format json

Stop and ask the human to choose when more than one workspace matches.

Draft, inspect, then execute

Create page.json:

{
  "name": "Acme Support",
  "slug": "acme-support",
  "bio": "Book a demo, request a callback, or read support articles.",
  "agent_instructions": "Use published knowledge first. Ask before requesting a material action."
}

Inspect the exact request:

contactbutton api post "/workspaces/$WORKSPACE_ID/pages" \
  --data @page.json \
  --idempotency-key page-acme-support-v1 \
  --dry-run

After approval:

contactbutton api post "/workspaces/$WORKSPACE_ID/pages" \
  --data @page.json \
  --idempotency-key page-acme-support-v1 \
  --confirm \
  --format json

Keep the returned resource ID. Do not select resources by array position in later steps.

CI example

jobs:
  verify-contact-button:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install --global @contactbutton/cli
      - env:
          CONTACTBUTTON_TOKEN: ${{ secrets.CONTACTBUTTON_TOKEN }}
        run: |
          contactbutton workspaces list --format json |
            jq -e '.data | length > 0'

Use this example only after the official npm package is published and verified as described in Install the CLI. Pin a reviewed CLI version for production CI rather than installing an unbounded latest version.

Documented endpoints that do not require a token can be called with --no-auth:

contactbutton api post /signups \
  --no-auth \
  --data @signup.json \
  --idempotency-key signup-acme-agent-v1 \
  --confirm

Human email verification remains required. The CLI does not automate access to the represented human’s email or bypass the one-time code.

Troubleshooting automation

Use --debug only in a private log; secret-looking fields are redacted, but business data may remain.
Treat exit 3 as a credential or scope problem, not a reason to request a broader key automatically.
Treat exit 4 as a structured API response. Read resolution and request_id before retrying.
Retry network exit 5 with bounded exponential backoff.
Reuse the same idempotency key only for the same method, path, and body.
Do not retry validation or confirmation failures without changing the input or obtaining the missing approval.

Get started

Contact Button CLI

Build

Operate

CLI automation and coding agents

Agent operating contract

Inventory before setup

Draft, inspect, then execute

CI example

Troubleshooting automation

​Agent operating contract

​Inventory before setup

​Draft, inspect, then execute

​CI example

​Public and signup endpoints

​Troubleshooting automation

Agent operating contract

Inventory before setup

Draft, inspect, then execute

CI example

Public and signup endpoints

Troubleshooting automation