> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://platform.bctrl.ai/v1/llms.txt

> 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 AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://platform.bctrl.ai/_mcp/server.

# secrets Commands

> Manage secrets

Manage secrets

Output formatting flags (`--json`, `--jq`, and `--template`) are documented once in [Output Formatting](/cli/output) and are omitted from the tables below.

## `bctrl secrets create`

Create a Secret at a new path. The returned ID addresses it; paths remain reference keys.

```bash
bctrl secrets create [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |

## `bctrl secrets delete`

Delete a Secret and all its versions. Supports `If-Match`. The audit trail is kept.

```bash
bctrl secrets delete <secret> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--if-match <version>`    | Require the current resource version               |
| `--yes`                   | Confirm this destructive operation                 |

## `bctrl secrets get`

Read one Secret: its metadata and which fields are set. Secret fields are write-only; use `POST /v1/secrets/{secret}/reveal` to read values.

```bash
bctrl secrets get <secret> [flags]
```

| Flag                   | Description                                        |
| ---------------------- | -------------------------------------------------- |
| `--headers <json>`     | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>` | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>` | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>` | Effective subaccount context (BCTRL-Subaccount-Id) |

## `bctrl secrets list`

List Secrets by path. `prefix` narrows to paths starting with it; `delimiter=/` groups deeper paths into `folders`, like S3. Secret values are never listed.

```bash
bctrl secrets list [flags]
```

| Flag                   | Description                                        |
| ---------------------- | -------------------------------------------------- |
| `--query <json>`       | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`      | Alias for --query                                  |
| `--prefix <value>`     | Query parameter prefix                             |
| `--delimiter <value>`  | Query parameter delimiter                          |
| `--type <value>`       | Query parameter type                               |
| `--cursor <value>`     | Query parameter cursor                             |
| `--order <value>`      | Query parameter order                              |
| `--limit <value>`      | Query parameter limit                              |
| `--headers <json>`     | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>` | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>` | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>` | Effective subaccount context (BCTRL-Subaccount-Id) |

## `bctrl secrets reveal`

Return the values of a Secret version. Only people may reveal: organization or subaccount API keys and dashboard sessions. Task agents, delegated code and View tokens get 403 `secrets.reveal_forbidden`. Every reveal is audited.

```bash
bctrl secrets reveal <secret> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |

## `bctrl secrets update`

Change some fields of a Secret; `null` clears one. Creates a new version. Supports `If-Match`.

```bash
bctrl secrets update <secret> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--if-match <version>`    | Require the current resource version               |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |

## `bctrl secrets versions`

List version metadata by secret ID. Values and ciphertext are never returned.

```bash
bctrl secrets versions <secret> [flags]
```

| Flag                   | Description                                        |
| ---------------------- | -------------------------------------------------- |
| `--query <json>`       | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`      | Alias for --query                                  |
| `--cursor <value>`     | Query parameter cursor                             |
| `--order <value>`      | Query parameter order                              |
| `--limit <value>`      | Query parameter limit                              |
| `--headers <json>`     | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>` | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>` | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>` | Effective subaccount context (BCTRL-Subaccount-Id) |