> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcapods.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# orca secrets

> List, set, and delete tenant secrets; values are write-only and never printed.

> **Last updated: 2026-09-06**

`orca secrets` manages the tenant's encrypted [secret vault](/concepts/secrets). Values are write-only: the API never returns plaintext, and the CLI never prints it. Listings show metadata only. Reference a stored value elsewhere as `secret://name`, for example in an MCP server header.

Every subcommand accepts the [global flags](/cli/reference/overview#global-flags). `delete` prompts for confirmation in a terminal; in a script `--yes` is required or the command refuses (exit code 2).

## orca secrets list

```bash theme={"dark"}
orca secrets list [--limit <n>] [--offset <n>] [--all]
```

Lists secret metadata: name, key hint, algorithm, last update, and description. Never values.

| Flag           | Type    | Default | Description                                                        |
| -------------- | ------- | ------- | ------------------------------------------------------------------ |
| `--limit <n>`  | integer | `10`    | Page size                                                          |
| `--offset <n>` | integer | `0`     | Page offset                                                        |
| `--all`        | boolean | `false` | Fetch every page (cannot be combined with `--limit` or `--offset`) |

```bash theme={"dark"}
orca secrets list --all --json | jq -r '.[].name'
```

Plain (piped) output is one tab-separated row per secret: `name`, `key` (or `-`), `algorithm`, `updatedAt`, `description` (or `-`). The `--json` output is an array of metadata records: `name`, `key`, `description`, `algorithm`, `createdAt`, `updatedAt`.

## orca secrets set

```bash theme={"dark"}
orca secrets set <name> [--value <value>] [--key <key>] [--description <text>]
```

Creates or replaces a secret. The value is taken from the first of: `--value`, stdin when it is piped (a single trailing newline is stripped, so `printf` and `echo` both round-trip), or a hidden prompt in a terminal. An empty value is refused with exit code 2.

`<name>` is the secret's identifier, the part after `secret://` in references. `--key` is different: it is the canonical environment variable the value is meant to populate, such as `ANTHROPIC_API_KEY`, and it is only metadata. A secret without `--key` is stored as untyped.

| Flag                   | Type   | Default | Description                                                                   |
| ---------------------- | ------ | ------- | ----------------------------------------------------------------------------- |
| `--value <value>`      | string | none    | The secret value; omit to read from piped stdin or a hidden prompt            |
| `--key <key>`          | string | none    | Canonical variable name the value populates (for example `ANTHROPIC_API_KEY`) |
| `--description <text>` | string | none    | Human-readable description                                                    |

The write replaces the whole record on the server, so the CLI reads the secret's current metadata first and carries `key` and `description` forward when the flags are omitted; rotating a value never clears them. Pass an empty string (`--key ""`) to clear one deliberately. On `cli-v0.5.0` the read does not happen and an omitted flag clears the field, so repeat both flags when rotating on that version.

```bash theme={"dark"}
orca secrets set anthropic --key ANTHROPIC_API_KEY --description "Prod Anthropic key"
printf '%s' "$TOKEN" | orca secrets set docs-token --json
```

With `--json` the metadata record is printed; the plaintext is never echoed.

## orca secrets delete

```bash theme={"dark"}
orca secrets delete <name> [--yes]
```

Deletes a secret. Any `secret://name` reference to it fails at resolution time from then on.

| Flag    | Type    | Default | Description                  |
| ------- | ------- | ------- | ---------------------------- |
| `--yes` | boolean | `false` | Skip the confirmation prompt |

```bash theme={"dark"}
orca secrets delete docs-token --yes --json
```

```json theme={"dark"}
{ "name": "docs-token", "deleted": true }
```

<Note>
  Verified against orca-cli `cli-v0.5.0`.
</Note>