> ## 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 command reference

> Reference for Contact Button CLI authentication, workspace, generic API, output, debug, and safety options.

## Global commands

```text theme={null}
contactbutton --help
contactbutton --version
contactbutton auth <action>
contactbutton workspaces <action>
contactbutton api <method> <path>
contactbutton discovery
```

## Authentication

```bash theme={null}
contactbutton auth login
contactbutton auth login --token-stdin
contactbutton auth status
contactbutton auth logout
```

The CLI never returns or displays the configured API key.

## Workspace shortcuts

```bash theme={null}
contactbutton workspaces list
contactbutton workspaces get <workspace-id>
```

These shortcuts are equivalent to `api get /workspaces` and `api get /workspaces/{workspace}`.

## Generic API command

Use any documented JSON endpoint:

```bash theme={null}
contactbutton api get /workspaces
contactbutton api get /workspaces/$WORKSPACE_ID/pages
contactbutton api post /workspaces --data @workspace.json --dry-run
contactbutton api post /workspaces --data @workspace.json --confirm
```

Supported methods are `GET`, `HEAD`, `OPTIONS`, `POST`, `PUT`, `PATCH`, and `DELETE`.

### Request data

Inline JSON:

```bash theme={null}
contactbutton api patch /workspaces/$WORKSPACE_ID \
  --data '{"name":"New name"}' \
  --dry-run
```

JSON file:

```bash theme={null}
contactbutton api post /workspaces/$WORKSPACE_ID/pages \
  --data @page.json \
  --confirm
```

Standard input:

```bash theme={null}
jq -n --arg name "Acme" '{name:$name}' |
  contactbutton api post /workspaces --data - --confirm
```

### Query parameters and headers

Repeat flags to send multiple values:

```bash theme={null}
contactbutton api get /workspaces/$WORKSPACE_ID/pages \
  --query cursor=$NEXT_CURSOR \
  --header X-Workflow-ID=setup-2026-07
```

`Authorization` is rejected when supplied through `--header`. Configure authentication through the supported credential sources.

### Mutation controls

Every non-safe method requires one of:

* `--dry-run`: print the redacted method, URL, headers, generated identifiers, and body without making a network request
* `--confirm`: send the mutation after the required approval has been obtained

Mutations receive an automatically generated `Idempotency-Key`. Supply a stable workflow key when retries must replay the same operation:

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

## Output formats

| Format | Behavior | Best for |
| - | - | - |
| `json` | Compact JSON; default when output is piped | Agents, scripts, and `jq` |
| `jsonl` | One JSON value per line | Streaming an array into another tool |
| `pretty` | Indented JSON; default in an interactive terminal | Human inspection |
| `raw` | Unmodified response body | Protocol debugging |

```bash theme={null}
contactbutton workspaces list --format json |
  jq -r '.data[] | [.id, .name] | @tsv'
```

## Debugging

```bash theme={null}
contactbutton api get /workspaces --debug
```

Debug events go to stderr so stdout stays parseable. Authorization values and fields whose names resemble tokens, API keys, passwords, or secrets are redacted. Request bodies may still contain personal or business information, so do not enable debug output in public CI logs.

## Exit codes

| Code | Meaning |
| -: | - |
| `0` | Success |
| `1` | Unexpected CLI error |
| `2` | Invalid usage, unsafe input, or missing mutation confirmation |
| `3` | Missing or rejected authentication |
| `4` | Contact Button API returned a non-authentication error |
| `5` | Network or timeout failure |
| `130` | Interactive authentication cancelled |

Errors are written as structured JSON with stable CLI or API error codes and, when available, the API request ID.


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