---
title: "Secrets"
description: "Keep sensitive values out of your repository and inject workspace secrets into preview processes with secretEnv."
---

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

# Secrets

Workspace secrets let preview processes and lifecycle hooks use API keys,
tokens, and other sensitive values without storing them in your repository.
Your `.trevize/settings.json` contains only a secret key; Trevize resolves the
encrypted value at runtime.

## Add a workspace secret

Open **Workspace settings → Secrets**, select **Add secret**, and enter:

- **Key** — the stable name referenced by repository configuration. It must
  start with a letter and contain only uppercase letters, digits, and
  underscores.
- **Value** — the sensitive value injected at runtime.
- **Description** — optional context for other workspace members.

After a secret is saved, Trevize returns only its key and metadata to the UI;
the value remains masked.

## Reference a secret in a repository

Add `secretEnv` to a [preview target](/configuration/preview). Each entry maps
the environment variable your application reads to a workspace secret key:

```json
{
  "preview": {
"targets": {
  "dev": {
    "command": "bun run dev",
    "port": 3000,
    "secretEnv": {
      "OPENAI_API_KEY": "OPENAI_PRODUCTION_KEY"
    }
  }
}
  }
}
```

Read the mapping as
`"<environment variable>": "<workspace secret key>"`. In this example, the
application reads `process.env.OPENAI_API_KEY`, while Trevize looks up the
workspace secret named `OPENAI_PRODUCTION_KEY`.

[Hook](/configuration/hooks) entries accept the same `secretEnv` block, so a
setup command can, for example, seed data through an authenticated API:

```json
{
  "hooks": {
"SandboxReady": [
  {
    "command": "bun run db:seed",
    "secretEnv": { "SEED_API_KEY": "SEED_API_KEY" }
  }
]
  }
}
```

The secret value itself never belongs in `.trevize/settings.json`.

## Manage secrets from the CLI

The CLI accepts values only through a hidden TTY prompt or stdin, so values do
not appear in shell history or command arguments. Secret listings and mutation
responses contain keys and metadata only:

```sh
trevize secrets list --output json
printf '%s\n' "$SERVICE_TOKEN" | trevize secrets set SERVICE_TOKEN --stdin
trevize secrets delete SERVICE_TOKEN --yes --output json
```

Use `--dry-run` to validate a key before a write. Deletion requires an
interactive confirmation, or the explicit `--yes` flag in automation. Do not
put secret values in repository configuration; map uploaded workspace secrets
by name with `secretEnv` as shown above.

## Share secrets or limit them to one process

Target-level `secretEnv` entries are available to every process in that target.
Put `secretEnv` on an individual process when only that process needs the
secret:

```json
{
  "preview": {
"targets": {
  "dev": {
    "defaultProcess": "web",
    "secretEnv": {
      "SHARED_SERVICE_TOKEN": "SHARED_SERVICE_TOKEN"
    },
    "processes": [
      {
        "name": "web",
        "command": "bun run dev:web",
        "port": 3000
      },
      {
        "name": "api",
        "command": "bun run dev:api",
        "port": 8787,
        "secretEnv": {
          "STRIPE_SECRET_KEY": "STRIPE_PRODUCTION_KEY"
        }
      }
    ]
  }
}
  }
}
```

Here, both processes receive `SHARED_SERVICE_TOKEN`, but only `api` receives
`STRIPE_SECRET_KEY`.

If the same environment variable appears in more than one place, resolution
uses this order, with later values taking precedence:

1. Target-level `env`
2. Process-level `env`
3. Target-level `secretEnv`
4. Process-level `secretEnv`

This lets a process-specific secret override a shared value deliberately.

## Secrets and interpolation

Use `secretEnv` for secret values. A workspace secret is not available as a
`${NAME}` placeholder inside `env`:

```json
{
  "env": {
"DATABASE_URL": "postgres://user:${DATABASE_PASSWORD}@db.example.com/app"
  }
}
```

The configuration above does not resolve `DATABASE_PASSWORD` from workspace
secrets. Store the complete sensitive value, such as the complete database URL,
as a workspace secret and map it directly instead:

```json
{
  "secretEnv": {
"DATABASE_URL": "DATABASE_URL"
  }
}
```

## Troubleshooting

If a referenced key does not exist in the workspace, Trevize stops the preview
before starting its processes and reports the missing key. Add the secret in
workspace settings or correct the right-hand side of the `secretEnv` mapping.

When a process cannot read a configured value, check that:

- The repository's `workspaceId` belongs to the workspace containing the
  secret.
- The right-hand value matches the workspace secret key exactly.
- `secretEnv` is attached to the intended target or process.
- The application reads the left-hand environment variable name.

> **Keep the scope narrow**
>
> Put a secret at process level unless every process in the target needs it.
> Repository configuration can safely contain secret keys, but never commit
> secret values.

Source: https://docs.trevize.dev/configuration/secrets/index.mdx