> 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.

# Agents and CI

> Use the BCTRL CLI safely from coding agents, CI jobs, and other automation.

The CLI gives agents and CI jobs shell-native access to BCTRL without an API client. The patterns below keep runs reproducible and machine-readable.

## Authentication

Set `BCTRL_API_KEY` instead of running `bctrl auth login`. It takes precedence over stored credentials, so the run uses exactly the key you passed:

```bash
export BCTRL_API_KEY="bctrl_..."
```

Verify the key resolves before running real work:

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

## Prefer JSON

Pass `--json` so output is structured and stable across CLI versions:

```bash
bctrl runtime list --json
bctrl run events list run_123 --json
bctrl file list --space sp_123 --json
```

Pull a single field out with `--jq`:

```bash
bctrl runtime list --json --jq '.data[].id'
```

Reach for `--template` when you need fixed custom text rather than JSON:

```bash
bctrl runtime list \
  --json \
  --template '{{#each data}}{{id}} {{status}}{{newline}}{{/each}}'
```

## Error handling

v1 API errors include stable fields:

```json
{
  "error": "Runtime not found",
  "code": "runtime.not_found",
  "requestId": "req_123",
  "details": {
    "runtimeId": "rt_123"
  }
}
```

The CLI surfaces the error code, request ID, and a suggested next command when one is available. When an agent reports a failure, pass through the command that failed, the error code, and the request ID so the run can be traced.

## Destructive commands

Delete and archive commands require a confirmation flag such as `--yes`, so they never fire by accident in a non-interactive shell. An agent should not delete, revoke, archive, or stop a resource unless the user asked for it.