> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contactbutton.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI automation and coding agents

> Safely automate Contact Button setup with JSON output, dry runs, idempotency, scoped credentials, and explicit human confirmation.

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:

```text theme={null}
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

```bash theme={null}
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`:

```json theme={null}
{
  "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:

```bash theme={null}
contactbutton api post "/workspaces/$WORKSPACE_ID/pages" \
  --data @page.json \
  --idempotency-key page-acme-support-v1 \
  --dry-run
```

After approval:

```bash theme={null}
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

```yaml theme={null}
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'
```

> [!NOTE]
>
> Use this example only after the official npm package is published and verified as described in [Install the CLI](https://docs.contactbutton.com/cli/install.md). Pin a reviewed CLI version for production CI rather than installing an unbounded latest version.

## Public and signup endpoints

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

```bash theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.