Your First Project

This tutorial walks you through the complete KeyEnv workflow: authenticating, creating a project, managing secrets, and running your application with secrets injected.

Prerequisites:

KeyEnv CLI installed
A KeyEnv account (sign up here)

Authenticate with your KeyEnv account:

keyenv login

This opens your browser for authentication. Once complete, you'll see:

✓ Logged in as [email protected]
✓ Access token saved to keychain

Verify your session anytime with:

keyenv whoami

Step 2: Initialize a Project

Navigate to your project directory:

cd ~/my-project
keyenv init

You'll be prompted to either select an existing project or create a new one:

? Select a project:
❯ Create new project
  my-existing-project
  another-project

If creating new, enter a project name:

? Project name: my-awesome-app
? Default environment: development

✓ Project 'my-awesome-app' created
✓ Configuration saved to .keyenv.toml

This creates a .keyenv.toml configuration file:

project_id = "abc123-def456-..."
default_environment = "development"

The .keyenv.toml file is safe to commit. It only contains the project ID, not secrets.

Step 3: Add Your First Secrets

Add secrets using the CLI:

# Set a simple secret
keyenv set DATABASE_URL "postgres://localhost:5432/mydb"

# Set multiple secrets
keyenv set API_KEY "your-api-key"
keyenv set JWT_SECRET "your-jwt-secret"

For sensitive values, pipe from stdin to avoid shell history:

echo "sk_live_abc123..." | keyenv set STRIPE_SECRET_KEY -

List your secrets to verify:

keyenv list

Output:

Environment: development

DATABASE_URL      postgres://localhost:5432/mydb
API_KEY           your-*****-key
JWT_SECRET        ********
STRIPE_SECRET_KEY sk_live_*****

Step 4: Pull Secrets to .env

Sync secrets to a local .env file:

keyenv pull

Output:

✓ Pulled 4 secrets to .env

Your .env file now contains:

DATABASE_URL=postgres://localhost:5432/mydb
API_KEY=your-api-key
JWT_SECRET=your-jwt-secret
STRIPE_SECRET_KEY=sk_live_abc123...

Add .env to your .gitignore to prevent accidentally committing secrets.

Step 5: Run with Secrets Injected

The recommended way to use secrets is with keyenv run. This injects secrets as environment variables without writing them to disk:

keyenv run -- npm start

Or with any command:

# Node.js
keyenv run -- node server.js

# Python
keyenv run -- python app.py

# Docker
keyenv run -- docker-compose up

The -- separates KeyEnv options from your command.

Step 6: Work with Different Environments

KeyEnv supports multiple environments (development, staging, production). Specify the environment using the -e/--env flag:

# Pull staging secrets
keyenv pull --env staging

# Run with production secrets
keyenv run --env production -- npm start

# Set a default environment in .keyenv.toml
# Edit the file and change: default_environment = "staging"

The -e/--env flag works with most commands (pull, push, run, set, get, list). To change your default environment, edit the default_environment value in your .keyenv.toml file.

What's Next?

You've learned the basics! Here's where to go next:

Core Concepts - Understand projects, environments, and teams
CLI Reference - Complete command documentation
CI/CD Integration - Set up secrets in your pipeline
Docker Guide - Use KeyEnv with containers

Quick Reference

Command	Description
`keyenv login`	Authenticate with KeyEnv
`keyenv init`	Initialize a project
`keyenv set KEY value`	Set a secret
`keyenv get KEY`	Get a secret value
`keyenv list`	List all secrets
`keyenv pull`	Sync secrets to .env
`keyenv run -- cmd`	Run command with secrets
`keyenv push`	Push local .env to server

Your First Project

On this page