Core Concepts

Understanding these concepts will help you get the most out of KeyEnv.

Projects

A project is a collection of secrets for a single application or service. Each project can have multiple environments.

• Projects are identified by a unique ID
• You can switch between projects with keyenv switch
• Projects can be shared with team members

Environments

Environments are isolated sets of secrets within a project. Common environments include:

Each environment has its own set of secrets with the same keys but different values:

# development
DATABASE_URL=postgres://localhost/mydb

# production
DATABASE_URL=postgres://prod-server/mydb

Secrets

A secret is a key-value pair. Secrets have:

• Key: The environment variable name (e.g., DATABASE_URL)
• Value: The sensitive data
• Version: Incremented on each update
• Description: Optional documentation

Version History

Every change to a secret is tracked. You can:

• View the history of changes with keyenv history SECRET_NAME
• See who made each change and when
• Audit access and modifications

Environment Permissions

Environment permissions control who can access secrets in each environment. Permission levels:

This allows you to:

• Give developers full access to development
• Restrict production to senior engineers
• Grant read-only access for debugging

Service Tokens

Service tokens are API keys for CI/CD and automated systems. They:

• Have limited permissions (specific project/environment)
• Can be scoped to a single environment for extra security
• Never expire but can be revoked
• Are used instead of user authentication in automated pipelines

# In CI/CD, set the token as an environment variable
export KEYENV_TOKEN="env_..."
keyenv pull

Team Collaboration

KeyEnv supports team workflows:

• Members can view and modify secrets
• Admins can manage team settings and members
• All changes are attributed to the user who made them

Next Steps

Now that you understand the concepts, explore:

• CLI commands for all operations
• Web app guide for browser-based management