Logo

CLI Guide

Organization Secrets

Organization Secrets let you securely store and retrieve sensitive values — API keys, database credentials, tokens — at the organization level. Secrets are encrypted with AES-256-GCM at the edge and accessible from the CLI, SDKs, and Web Dashboard.

Before You Begin

Make sure you have:

Installed the EnvVault CLI (see the installation guide)

Created an API key from the API Keys page in the web app

Logged in via envv login --token <API_KEY>

Core Concepts

Organization Scoping

Every secret belongs to exactly one organization. API keys are bound to the organization they were created in, so the CLI always reads and writes secrets in the correct org with no ambiguity.

Environment Scoping

Secrets are isolated per environment within an organization. The same key can hold different values in development, staging, and production. Pass --env to target a specific one; without it, the CLI defaults to development.

Edge Encryption

Values are encrypted with AES-256-GCM on Cloudflare's edge before storage. Plaintext never touches the database. Decryption happens in memory only when a secret is requested.

Versioning

Setting an existing key updates its value and increments the version automatically. Created: v1, updated once: v2, updated again: v3.

Key Format

Keys are auto-uppercased. Allowed characters: A-Z 0-9 _ - . Maximum 256 characters. Values can be up to 1 MB.

Commands

Login

Authenticate with an API key created from the web app:

envv login --token <YOUR_API_KEY>

Credentials are stored in ~/.envv/config.json.

List Secrets

List all secret keys in the organization (metadata only, no values):

# Defaults to the development environment
envv secrets list

# Target a specific environment
envv secrets list --env=production
Listing secrets for organization: Acme Corp (environment: production)

KEY                            VERSION    UPDATED AT
----------------------------------------------------------------------
DATABASE_URL                   3          2026-04-08 10:30:00
STRIPE_SECRET_KEY              1          2026-04-07 15:20:00
JWT_SECRET                     2          2026-04-06 09:00:00
Get a Secret

Retrieve the decrypted value of a single secret:

# Defaults to development
envv secrets get DATABASE_URL

# Read from a specific environment
envv secrets get DATABASE_URL --env=production
postgres://user:pass@host:5432/mydb
Set or Update a Secret

Create a new secret or update an existing one (version increments automatically):

# Write to development (default)
envv secrets set STRIPE_SECRET_KEY=sk_test_abc123

# Write to a specific environment
envv secrets set STRIPE_SECRET_KEY=sk_live_abc123 --env=production

Injecting Secrets at Runtime

envv run

Run any command with all organization secrets injected as environment variables:

# Run a Node.js server with secrets in process.env
envv run 'node server.js'

# Use with npm scripts
envv run 'npm start'

Common Use Cases

CI/CD with GitHub Actions

Store the API key as a GitHub secret, then use it in your workflow:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install EnvVault CLI
        run: brew install envvault/homebrew-envvault/envvault

      - name: Login
        run: envv login --token ${{ secrets.ENVVAULT_TOKEN }}

      - name: Deploy with secrets
        run: envv run 'docker compose -f docker-compose.prod.yml up -d'
Rotating a Secret

Update the value (version auto-increments) and restart services:

# Update the value
envv secrets set DATABASE_URL=postgres://user:newpass@host/db

# Verify
envv secrets get DATABASE_URL

# Restart services with new value
envv docker-run --env=production --restart -- docker compose up -d

Best Practices

Use API keys, not JWTs. API keys are organization-scoped and revocable.

Separate keys per environment. Don't reuse the same key across production, staging, and development.

Set expiration dates. When creating API keys, set an expiry to limit the blast radius of a leaked key.

Never commit secrets. Don't commit API keys or secret values to version control. Use CI/CD secret stores to provide ENVVAULT_TOKEN.

Audit regularly. Check the Audit Logs page for unexpected SECRET_READ events.

Troubleshooting

"No API key provided" (401)

The CLI couldn't find a token. Login again:

envv login --token <YOUR_API_KEY>
"Invalid or revoked API key" (401)

The API key was revoked or expired. Create a new one from the API Keys page in the web app.

"Secret not found" (404)

Check the spelling (keys are case-insensitive — auto-uppercased) and confirm the API key belongs to the right organization.

"Rate limit exceeded" (429)

You've exceeded 100 requests per 15 minutes from the same IP. Wait and retry.

Limits

Secret key length256 chars
Secret value size1 MB
Description length512 chars
Tags per secret20
Batch get size100 keys
Rate limit100 / 15 min / IP