KeyEnv CLI – Secrets Management

KeyEnv manages secrets and environment variables across projects and environments (development, staging, production). Secrets are stored encrypted on the server and synced to local .env files or injected at runtime.

Prerequisites

Check if installed: keyenv --version

Install if missing:

curl -fsSL https://keyenv.dev/install.sh | bash

Check auth: keyenv whoami

Login if needed: keyenv login (opens browser)

Project Setup

Projects are configured per-directory via .keyenv.toml. If no .keyenv.toml exists in the current directory tree, initialize first:

# Create new project
keyenv init --name "my-app"

# Or link to existing project
keyenv init --project <project-id>

This creates .keyenv.toml with project_id and default_environment.

List available projects: keyenv projects list

Switch project: keyenv switch <name-or-id>

Managing Secrets

All secret commands accept -e <env> to target a specific environment. Default is development.

# List secret keys (values hidden)
keyenv list
keyenv list -e production

# Get a specific secret value
keyenv get DATABASE_URL
keyenv get API_KEY -e production

# Set a secret (creates or updates)
keyenv set DATABASE_URL "postgres://localhost/mydb"
keyenv set API_KEY "sk_live_..." -e production

# Set from stdin (for piping sensitive values)
echo "secret-value" | keyenv set MY_SECRET -

# Generate a random secret
keyenv set SESSION_SECRET --generate
keyenv set ENCRYPTION_KEY --generate --length 64

# Delete a secret
keyenv delete OLD_KEY --yes

Syncing Secrets

# Pull remote secrets to local .env file
keyenv pull
keyenv pull -e staging

# Push local .env to remote (new keys only, existing skipped)
keyenv push

# Push with overwrite (updates existing keys too)
keyenv push --force

# Compare local .env with remote
keyenv diff
# + local_only  - remote_only  ~ modified

Running with Secrets

Inject secrets as environment variables without writing a .env file:

keyenv run -- npm start
keyenv run -e production -- node server.js
keyenv run -- python manage.py runserver

Exporting Secrets

# Export as dotenv (default)
keyenv export

# Export as JSON
keyenv export -e production -f json

# Export to file
keyenv export -o .env.local

# Export as shell commands (for eval)
eval "$(keyenv export -f shell)"

Secret History

# View change history
keyenv history DATABASE_URL

# View with limit
keyenv history API_KEY -e production --limit 5

Permissions

# View your permissions
keyenv permissions my

# List environment permissions
keyenv permissions list

# Grant access (roles: none, read, write, admin)
keyenv permissions set user@example.com write
keyenv permissions delete user@example.com

CI/CD with Service Tokens

In CI/CD, authenticate with a service token instead of browser login:

export KEYENV_TOKEN="env_..."
keyenv pull -e production

Or pass directly: keyenv login --token env_...

Global Flags

Environment Variables

Common Workflows

New project setup:

keyenv login
keyenv init --name "my-app"
keyenv set DATABASE_URL "postgres://localhost/mydb"
keyenv set API_KEY --generate

Pull secrets and run locally:

keyenv pull
# or without .env file:
keyenv run -- npm start

Sync .env file to a new environment:

keyenv push -e staging --force

Check what’s different before pushing:

keyenv diff -e staging