Skip to navigation
Command reference

secrets Commands

View as Markdown

Manage secrets

Output formatting flags (--json, --jq, and --template) are documented once in Output Formatting 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.

bctrl secrets create [flags]
FlagDescription
--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.

bctrl secrets delete <secret> [flags]
FlagDescription
--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
--yesConfirm 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.

bctrl secrets get <secret> [flags]
FlagDescription
--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.

bctrl secrets list [flags]
FlagDescription
--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.

bctrl secrets reveal <secret> [flags]
FlagDescription
--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.

bctrl secrets update <secret> [flags]
FlagDescription
--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.

bctrl secrets versions <secret> [flags]
FlagDescription
--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)