> ## 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 authentication

> Authenticate the Contact Button CLI with a scoped API key while keeping credentials out of prompts, shell history, and logs.

Create a scoped API key at [app.contactbutton.com/account/api-keys](https://app.contactbutton.com/account/api-keys). Select the smallest set of permissions the workflow needs.

## Recommended for agents and CI

Store the key in the coding-agent host or CI provider's secret manager as `CONTACTBUTTON_TOKEN`:

```bash theme={null}
export CONTACTBUTTON_TOKEN="<loaded by your secret manager>"
contactbutton auth status
contactbutton workspaces list --format json
```

`CONTACTBUTTON_API_KEY` is accepted as a compatibility alias. If both are set, `CONTACTBUTTON_TOKEN` wins.

Never paste the key into a prompt, commit it to a repository, or pass it as a CLI argument. The CLI deliberately has no `--token` or `--api-key` flag.

## Local interactive login

For a developer workstation:

```bash theme={null}
contactbutton auth login
```

The prompt does not echo the key. The CLI stores it at:

* macOS and Linux: `${XDG_CONFIG_HOME:-~/.config}/contactbutton/config.json`
* Windows: the equivalent path beneath the user's configured home directory

The directory is owner-only and the file uses mode `0600` where the operating system supports POSIX permissions.

For an automated local setup that already receives the key through a secure stdin channel:

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

Do not type the secret directly after `echo`, because it can enter shell history. Prefer a secret-manager command that writes the value to stdin.

## Credential precedence

The CLI resolves credentials in this order:

1. `CONTACTBUTTON_TOKEN`
2. `CONTACTBUTTON_API_KEY`
3. The local CLI configuration file

`contactbutton auth status` reports the active source but never prints the secret.

## Log out and rotate

```bash theme={null}
contactbutton auth logout
```

This removes only the locally stored key. It cannot remove an environment variable from the parent shell. Revoke or rotate the actual key from the API-key portal; deleting local configuration does not revoke a server-side credential.

## Appdev and local APIs

Override the API root when testing:

```bash theme={null}
contactbutton workspaces list \
  --base-url https://appdev.contactbutton.com/v1
```

The CLI requires HTTPS except for `localhost`, `127.0.0.1`, or `::1`. Request paths must remain relative to the configured base URL, preventing a supplied path from redirecting the bearer key to another host.


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