CLI command reference

Global commands

contactbutton --help
contactbutton --version
contactbutton auth <action>
contactbutton workspaces <action>
contactbutton api <method> <path>
contactbutton discovery

Authentication

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

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:

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:

contactbutton api patch /workspaces/$WORKSPACE_ID \
  --data '{"name":"New name"}' \
  --dry-run

JSON file:

contactbutton api post /workspaces/$WORKSPACE_ID/pages \
  --data @page.json \
  --confirm

Standard input:

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

Query parameters and headers

Repeat flags to send multiple values:

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:

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

contactbutton workspaces list --format json |
  jq -r '.data[] | [.id, .name] | @tsv'

Debugging

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.

Get started

Contact Button CLI

Build

Operate

Global commands

Authentication

Workspace shortcuts

Generic API command

Request data

Query parameters and headers

Mutation controls

Output formats

Debugging

Exit codes

​Global commands

​Authentication

​Workspace shortcuts

​Generic API command

​Request data

​Query parameters and headers

​Mutation controls

​Output formats

​Debugging

​Exit codes

Global commands

Authentication

Workspace shortcuts

Generic API command

Request data

Query parameters and headers

Mutation controls

Output formats

Debugging

Exit codes