Getting Started

Install envctl, create your identity, and set up your first project in under 5 minutes.

Installation

go install envctl.dev/go/envctl@latest

Requires Go 1.25 or later.

From Releases

Download pre-built binaries from the GitHub releases page.

Verify Installation

$ envctl version
envctl v1.0.0 (abc1234)

Initialize Your Identity

Before using envctl, you need to create your identity. This generates a cryptographic keypair that identifies you across all projects.

$ envctl init
Enter a passphrase (min 8 characters):
Confirm passphrase:

✓ Identity created
  Name: alice-macbook
  Fingerprint: sha256:7f3a9b2c...

Your identity is stored in ~/.config/envctl/
Share your public key with teammates to receive invites.

Options

--name <name>
Set a custom name (default: username-hostname)
--keychain
Store passphrase in system keychain (macOS/Windows/Linux)
--yubikey
Store identity on a YubiKey for hardware-backed security

Passphrase tips

Use a strong passphrase you can remember. If you use --keychain, the passphrase is stored securely and you won't need to enter it every time.

Start the Daemon

The daemon handles P2P sync, peer discovery, and serves the web UI. Start it now:

$ envctl daemon start
✓ Daemon started (PID 12345)
  P2P port: 7834
  Web UI: http://localhost:7835

Check its status anytime:

$ envctl daemon status

Auto-Start on Login

To have the daemon start automatically when you log in:

1. Store your passphrase in the system keychain

The daemon needs your passphrase to unlock your identity. For unattended startup, store it securely:

$ envctl keychain store
Enter passphrase:
Verifying passphrase... done
Storing in keychain... done

Passphrase stored in system keychain.
The daemon can now start automatically without prompting.

Note: If you created your identity with envctl init --keychain, the passphrase is already stored.

2. Install the service

$ envctl daemon install
✓ Installed launchd agent

3. Verify after reboot

$ envctl daemon status
Daemon Status

  Running:     yes
  PID:         12345
  Uptime:      2h 15m
  ...

Uninstalling

To remove the auto-start service:

$ envctl daemon uninstall

Create Your First Project

Navigate to your project directory and create an envctl project:

$ cd ~/myproject
$ envctl project create
Project name: myproject

✓ Created project "myproject"
  Environments: dev, staging, prod

Project linked to this directory.
Run 'envctl env var set KEY=value' to add your first secret.

This creates a .envctl/ directory in your project root. Add .envctl/ to your .gitignore if you don't want to track encrypted secrets in git (though it's safe to commit—they're encrypted).

Options

--envs <names>
Specify environments (default: dev, staging, prod)

Add Your First Secret

Add secrets using the env var set command:

$ envctl env var set DATABASE_URL=postgres://localhost/mydb
✓ Set DATABASE_URL in dev

$ envctl env var set API_KEY=sk_live_abc123
✓ Set API_KEY in dev

Secrets are immediately encrypted and signed with your identity. By default, secrets are added to the dev environment.

Add to a Specific Environment

$ envctl env var set -e prod API_KEY=sk_live_prod_xyz789
✓ Set API_KEY in prod

View Your Secrets

$ envctl env var list
Variables in myproject/dev:

DATABASE_URL = postgres://localhost/mydb
API_KEY      = sk_li...23 (redacted)

Use Your Secrets

There are several ways to use your secrets in development:

Option 1: Write a .env file

$ envctl env use dev
Passphrase:
✓ .env written (2 secrets)

This decrypts your secrets and writes them to a .env file. Most frameworks (Node.js, Python, Ruby, etc.) can read this automatically.

Option 2: Run a command with secrets injected

$ envctl env apply -- npm start
✓ Running with 2 secrets

Secrets are injected directly into the process environment. No .env file is written to disk.

Option 3: Open an interactive shell

$ envctl env shell
Passphrase:
Starting bash with 2 secrets from myproject/dev
Type 'exit' to leave and clear secrets from memory.

$ echo $API_KEY
sk_live_abc123
$ exit
Exited envctl shell. Secrets cleared.

Invite Your Team

To share secrets with a teammate, you need their public key. Ask them to run:

$ envctl whoami
Name: bob-laptop
Fingerprint: sha256:8d4e2f1a...
Public key: 7f3a9b2c4d5e6f7a8b9c0d1e...

Then invite them to your project:

$ envctl project invite bob --pubkey 7f3a9b2c4d5e6f7a8b9c0d1e...
✓ Invitation created

Share this with bob:

  envctl join eyJwcm9qZWN0IjoibXlwcm9qZWN0...

Invite expires in 10 minutes.

Your teammate runs the join command in their project directory:

$ cd ~/myproject
$ envctl join eyJwcm9qZWN0IjoibXlwcm9qZWN0...
✓ Joined project "myproject"
  Environments: dev, staging

Syncing secrets...

See the Team Onboarding guide for more details on inviting team members and managing access.

Basic Workflow

Once set up, your daily workflow looks like this:

# Check sync status
$ envctl status
Project: myproject
Environment: dev (2 secrets)
✓ Synced with 2 peers

# View recent changes
$ envctl log
2024-01-15 10:30  alice  Set API_KEY
2024-01-15 10:28  alice  Set DATABASE_URL
2024-01-14 16:45  bob    Created project

# Add or update a secret
$ envctl env var set NEW_SECRET=value

# Push to teammates (usually automatic)
$ envctl push

# Pull latest from teammates
$ envctl pull

Next Steps