Command Reference

envctl init

Initialize your identity by generating a cryptographic keypair.

This must be run before using any other envctl commands. Your identity is stored in ~/.config/envctl/ and protected by a passphrase.

Options

--name <name>

Set a custom display name (default: username-hostname)

--keychain

Store passphrase in the system keychain for automatic unlock

--yubikey

Store the private key on a YubiKey for hardware-backed security

Examples

# Basic initialization
$ envctl init

# With a custom name
$ envctl init --name alice-work-laptop

# With keychain storage (no passphrase prompts)
$ envctl init --keychain

# With YubiKey
$ envctl init --yubikey

Related: whoami

envctl whoami

Display your identity information.

Options

--verbose

Show full public key (useful for sharing)

Examples

$ envctl whoami
Name: alice-macbook
Fingerprint: sha256:7f3a9b2c4d5e6f7a...

$ envctl whoami --verbose
Name: alice-macbook
Fingerprint: sha256:7f3a9b2c4d5e6f7a8b9c0d1e...
Public key: 7f3a9b2c4d5e6f7a8b9c0d1e2f3a4b5c...

envctl project create

Create a new project and link it to the current directory.

Options

--envs <names>

Comma-separated list of environments to create (default: dev,stage,prod)

--default-access <env>

Default environment access for new members (default: dev)

Examples

# Create with default environments
$ envctl project create myapp

# Create with custom environments
$ envctl project create myapp --envs dev,qa,stage,prod

# Create with custom default access for new members
$ envctl project create myapp --envs local,test,live --default-access local

Related: join, project invite

envctl project delete

Delete a project's local chain file.

This is a local-only operation that removes your copy of the project's chain. Other project members still have their copies and can continue using the project. Use this to clean up test projects or projects you no longer participate in.

Options

--silent

Delete without confirmation prompt

Examples

$ envctl project delete testproject
Delete local chain for 'testproject'? [y/N] y
✓ Deleted testproject

$ envctl project delete testproject --silent
✓ Deleted testproject

Note: This does NOT remove you from the project or notify other members. To formally leave a project, use project leave instead.

envctl project invite

Invite a team member to the project.

Options

--pubkey <key> (required)

The invitee's public key (from envctl whoami --verbose)

--ttl <duration>

How long the invite is valid (default: 10m)

--env <names>

Environments to grant access to (default: dev)

--role <role>

Role to assign: admin, member, or reader (default: member)

Examples

# Basic invite
$ envctl project invite bob --pubkey 8d4e2f1a...
✓ Invitation created
  Share this with bob: envctl join eyJwcm9qZWN0...

# Invite with specific environments
$ envctl project invite bob --pubkey 8d4e2f1a... --env dev,staging

# Invite as admin with prod access
$ envctl project invite bob --pubkey 8d4e2f1a... --env dev,staging,prod --role admin

Related: join, project remove

envctl project remove

Remove a team member from the project.

After removal, you'll be prompted to rotate secrets for environments the member had access to. This opens your editor for each environment so you can set new values for sensitive secrets (API keys, passwords, etc.) that the removed member may have copied.

Options

-s, --silent

Skip all prompts (removal confirmation and rotation prompt)

Examples

$ envctl project remove bob
Remove 'bob' from project? [y/N] y
Member 'bob' removed.

'bob' had access to: dev, stage

SECURITY: The removed member may have copied secret values.
You should set NEW values for sensitive secrets (API keys, passwords, etc.)

Rotate secrets for these environments? [Y/n] y

Rotating secrets for myapp/dev...
# Opens $EDITOR with current values - update secrets as needed
  Updated: DATABASE_PASSWORD, API_KEY
Rotating secrets for myapp/stage...
# Opens $EDITOR again for the stage environment
  Updated: DATABASE_PASSWORD

Done. Updated secrets will be synced to team members when the daemon is running.

# Silent mode - skip all prompts
$ envctl project remove bob --silent
Member 'bob' removed.

Related: Offboarding guide

envctl join

Join an existing project using an invitation code.

Run this command in the directory where you want to work on the project. The invite code is provided by an existing project member.

Examples

$ cd ~/projects/myapp
$ envctl join eyJwcm9qZWN0IjoibXlhcHAi...
✓ Joined project "myapp"
  Environments: dev, staging
Syncing secrets...

Related: project invite

envctl project members

List all members of the project.

Examples

