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

# ankra secrets

> Manage organisation secrets that manifests and addon values reference by sentinel

## ankra secrets

Manage the organisation's secrets (secret slots).

A secret holds one value in Ankra's vault. Manifests, addon values and MCP
server env reference it by its sentinel, \$\{SECRET\_SLOT:\<id>}, instead of
carrying the value, so the value never lives in Git, in a stack definition or
in a chat transcript. Ankra substitutes the value only when it seals the file
with the organisation's SOPS key for delivery: put the sentinel at a key that
the manifest's or addon's encrypted\_paths declares.

Values only go in, never come out: list shows names, ids, who uses each
secret and when it was last read, never a value. A value is read from stdin,
a masked prompt or `--from-file`, or generated by Ankra with `--generate`; it is
never accepted as a command-line argument.

```bash theme={null}
ankra secrets create db-password --generate
ankra secrets create stripe-key --from-file ./stripe.key
printf '%s' "$TOKEN" | ankra secrets create ci-token
ankra secrets list
ankra secrets set stripe-key --from-file ./stripe-new.key
ankra secrets rotate db-password --generate
ankra secrets delete ci-token
```

## ankra secrets create

Create a secret and print its sentinel, \$\{SECRET\_SLOT:\<id>}, on stdout.
Put the sentinel where the value belongs.

The value comes from exactly one of:

```text theme={null}
--generate          Ankra creates a random value nobody sees
--from-file <path>  the file's bytes, exactly as stored
stdin               piped input, without the one line ending the pipe adds;
                    on a terminal, a masked prompt (surrounding spaces are
                    dropped there, since a typed one is a typo)
```

It is never accepted as a command-line argument. `--generate` ignores stdin:
pipe a value without `--generate` to store it.

A generated secret expires (after one day by default, `--ttl` up to a week)
unless a deployed resource references its sentinel, which keeps it for as
long as it is referenced. A secret with a supplied value does not expire
unless `--ttl` is given.

The sentinel alone goes to stdout, so it can be captured:

```bash theme={null}
SENTINEL="$(ankra secrets create db-password --generate)"
```

```bash theme={null}
ankra secrets create <name> [flags]
```

**Examples**

```bash theme={null}
ankra secrets create db-password --generate --length 48
ankra secrets create stripe-key --from-file ./stripe.key --hint "Stripe live key"
printf '%s' "$TOKEN" | ankra secrets create ci-token
ankra secrets create ci-token -o json < token.txt
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--from-file` | | Read the value from this file, byte for byte |
| `--generate` | `false` | Have Ankra create a random value nobody sees |
| `--hint` | | A note about what the secret is for (at most 240 characters) |
| `--length` | `32` | With `--generate`: how many random characters (16-96) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--prefix` | | With `--generate`: text in front of the random characters (at most 16, no whitespace) |
| `--ttl` | `0s` | Expire the secret after this long, e.g. 72h (a generated secret defaults to 24h, at most 168h) |

## ankra secrets delete

Delete a secret and its stored value. This cannot be undone.

A secret that deployed resources still reference is refused, and the
resources are named: remove the sentinel from them (or remove the resources)
first. There is no `--force`: the platform refuses to delete a referenced
secret, because the next delivery of those resources would fail.

```bash theme={null}
ankra secrets delete <name|id> [flags]
```

**Examples**

```bash theme={null}
ankra secrets delete ci-token
ankra secrets delete 0b6f2c1e-3c44-4b9e-9a51-2f1f6f0f9a10 --yes
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra secrets list

List the organisation's secrets, newest first: name, id, whether a person
or Ankra supplied the value, the deployed resources that reference it, when
the value was last read and when the secret expires. Values are never shown.

-o json includes each secret's sentinel and every reference.

```bash theme={null}
ankra secrets list [flags]
```

**Examples**

```bash theme={null}
ankra secrets list
ankra secrets list -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra secrets rotate

Rotate a secret's value in place. The secret keeps its id, so its sentinel
and every reference to it stay valid; the resources that reference it receive
the new value when Ankra next delivers them.

With `--generate` Ankra creates the new random value and nobody sees it.
Without it the new value comes from `--from-file` or stdin, as for 'set';
with it, stdin is ignored. The value is never accepted as a command-line
argument.

```bash theme={null}
ankra secrets rotate <name|id> [flags]
```

**Examples**

```bash theme={null}
ankra secrets rotate db-password --generate
ankra secrets rotate db-password --generate --length 64 --prefix pw_
ankra secrets rotate stripe-key --from-file ./stripe-new.key
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--from-file` | | Read the new value from this file, byte for byte |
| `--generate` | `false` | Have Ankra create the new random value |
| `--length` | `32` | With `--generate`: how many random characters (16-96) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--prefix` | | With `--generate`: text in front of the random characters (at most 16, no whitespace) |

## ankra secrets set

Replace a secret's value in place with one you supply. The secret keeps its
id, so its sentinel and every reference to it stay valid; the resources that
reference it receive the new value when Ankra next delivers them.

The value comes from `--from-file` (the file's bytes, exactly as stored) or
stdin (without the one line ending the pipe adds; on a terminal, a masked
prompt that drops surrounding spaces). It is never accepted as a command-line argument. To have Ankra
generate the new value, use 'ankra secrets rotate `--generate`'.

```bash theme={null}
ankra secrets set <name|id> [flags]
```

**Examples**

```bash theme={null}
ankra secrets set stripe-key --from-file ./stripe-new.key
printf '%s' "$NEW_TOKEN" | ankra secrets set ci-token
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--from-file` | | Read the new value from this file, byte for byte |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.