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

# ci.secret

> Read platform-mounted secrets; never logged or traced.

Read a secret mounted by the Cirron platform runtime. Secrets are
scoped to workspace, pipeline, or deployment on the platform and
injected into the container at run time. The SDK abstracts the
injection mechanism (env var in cloud/on-prem, file mount in
air-gapped).

## Signature

```python theme={null}
def secret(name: str) -> str
```

## Parameters

| Name   | Type  | Purpose                                          |
| ------ | ----- | ------------------------------------------------ |
| `name` | `str` | Secret name as configured on the Cirron platform |

Hyphens in `name` map to underscores when resolving the env var
form; `ci.secret("openai-api-key")` reads `CIRRON_SECRET_OPENAI_API_KEY`.

## Resolution order

First match wins:

1. **`CIRRON_SECRET_<NAME>`**: environment variable. Standard
   cloud and on-prem mechanism. `<NAME>` is `name.upper()` with
   hyphens replaced by underscores.
2. **`/etc/cirron/secrets/<name>`**: file mount. Used in air-gapped
   environments where env-var injection isn't the deployment
   mechanism. Trailing newlines are stripped.
3. **`CirronSecretNotFound`**: raised if neither is present. The
   message points at the platform's secrets UI.

## Examples

```python theme={null}
import openai, cirron as ci

openai.api_key = ci.secret("openai-api-key")
```

```python theme={null}
from anthropic import Anthropic
import cirron as ci

client = Anthropic(api_key=ci.secret("anthropic-api-key"))
```

## Guarantees

* Secret values are **never logged**, even at `DEBUG`.
* Secret values are **never included** in trace spans, marks, or
  snapshots.
* Secret values are **never flushed to disk** through the spool.

Treat the return value like any sensitive string: don't include it
in attribute values passed to `ci.scope()` or `ci.mark()`.

## When the secret isn't mounted

`CirronSecretNotFound` is raised with a message pointing at the
platform's secrets UI. Typical causes:

* The secret hasn't been configured on the dashboard for this
  workspace / pipeline / deployment.
* The deployment hasn't been restarted since the secret was added
  (env-var injection requires a fresh container).
* You're running standalone (not inside a Cirron pipeline or
  deployment) and the secret isn't set as a local env var or file.

For local development, you can simulate the injection yourself:

```bash theme={null}
export CIRRON_SECRET_OPENAI_API_KEY=sk-...
```

## Related

<CardGroup cols={2}>
  <Card title="ci.env" icon="gear" href="/sdk/reference/env">
    For non-sensitive config. Never read credentials through `ci.env`.
  </Card>

  <Card title="CirronSecretNotFound" icon="triangle-exclamation" href="/sdk/errors#cirronsecretnotfound">
    How to handle a missing secret.
  </Card>
</CardGroup>