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

Service Tokens

Manage service tokens for CI/CD and programmatic access:

# List all service tokens
keyenv tokens list

# Create a token with specific scopes
keyenv tokens create --name deploy-ci --scope read
keyenv tokens create --name admin-token --scope admin --expires 90

# Create a token restricted to a specific environment
keyenv tokens create --name staging --scope write --env env_abc123

# Revoke a token
keyenv tokens revoke st_abc123
keyenv tokens revoke st_abc123 --yes    # skip confirmation

# Rotate a token (generates new, old gets grace period)
keyenv tokens rotate st_abc123
keyenv tokens rotate st_abc123 --grace-period 30

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

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

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

Teams

Manage teams and team members:

# List your teams
keyenv team list

# Show team details and members
keyenv team show team_abc123

# Invite a member (default role: member)
keyenv team invite team_abc123 user@example.com
keyenv team invite team_abc123 user@example.com admin

# Update a member's role
keyenv team role team_abc123 user_xyz admin

# Remove a member
keyenv team remove team_abc123 user_xyz

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