stackbone secrets

stackbone secrets targets a running agent installation. With no --agent it uses the local-dev installation linked to the current project, so stackbone dev must be running. See target resolution. Every verb accepts --json and emits the standard envelope.

Manage environment-scoped secrets bound to the targeted installation. There is no reveal verb: the CLI never prints a plaintext value, on any verb, in any output mode. Reading a stored secret back is a human-only action in Studio. That rule holds across the whole CLI; see secrets are never printed. set is idempotent on the name (create and rotate are the same call).

Command	Purpose
`stackbone secrets list`	List secret names (values always masked) and their last-rotated time.
`stackbone secrets set <name>`	Create or rotate a secret. Value from `--value <v>` or stdin; `--description`.
`stackbone secrets remove <name>`	Delete a secret. Requires `--yes`.

remove is destructive and refuses to run without --yes, described under destructive verbs.

A name is SHOUTY_SNAKE_CASE. It starts with an uppercase letter, then carries uppercase letters, digits and underscores, up to 128 characters. A value is at most 4 KiB, and a --description at most 256 characters.

Names the install owns are refused. set and remove reject any name that starts with STACKBONE_, and these as well: DATABASE_URL, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, S3_ENDPOINT, S3_BUCKET, MODEL_PROVIDER_API_KEY, MODEL_PROVIDER_BASE_URL, OPENROUTER_API_KEY, OPENROUTER_BASE_URL, BROWSER_MODE, BROWSERBASE_API_KEY, BROWSERBASE_PROJECT_ID. The runtime injects those itself, and an operator writes the model provider and the browser provider from their own Studio screens. list leaves them out too.

JSON payload

// secrets list: value_preview is a mask, never the plaintext
{
  "schema_version": 1,
  "items": [
    {
      "name": "OPENAI_API_KEY",
      "description": "Billing account key",
      "value_preview": "••••••",
      "created_by_email": "a@b.com",
      "created_at": "2026-05-20T09:00:00Z",
      "last_rotated_at": "2026-06-01T10:00:00Z",
    },
  ],
}

Note

A deployed box locks each secret with the per-agent STACKBONE_SECRET_KEY in its .env, the same key the agent decrypts with. See what you set on the deployed container. A box running an image older than CLI 0.3.3 wrote them under a different key, so the agent read them as missing. You cannot recover those values: set them again once the box runs a 0.3.3 image or newer. stackbone dev was never affected.

Exit codes: 0 ok · 4 not found (unknown secret) · 5 permission (remove without --yes) · 1 generic (empty value, a name that breaks the shape rule, a reserved name). See exit codes.