Quick Start

This guide walks you through setting up kiln for your project in 5 minutes. You’ll encrypt secrets, manage team access, and run applications with decrypted environment variables.

Prerequisites

• kiln installed on your system
• A project directory where you want to manage secrets
• Basic familiarity with environment variables

Initial Setup

1. Generate an encryption key

   kiln init key

   This creates:

   • Directoryhome

     • Directoryuser

       • Directory.kiln

         • kiln.key # Your private key (keep secret)
         • kiln.key.pub # Your public key (safe to share)

   Tip

   Want password protection? Use kiln init key --encrypt.

2. Create a configuration file

   kiln init config --recipients "$(whoami)=$(cat ~/.kiln/kiln.key.pub)"

   This creates kiln.toml with yourself as the first recipient.

3. Set your first secret

   kiln set DATABASE_URL

   kiln prompts you to enter the value securely (input is hidden).

4. Verify it works

   kiln get DATABASE_URL

5. Run your application

   kiln run -- your-application

   kiln automatically injects all encrypted variables into your application’s environment.

Team Setup

Expand to support a team member:

1. Teammate generates their key

   # Teammate runs on their machine
   kiln init key --path ./teammate.key

2. Add them to your project

   kiln rekey --file default --add-recipient "alice=$(cat ./teammate.key.pub)"

3. Update team configuration

   Edit kiln.toml to organize your team:

   [recipients]
   you = "age1..."
   alice = "age1..."
   
   [groups]
   developers = ["you", "alice"]
   
   [files]
   default = { filename = ".kiln.env", access = ["developers"] }

4. Create environment-specific files

   # Staging secrets (all developers)
   kiln set --file staging API_URL https://staging.api.com
   
   # Production secrets (you only)
   kiln set --file production SECRET_KEY super-secret-production-key

   Update kiln.toml:

   [files]
   default = { filename = ".kiln.env", access = ["developers"] }
   staging = { filename = "staging.env", access = ["developers"] }
   production = { filename = "prod.env", access = ["you"] }

Working with Environments

Development

kiln set DEBUG true
kiln set LOG_LEVEL debug
kiln run -- npm run dev

Staging

kiln set --file staging API_URL https://staging.api.com
kiln run --file staging -- ./deploy-staging.sh

Production

kiln set --file production SECRET_KEY production-secret
kiln run --file production -- ./deploy-production.sh

Version Control

Your encrypted files are safe to commit:

git add kiln.toml .kiln.env staging.env prod.env
git commit -m "Add encrypted environment configuration"
git push origin main

Caution

Never commit your private key (~/.kiln/kiln.key). Only commit encrypted files and kiln.toml.

Common Operations

Check file status:

kiln info --verify

Export for scripts:

eval $(kiln export)
kiln export --format json > config.json

Edit multiple variables:

kiln edit --file production

Next Steps

You now have a working kiln setup. Continue with:

Advanced Configuration Team Workflows Explore All Commands