$ envctl project members
Members of myapp:

alice (admin)     dev, staging, prod
bob (member)      dev, staging
carol (reader)    dev

envctl project leave

Leave the current project.

Any member can leave a project at any time. The last admin cannot leave (must promote another admin first).

Examples

$ envctl project leave
Leave project 'myapp'? [y/N] y
✓ Left project myapp

envctl project link

Link the current directory to an existing project.

Use this when you want to work with a project that was created elsewhere or shared by a team member. The project must exist in your local chains directory.

Examples

$ cd ~/work/backend
$ envctl project link myapp
✓ Linked directory to project 'myapp'
Default environment: dev

You can now use:
  envctl fetch dev    # Get secrets sent by team members
  envctl use dev      # Decrypt local secrets

envctl project access

Show environment access for all members.

Examples

$ envctl project access
Environment Access for myapp:

          dev    staging    prod
alice      ✓        ✓        ✓
bob        ✓        ✓        -
carol      ✓        -        -

envctl project grant

Grant a member access to additional environments.

Options

--env <names> (required)

Comma-separated list of environments to grant

Examples

$ envctl project grant bob --env staging
✓ Granted bob access to staging

$ envctl project grant bob --env staging,prod

envctl project revoke

Revoke a member's access to environments.

Options

--env <names> (required)

Comma-separated list of environments to revoke

Examples

$ envctl project revoke bob --env prod
✓ Revoked bob's access to prod

envctl project pending

Show pending proposals that require approval.

In multi-admin projects, sensitive operations (member removal, dissolution) require approval from other admins.

Examples

$ envctl project pending
Pending proposals for myapp:

#1  Remove member 'bob'
    Proposed by: alice (2 hours ago)
    Approvals: 1/2 required

#2  Grant staging access to carol
    Proposed by: alice (1 hour ago)
    Approvals: 1/1 required (auto-approve)

Related: project approve, project deny

envctl project approve

Approve a pending proposal.

Examples

$ envctl project approve 1
✓ Approved proposal #1 (Remove member 'bob')
  Awaiting 1 more approval

envctl project deny

Deny a pending proposal.

Examples

$ envctl project deny 1
✓ Denied proposal #1 (Remove member 'bob')

envctl project log

Show the project's blockchain history.

Displays all membership changes, access grants, and other governance actions recorded on the chain.

Examples

$ envctl project log
Chain history for myapp (height: 12):

#12  grant_access     alice granted carol access to dev
#11  member_add       carol joined as reader
#10  revoke_access    alice revoked bob's prod access
#9   grant_access     alice granted bob access to staging
...
#1   genesis          alice created project

envctl project dissolve

Dissolve a project (requires admin consensus).

This creates a dissolution proposal. In multi-admin projects, other admins must approve. Once dissolved, the project cannot accept new blocks.

Options

--reason <text>

Reason for dissolution (recorded in chain)

Examples

$ envctl project dissolve oldproject --reason "Project completed"
! Dissolution requires approval from 2 admins
✓ Created dissolution proposal

Warning: Dissolution cannot be undone. Dissolved projects remain visible for historical record but cannot be modified.

envctl project invites

List all invites for the project.

Examples

$ envctl project invites
Invites for myapp:

ABC-DEF-GHI  valid     bob (member)      expires in 8m
XYZ-123-456  expired   carol (reader)    expired 2h ago
QWE-RTY-UIO  used      dave (member)     joined yesterday

envctl project revoke-invite

Revoke an unused invite code.

Only valid (unused, non-expired) invites can be revoked.

Options

--reason <text>

Reason for revocation (recorded in chain)

Examples

$ envctl project revoke-invite ABC-DEF-GHI --reason "Wrong person"
✓ Revoked invite ABC-DEF-GHI

envctl env list

List all environments in the current project.

Examples

$ envctl env list
Environments for myapp:

* dev          (3 members)
  staging      (2 members)
  prod         (1 member)

The asterisk (*) indicates your current environment.

envctl env create

Create a new environment.

Examples

$ envctl env create qa
✓ Created environment 'qa'

envctl env delete

Delete an environment and all its secrets.

Options

--force

Skip confirmation prompt

Examples

$ envctl env delete qa
Delete environment 'qa' and all its secrets? [y/N] y
✓ Deleted environment 'qa'

envctl env use

Switch to an environment and write a .env file.

