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

# cubby secrets

> Manage environment variables for your app

# cubby secrets

Manage secrets (environment variables) for your app. Secrets can be set for local development or production environments.

## Subcommands

| Command                          | Description                                        |
| -------------------------------- | -------------------------------------------------- |
| `cubby secrets set <name>`       | Set a secret                                       |
| `cubby secrets list`             | List secrets                                       |
| `cubby secrets delete <name>`    | Delete a secret                                    |
| `cubby secrets apply --env prod` | Apply production secret changes without rebuilding |

***

## cubby secrets set

Set a secret for an app. The value is entered securely (hidden input).

### Usage

```bash theme={null}
cubby secrets set <name> [flags]
```

### Arguments

| Argument | Description                                    |
| -------- | ---------------------------------------------- |
| `name`   | Secret name (e.g., `API_KEY`, `STRIPE_SECRET`) |

### Flags

| Flag    | Short | Description                     | Default |
| ------- | ----- | ------------------------------- | ------- |
| `--env` | `-e`  | Environment (`local` or `prod`) | `local` |

### Examples

```bash theme={null}
# Set local secret
cubby secrets set OPENAI_API_KEY

# Set production secret
cubby secrets set STRIPE_SECRET_KEY --env prod
```

### Naming Convention

Secret names must be:

* Uppercase letters, numbers, and underscores
* Start with a letter

Examples: `API_KEY`, `DATABASE_URL`, `STRIPE_SECRET_KEY`

### Production Secrets Workflow

Production secrets require the app to exist on the platform:

```bash theme={null}
# 1. Deploy first (creates the app)
cubby deploy

# 2. Set secrets
cubby secrets set OPENAI_API_KEY --env prod

# 3. Apply without rebuilding
cubby secrets apply --env prod
```

<Warning>
  Setting a production secret does **not** update already-running containers by itself. Run `cubby secrets apply --env prod` to restart the app and apply changes without rebuilding.
</Warning>

***

## cubby secrets list

List all secrets for an app.

### Usage

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

### Flags

| Flag       | Short | Description                            | Default |
| ---------- | ----- | -------------------------------------- | ------- |
| `--reveal` | `-r`  | Show secret values (hidden by default) | `false` |
| `--env`    | `-e`  | Environment (`local` or `prod`)        | `local` |

### Examples

```bash theme={null}
# List local secrets
cubby secrets list

# Show values
cubby secrets list --reveal

# List production secrets
cubby secrets list --env prod
```

### Output

```
Secrets for myapp (local):

  OPENAI_API_KEY=********************
  STRIPE_SECRET_KEY=********************

  Use --reveal to show values
```

***

## cubby secrets delete

Delete a secret from an app.

### Usage

```bash theme={null}
cubby secrets delete <name> [flags]
```

### Arguments

| Argument | Description           |
| -------- | --------------------- |
| `name`   | Secret name to delete |

### Flags

| Flag      | Short | Description                     | Default |
| --------- | ----- | ------------------------------- | ------- |
| `--env`   | `-e`  | Environment (`local` or `prod`) | `local` |
| `--force` | `-f`  | Skip confirmation prompt        | `false` |

### Examples

```bash theme={null}
# Delete local secret
cubby secrets delete API_KEY

# Delete production secret
cubby secrets delete API_KEY --env prod

# Delete without confirmation
cubby secrets delete API_KEY --force
```

***

## cubby secrets apply

Apply saved production secret changes to the running app without rebuilding the image.

### Usage

```bash theme={null}
cubby secrets apply --env prod
```

### Flags

| Flag    | Short | Description          | Default |
| ------- | ----- | -------------------- | ------- |
| `--env` | `-e`  | Environment (`prod`) | `prod`  |

### Examples

```bash theme={null}
cubby secrets set OPENAI_API_KEY --env prod
cubby secrets apply --env prod
```

***

## Reserved Names

Some environment variables are reserved and managed by Cubby:

| Name           | Description                                    |
| -------------- | ---------------------------------------------- |
| `DATABASE_URL` | Automatically provisioned for apps with Prisma |
| `PORT`         | Set by the container runtime (default: 3000)   |

Do not set these manually.

## How Secrets Work

### Local Development

Local secrets are stored on your machine and injected into the `cubby dev` container:

```bash theme={null}
cubby secrets set API_KEY
cubby dev  # API_KEY available in container
```

### Production

Production secrets are:

* Encrypted at rest
* Injected at container startup
* Never logged or exposed

The workflow:

1. Deploy creates the app
2. Set secrets via `cubby secrets set --env prod`
3. Apply secrets via `cubby secrets apply --env prod` to restart the app without rebuilding

## Accessing Secrets in Code

Secrets are available as environment variables:

```typescript theme={null}
// API route
export async function GET() {
  const apiKey = process.env.OPENAI_API_KEY
  // Use the secret
}
```

## Best Practices

1. **Never commit secrets** - Use `cubby secrets`, not `.env` files in production
2. **Use descriptive names** - `STRIPE_SECRET_KEY` not `SK`
3. **Apply after changes** - Run `cubby secrets apply --env prod` after changing production secrets
4. **Keep local and prod separate** - Different values for each environment

## Related Commands

* [`cubby dev`](/cli-reference/dev) - Uses local secrets
* [`cubby deploy`](/cli-reference/deploy) - Uses production secrets