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

# evolve secrets

> Store and manage env secrets. Values are write-only; reads return metadata.

```bash theme={"dark"}
evolve secrets <command> [options]
```

`secrets` is the one plural noun; `secret` is a hidden alias. It is the same vault the dashboard's Secrets page writes, reached with your API key.

The same three operations exist on the SDK's `Evolve.managedSecrets()`.

A read-only API key may `list` but not `set` or `delete` (`read_only_key`). LLM provider keys cannot be stored here; they decide who pays and stay on the dashboard.

## secrets set

```bash theme={"dark"}
evolve secrets set <NAME> [options]
```

Store an env secret, or re-shape its delivery or scoping by restating the same value. A different value under an existing name and label is refused (`secret_exists`, 409): delete first, or use another label. Never a silent overwrite. `NAME` matches `[A-Z_][A-Z0-9_]{0,127}`, uppercased for you; the `EVOLVE_` prefix is reserved.

<ParamField path="--value" type="value">
  The secret value, at most 190 bytes of UTF-8. Omit it to pipe the value on stdin, which keeps it out of shell history; one trailing newline is stripped from the pipe. A terminal with neither channel is a usage error, never a hang.
</ParamField>

<ParamField path="--label" type="label" default="default">
  Labeled-row identity, at most 80 characters of `[A-Za-z0-9._-]`. Several values of one name live side by side.
</ParamField>

<ParamField path="--delivery" type="mode" required>
  `brokered`: the value never enters a sandbox, and needs the `--allowed-*` scoping. `direct`: the raw value in the sandbox env; scoping refused.
</ParamField>

<ParamField path="--allowed-host" type="host">
  Brokered scoping: a hostname, or a wildcard like `*.example.com`. Repeatable.
</ParamField>

<ParamField path="--allowed-path-prefix" type="/prefix">
  Brokered scoping: an allowed URL path prefix. Repeatable.
</ParamField>

<ParamField path="--allowed-method" type="METHOD">
  Brokered scoping: an allowed HTTP method. Repeatable.
</ParamField>

```bash theme={"dark"}
printf %s "$GITHUB_TOKEN" | evolve secrets set GITHUB_TOKEN --delivery brokered \
  --allowed-host api.github.com --allowed-path-prefix / --allowed-method GET
```

## secrets list

```bash theme={"dark"}
evolve secrets list [options]
```

List your env secrets. Metadata only; values never leave the server.

<ParamField path="--columns" type="keys | all | help">
  Choose and order columns, comma-separated. `help` lists the keys.
</ParamField>

<ParamField path="-q, --quiet">
  Print only `name[:label]`, one per line.
</ParamField>

<ParamField path="--no-trunc">
  Full cell content instead of one-line truncation.
</ParamField>

<ParamField path="--no-headers">
  Omit the header row in piped (TSV) output.
</ParamField>

## secrets delete

```bash theme={"dark"}
evolve secrets delete <NAME> [options]
```

Delete an env secret by name. Revokes every runtime grant riding the row. Rotate a value by `delete` then `set`, or store the new value under another label.

<ParamField path="--label" type="label">
  The labeled row to delete. Omitted, it resolves as an attachment does: the `default` row, else the only row, else refused with `secret_ambiguous` naming every label.
</ParamField>

```bash theme={"dark"}
evolve secrets delete GITHUB_TOKEN --label staging
```

## Global options

<ParamField path="--json">
  Machine-readable JSON output.
</ParamField>

<ParamField path="--api-key" type="key">
  API key. Defaults to `$EVOLVE_API_KEY`.
</ParamField>

<ParamField path="--base-url" type="url">
  API base URL. Defaults to the Evolve dashboard API.
</ParamField>