---
title: "CLI: Secrets Management — WindKeep"
description: "Manage secrets and run commands with the WindKeep CLI."
canonical_url: "https://windkeep.up.railway.app/cli-guide/secrets"
meta:
  "og:description": "Manage secrets and run commands with the WindKeep CLI."
  "og:image": "https://windkeep.up.railway.app/og-image.png"
  "og:title": "CLI: Secrets Management — WindKeep"
---

> Index of every page on this site: [llms.txt](https://windkeep.up.railway.app/llms.txt)

# CLI: Secrets Management

## Overview

Secrets are environment variables stored in WindKeep. Each secret can hold different values for development, staging, and production — so the same key works across every environment.

## Understanding Secrets

Use secrets for connection strings, API tokens, OAuth credentials, encryption keys, and any other sensitive configuration.

Each secret supports per-environment values:

**Important:** Secret commands require an active project. Run `windkeep projects switch` first, or pass `-p` to `windkeep run` and `windkeep pull`.

- **DEVELOPMENT:** Local development values (default for windkeep run).
- **STAGING:** Test and QA environments.
- **PRODUCTION:** Live application values.

## Command: List Secrets

List all secrets in the active project, including which environments have values and when each secret was last updated.

**Example & Output:**

```
windkeep secrets list
```

```
Project: My Project

KEY            ENVIRONMENTS                     DESCRIPTION          UPDATED
DATABASE_URL   DEVELOPMENT, STAGING, PRODUCTION  Database connection  2d ago
API_KEY        PRODUCTION                        Third-party API key  5m ago

2 secret(s) total
```

## Command: Get Secret

Show decrypted values and metadata for a single secret key.

**Example & Output:**

```
windkeep secrets get DATABASE_URL
```

```
Key:     DATABASE_URL
Desc:    Database connection string
Updated: 2d ago

ENVIRONMENT  VALUE
DEVELOPMENT  postgres://localhost:5432/dev
STAGING      postgres://staging-db:5432/app
PRODUCTION   postgres://prod-db:5432/app
```

**Arguments:**

- `KEY`: Secret key name (required).

## Command: Create Secret

Create a new secret in the active project. Set values per environment with `--dev`, `--staging`, and `--prod`.

```
# Set values for all environments at once
windkeep secrets create DATABASE_URL \
  --description "Database connection string" \
  --dev "postgres://localhost:5432/dev" \
  --staging "postgres://staging-db:5432/app" \
  --prod "postgres://prod-db:5432/app"

# Or create a secret with only the environments you need
windkeep secrets create API_KEY --description "Production API key" --prod "sk_live_abc123"
```

**Arguments:**

- `KEY`: Secret key (required; uppercase recommended).

**Flags:**

- `-d, --description`: Optional description.
- `--dev, --staging, --prod`: Environment values.

## Command: Set Secret

Update values for an existing secret. Only the environments you specify are changed — all others keep their current values.

```
windkeep secrets set DATABASE_URL --prod "postgres://new-prod-db:5432/app"

windkeep secrets set API_KEY --staging "sk_test_xyz789" --prod "sk_live_xyz789"

windkeep secrets set JWT_SECRET -d "Updated signing secret" --dev "new_dev_secret"
```

**Arguments:**

- `KEY`: Secret key (required).

**Flags:**

- `-d, --description`: Update the description.
- `--dev, --staging, --prod`: Environment values to update.

## Command: Secret History

View the audit trail for a secret — who changed each value and when.

**Example & Output:**

```
windkeep secrets history DATABASE_URL -e prod
```

```
History for: DATABASE_URL

[PRODUCTION]  current: postgres://prod-db:5432/app
VALUE                          CHANGED BY  WHEN
postgres://old-prod-db:5432/app  Alice Smith  3d ago
```

**Arguments:**

- `KEY`: Secret key (required).

**Flags:**

- `-e, --env`: Filter by environment (dev, staging, or prod).

## Command: Delete Secret

Permanently delete a secret and all of its environment values. **This cannot be undone.**

```
windkeep secrets delete OLD_API_KEY --confirm
```

**Arguments:**

- `KEY`: Secret key to delete (required).

**Flags:**

- `--confirm`: Skip the confirmation prompt.

## Injecting Secrets at Runtime

`windkeep run` fetches secrets from WindKeep and injects them as environment variables into your process — no `.env` file required.

WindKeep flags must come **before** the command you want to run. Use `--` to separate flags when your command also uses `--` flags.

```
# Run with development secrets (default)
windkeep run npm run dev

# Run with production secrets
windkeep run --env prod python app.py

# Override project and environment
windkeep run -p api-service -e staging node server.js

# Pass through flags to the child command
windkeep run -e prod -- node --inspect server.js
```

**Flags:**

- `-e, --env`: Environment (dev, staging, or prod — defaults to development).
- `-p, --project`: Override the active project by slug.
- `-v, --verbose`: Print injected secret keys before running (values are never shown).

## Syncing with Local .env Files

Prefer working with `.env` files locally? Use `pull` and `push` to sync secrets between WindKeep and your filesystem.

## Command: Pull Secrets

Export secrets from a project to a local `.env` file. Defaults to `.env.{slug}.{env}` if no output path is given.

```
# Pull development secrets to the default file
windkeep pull

# Pull production secrets to a specific file
windkeep pull prod.env -e production

# Pull from a different project
windkeep pull .env.staging -e staging -p my-api
```

**Arguments:**

- `OUTPUT_FILE`: Output file path (optional).

**Flags:**

- `-e, --env`: Environment to pull (defaults to development).
- `-p, --project`: Override the active project by slug.

## Command: Push Secrets

Import secrets from a local `.env` file into the active project. Existing keys are skipped unless you pass `--overwrite`.

```
# Push from the default .env file
windkeep push

# Push production secrets and overwrite existing keys
windkeep push prod.env -e production --overwrite
```

**Arguments:**

- `INPUT_FILE`: Input file path (defaults to .env).

**Flags:**

- `-e, --env`: Environment to push to (defaults to development).
- `--overwrite`: Update secrets that already exist.

```json
{"@context":"https://schema.org","@graph":[{"@id":"https://windkeep.up.railway.app/#website","@type":"WebSite","name":"WindKeep","url":"https://windkeep.up.railway.app/"},{"@id":"https://windkeep.up.railway.app/cli-guide/secrets#webpage","@type":"WebPage","description":"Manage secrets and run commands with the WindKeep CLI.","name":"CLI: Secrets Management","url":"https://windkeep.up.railway.app/cli-guide/secrets","isPartOf":{"@id":"https://windkeep.up.railway.app/#website"},"potentialAction":[{"@type":"ReadAction","target":["https://windkeep.up.railway.app/cli-guide/secrets"]}]}]}
```

## Sitemap

See the full [sitemap](https://windkeep.up.railway.app/sitemap.md) for all pages.