Decrypts secrets for the specified environment and writes them to a .env file in the current directory.

Options

--no-overrides

Ignore local .env.<name> override files

Examples

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

$ envctl env use staging --no-overrides
✓ .env written (5 secrets)

Related: env apply, env shell

envctl env apply

Run a command with secrets injected into the environment.

Secrets are injected directly into the process environment without writing a .env file to disk.

Options

-e, --env <name>

Environment to use (default: current)

Examples

# Run npm start with dev secrets
$ envctl env apply -- npm start

# Run with production secrets
$ envctl env apply -e prod -- ./deploy.sh

# Run tests with staging secrets
$ envctl env apply -e staging -- npm test

Related: env shell, env use

envctl env shell

Open an interactive shell with secrets loaded.

Starts your default shell (bash, zsh, etc.) with secrets in the environment. Type exit to leave and clear secrets from memory.

Options

-e, --env <name>

Environment to use (default: current)

Examples

$ envctl env shell
Starting bash with 3 secrets from myapp/dev
Type 'exit' to leave and clear secrets from memory.

$ echo $API_KEY
sk_dev_abc123

$ exit
Exited envctl shell. Secrets cleared.

envctl env clear

Remove the .env file from the current directory.

Examples

$ envctl env clear
✓ Removed .env

envctl env edit

Edit environment variables interactively in your default editor.

Opens a temporary file with your secrets in $EDITOR. Changes are saved when you close the editor.

Options

-e, --env <name>

Environment to edit (default: current)

Examples

$ envctl env edit
# Opens $EDITOR with secrets
✓ Updated 2 variables

envctl env var set

Set an environment variable.

Options

-e, --env <name>

Environment to modify (default: current)

Examples

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

# Set in specific environment
$ envctl env var set -e prod DATABASE_URL=postgres://prod-db/mydb
✓ Set DATABASE_URL in prod

# Set multiple variables
$ envctl env var set API_KEY=sk_live_abc123
$ envctl env var set STRIPE_KEY=pk_live_xyz789

Related: env var delete, env var list

envctl env var delete

Delete an environment variable.

Options

-e, --env <name>

Environment to modify (default: current)

Examples

$ envctl env var delete OLD_API_KEY
✓ Deleted OLD_API_KEY from dev

envctl env var list

List all variables in an environment.

Options

-e, --env <name>

Environment to list (default: current)

Examples

$ envctl env var list
Variables in myapp/dev:

DATABASE_URL = postgres://localhost/mydb
API_KEY      = sk_de...23 (redacted)
DEBUG        = true

envctl status

Show the current project and sync status.

Examples

$ envctl status
Project: myapp
Environment: dev (3 secrets)
✓ Synced with 2 peers

# When out of sync
$ envctl status
Project: myapp
Environment: dev (3 secrets)
! 2 pending updates from alice

envctl log

View the audit log of changes.

Options

--since <duration>

Show logs since (e.g., 1h, 24h, 7d)

--search <text>

Filter by text (author name, variable name, etc.)

--limit <n>

Maximum entries to show

--follow

Stream new entries as they arrive

Examples

$ envctl log
2024-03-01 14:30  alice  Set API_KEY in prod
2024-03-01 14:28  alice  Set DATABASE_URL in prod
2024-02-28 10:00  bob    Set STRIPE_KEY in dev

$ envctl log --since 24h --search alice

envctl push

Push local changes to connected peers.

Usually sync is automatic when the daemon is running. Use this command to force an immediate push.

Examples

$ envctl push
✓ Pushed 3 operations to 2 peers

envctl pull

Pull changes from connected peers.

Examples

$ envctl pull
✓ Pulled 5 operations from alice
  dev: 2 variables changed
  staging: 3 variables changed

envctl project relay set

Configure a relay server for async sync.

