> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://platform.bctrl.ai/llms.txt.
> For full documentation content, see https://platform.bctrl.ai/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://platform.bctrl.ai/_mcp/server.

# Authentication

> Authenticate the BCTRL CLI with stored credentials or BCTRL_API_KEY.

Every command authenticates with a BCTRL API key, supplied either through an interactive login or the `BCTRL_API_KEY` environment variable.

## Local login

```bash
bctrl auth login
```

This stores your key locally so later commands run without passing it each time.

Check which key is active and which account it resolves to:

```bash
bctrl auth status
bctrl auth status --json
```

Clear the stored credentials when you are done:

```bash
bctrl auth logout
```

## CI and agents

For automation, set the key in the environment rather than logging in:

```bash
export BCTRL_API_KEY="bctrl_..."
bctrl auth status --json
```

`BCTRL_API_KEY` overrides any stored credentials, so a CI or agent run always uses the key you handed it.

## Printing the active token

`bctrl auth token` prints the key in use. It refuses to write to an interactive terminal unless you pass `--reveal`, which keeps the key out of your scrollback by default:

```bash
bctrl auth token --reveal
```

In a script, pipe stdout to the consumer instead:

```bash
bctrl auth token | some-script
```

Reach for this only when a tool needs the raw key. Prefer driving BCTRL through the CLI rather than extracting the token.

## Development API URL

The CLI talks to `https://api.bctrl.ai/v1` by default. Point it at a local or staging stack with `BCTRL_API_URL`:

```bash
BCTRL_API_URL=http://localhost:8787/v1 bctrl auth status
```

Most users never need this.