secret - cred

## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# secret

Manage secrets in your local vault.

## set

Add or update a secret:

    cred secret set DATABASE_URL "postgres://user:pass@localhost:5432/db"

### Target Scopes (v0.14.0+)

Scope a secret to specific deployment targets. This helps prevent accidentally pushing backend-only secrets to frontend targets.

Unscoped secrets (default) are eligible for all targets.

    # Only push this to Vercel
    cred secret set NEXT_PUBLIC_API_URL "https://..." --targets vercel

    # Push this to GitHub and Fly only
    cred secret set DATABASE_URL "postgres://..." --targets github,fly

Clear scopes (make unscoped again):

    cred secret set DATABASE_URL "postgres://..." --clear-targets

With a description:

    cred secret set API_KEY "sk-xxx" --description "OpenAI production key"
    cred secret set CERT_PEM "-----BEGIN..." -d "TLS certificate"

In a specific environment:

    cred secret set DATABASE_URL "postgres://prod..." --env prod

### Format Detection

cred auto-detects the format of your secrets:

Format | Detection | Example
--- | --- | ---
`pem` | Starts with `-----BEGIN` | Certificates, keys
`json` | Valid JSON object/array | `{"key": "value"}`
`base64` | Single-line base64 | `SGVsbG8gV29ybGQ=`
`multiline` | Contains newlines | Multi-line text
`raw` | Default | Single-line text

Override auto-detection:

    cred secret set MY_KEY "value" --format json

## get

Retrieve a secret value:

    cred secret get JWT_SECRET

From a specific environment:

    cred secret get JWT_SECRET --env prod

With full metadata:

    cred secret get JWT_SECRET --json

    {
        "data": {
            "key": "JWT_SECRET",
            "value": "super-secret",
            "format": "raw",
            "created_at": "2025-12-11T12:00:00Z",
            "updated_at": "2025-12-11T12:00:00Z",
            "description": null
        }
    }

## list

List all secrets in the vault:

    cred secret list

Output:

    Vault content:
      API_KEY = ***** (OpenAI production key)
      JWT_SECRET = *****

List secrets in a specific environment:

    cred secret list --env prod

Descriptions are shown inline when present.

## remove

Delete a secret from the local vault:

    cred secret remove JWT_SECRET --yes

From a specific environment:

    cred secret remove JWT_SECRET --env prod --yes

Output:

    ✓ Removed 'JWT_SECRET' from local vault (3 days old)

> Note: This only removes from the local vault. To delete from a target, use `cred prune`.

## describe

Update a secret’s description:

    cred secret describe API_KEY "Updated: rotating quarterly"

Clear a description:

    cred secret describe API_KEY

## history

View the version history of a secret:

    cred secret history DATABASE_URL

Output:

    History for 'DATABASE_URL' in env 'default':

      [current] 2025-01-03 14:30:00 (manual)
      [0] 2025-01-02 10:15:00 (manual)
      [1] 2025-01-01 09:00:00 (manual)

    Use 'cred secret rollback DATABASE_URL --version <N>' to restore

From a specific environment:

    cred secret history DATABASE_URL --env prod

cred keeps up to 10 previous versions of each secret.

## rollback

Restore a secret to a previous version:

    cred secret rollback DATABASE_URL --version 0 --yes

The `--version` flag specifies which historical version to restore (0 = most recent previous value).

From a specific environment:

    cred secret rollback DATABASE_URL --version 0 --env prod --yes

Preview before rolling back:

    cred secret rollback DATABASE_URL --version 0 --dry-run

> Note: Rollback is a destructive operation and requires `--yes` to confirm.

## import

Import `KEY=VALUE` pairs from a .env file:

    cred import .env

Import to a specific environment:

    cred import prod.env --env prod

Existing keys are skipped by default to keep imports non-destructive.

Overwrite existing keys:

    cred import .env --overwrite

Preview without writing:

    cred import .env --dry-run

## export

Write vault contents to a .env file:

    cred export .env.backup

Export from a specific environment:

    cred export prod.env --env prod

Keys are sorted alphabetically. Existing files are preserved unless forced:

    cred export .env --force

Preview:

    cred export .env --dry-run