The URL can be a hostname (relay.envctl.dev) or a full WebSocket URL (wss://relay.envctl.dev/ws).

Examples

$ envctl project relay set relay.envctl.dev
✓ Relay configured for myapp
  URL: wss://relay.envctl.dev/ws

Related: Relay guide

envctl project relay status

Show relay connection status.

Examples

$ envctl project relay status
Relay Status for myapp:

  URL: wss://relay.envctl.dev/ws
  Status: connected
  Last message: 2 minutes ago

envctl daemon start

Start the background daemon for P2P sync.

Options

--p2p-port <port>

Port for P2P connections (default: 7834)

--web-port <port>

Port for the web UI (default: 7835)

Examples

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

envctl daemon stop

Stop the running daemon.

Examples

$ envctl daemon stop
✓ Daemon stopped

envctl daemon run

Run the daemon in the foreground (useful for debugging).

Unlike daemon start, this runs the daemon in the foreground and logs to stderr. Press Ctrl+C to stop.

Options

--p2p-port <port>

Port for P2P connections (default: 7834)

--web-port <port>

Port for the web UI (default: 7835)

Examples

$ envctl daemon run
INFO  Starting daemon...
INFO  P2P listening on :7834
INFO  Web UI at http://localhost:7835
^C
INFO  Shutting down...

envctl daemon status

Show the status of the running daemon.

Options

--json

Output status as JSON

Examples

$ envctl daemon status
Daemon Status:
  Running: yes
  PID: 12345
  Uptime: 2h 15m
  Identity: alice-macbook
  P2P Address: :7834
  Connected Peers: 2
  Projects: 3

envctl daemon env

Print shell commands to set up the daemon socket.

Outputs export commands for your shell. Useful for scripts that need to communicate with the daemon.

Examples

$ envctl daemon env
export ENVCTL_SOCKET=/Users/alice/.config/envctl/envctl.sock

$ eval "$(envctl daemon env)"

envctl daemon install

Install the daemon as a system service (launchd on macOS, systemd on Linux).

Configures the daemon to start automatically when you log in.

Examples

$ envctl daemon install
✓ Installed launch agent
✓ Daemon will start automatically on login

# To start now:
$ envctl daemon start

Related: daemon uninstall

envctl daemon uninstall

Remove the daemon from system services.

Examples

$ envctl daemon uninstall
✓ Stopped daemon
✓ Removed launch agent

envctl ci keygen

Generate a keypair for CI/CD pipelines.

Creates a CI-specific keypair. The public key is stored on the project's team chain and automatically synced to all team members. The private key is shown once—store it in your CI platform's secrets. Requires the daemon to be running.

Options

-f, --force

Replace existing CI key

Examples

$ envctl ci keygen
Generated CI keypair for project "myapp"

Public key stored on project chain (committed)

CI Private Key (store in your CI platform's secrets as ENVCTL_CI_KEY):

Kz4xN2U5...base64...

This private key will NOT be shown again.

Related: CI/CD guide

envctl ci export

Export an encrypted bundle for CI pipelines.

Encrypts your environment variables using the project's CI public key (from the team chain). Requires the daemon to be running. You'll be prompted for your identity passphrase.

Options

-e, --env <name>

Environment to export (default: dev)

-o, --output <file>

Output file (default: stdout)

Examples

$ envctl ci export -e prod -o .envctl/prod.enc
Passphrase:
Exported 8 variables to .envctl/prod.enc

$ git add .envctl/prod.enc
$ git commit -m "Update CI secrets"

envctl ci apply

Run a command with secrets decrypted from a CI bundle.

Designed for CI runners. Decrypts the bundle using the CI private key from an environment variable and injects secrets into the command's environment. No daemon or identity required—just the bundle file and the CI private key.

Options

-b, --bundle <file>

Path to encrypted bundle (default: .envctl/secrets.enc)

--key-env <var>

Environment variable containing CI private key (default: ENVCTL_CI_KEY)

Examples

# In GitHub Actions
- name: Run tests
  env:
    ENVCTL_CI_KEY: ${{ secrets.ENVCTL_CI_KEY }}
  run: envctl ci apply -b .envctl/prod.enc -- npm test

envctl doctor

Run health checks to diagnose issues.

Options

--fix

Attempt to fix issues automatically

Examples

$ envctl doctor
✓ Identity configured
✓ Daemon running (PID 12345)
✓ P2P port 7834 accessible
! Relay not configured

All checks passed (1 warning)

Related: Troubleshooting

envctl ui

Open the envctl web UI in your default browser.

The web UI provides a visual interface for managing your projects and team. The daemon must be running.

Options

--no-open

Print the URL instead of opening the browser

Features

• Project members — View all members and their roles
• Pending requests — Approve or deny join requests and proposals
• Connected peers — See who's currently online
• Audit log — Review recent activity and changes

Examples

$ envctl ui
Opening http://localhost:7835 in browser...

$ envctl ui --no-open
http://localhost:7835

Related: Web UI Guide