Agents and CI

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:

$
export BCTRL_API_KEY="bctrl_..."

Verify the key resolves before running real work:

$
bctrl auth status --json

Prefer JSON

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

$
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:

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

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

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

Error handling

v1 API errors include stable fields:

1
{
2
  "error": "Runtime not found",
3
  "code": "runtime.not_found",
4
  "requestId": "req_123",
5
  "details": {
6
    "runtimeId": "rt_123"
7
  }
8
}

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.