CLI Tool

Command reference for @envpilot/cli v1.6.0. Requires Node.js 18+.

Install#

❯terminal

npm install -g @envpilot/cli

Or with bun:

❯terminal

bun install -g @envpilot/cli

Or run a single command without installing:

❯terminal

npx @envpilot/cli login

Quick start#

❯terminal

# One-command setup: authenticate, pick a project, pull variables
envpilot sync
 
# Or step by step
envpilot login
envpilot init
envpilot pull
 
# Inject secrets at runtime without writing a .env file
envpilot run -- bun dev

Interactive TUI#

Run envpilot with no arguments to open the terminal dashboard. Use arrow keys to browse commands, Enter to run, Esc to exit. The TUI returns after each command finishes.

Output formats#

envpilot pull supports seven export formats:

❯terminal

envpilot pull                         # .env (default)
envpilot pull --format json           # JSON
envpilot pull --format yaml           # YAML
envpilot pull --format vercel         # Vercel
envpilot pull --format netlify        # Netlify TOML
envpilot pull --format aws            # AWS Parameter Store JSON
envpilot pull --format docker-compose # Docker Compose

Push behavior by role#

Role	Behavior
Admin / Team Lead	Push succeeds immediately
Developer	Creates pending requests for approval
Viewer	Blocked with an error

Command reference#

Get Started#

`envpilot`

Open the Ink-powered terminal dashboard for discovering and running commands.

❯terminal

envpilot
envpilot ui
envpilot dashboard

This is the default when you run envpilot with no subcommand.

Supports search, keyboard navigation, and command launch.

`envpilot ui`

Open the interactive Ink-powered terminal UI.

❯terminal

envpilot ui
envpilot dashboard

Use this when you want the UI explicitly instead of relying on the default no-arg launcher.

`envpilot man [command]`

Show the CLI manual page with commands, workflows, and security guidance.

❯terminal

envpilot man
envpilot man pull

Use this to see the supported command set.

Supports per-command manual sections.

`envpilot login [--api-url <url>] [--no-browser]`

Authenticate the CLI against the Envpilot web app.

❯terminal

envpilot login
envpilot login --no-browser

Opens the web authentication page by default.

Required before organization or project commands will work.

`envpilot init [--organization <id>] [--project <id>] [--env <environment>]`

Link the current directory to a project and choose a default environment.

❯terminal

envpilot init
envpilot init --add

Creates or updates the local .envpilot file.

Supports linking multiple projects with --add.

Sync#

`envpilot sync [--organization <id>] [--project <id>] [--env <environment>]`

Authenticate, select a project, pull variables, and set up local protection in one flow.

❯terminal

envpilot sync
envpilot sync --env production

Best first-run workflow for local setup.

Reuses the existing login, init, and pull logic under the hood.

`envpilot pull [--env <environment>] [--file <path>] [--format <format>]`

Download project variables into a local file or export format.

❯terminal

envpilot pull
envpilot pull --env staging --dry-run

Supports .env, JSON, YAML, Vercel, Netlify, AWS, and Docker Compose formats.

Can pull the active linked project or all linked projects.

`envpilot push [--env <environment>] [--file <path>] [--merge|--replace]`

Upload local variables back to Envpilot with approval-aware write behavior.

❯terminal

envpilot push
envpilot push --replace

Managers/admins write directly; lower roles create requests for approval.

Compares local and remote variables before applying changes.

Run#

`envpilot run [options] -- <command> [args...]`

Inject project secrets as environment variables directly into a child process — no .env file is written to disk. Secrets are fetched from the vault, injected into the process environment, and disappear when the process exits.

❯terminal

envpilot run -- bun dev
envpilot run -- npm test
envpilot run -- node server.js
envpilot run -- python manage.py runserver
envpilot run --env production -- node dist/server.js
envpilot run --env staging --print

Secrets are injected via process.env — no file is created, nothing to gitignore, nothing to leak.

Use -- to separate envpilot flags from the command you want to run.

Options

Flag	Default	Description
`-e, --env <environment>`	linked env	Environment to load (`development`, `staging`, `production`)
`-p, --project <name-or-id>`	active project	Override the linked project
`-o, --organization <id>`	linked org	Override the organization
`--keep-existing`	off	Let your shell's env vars win over fetched secrets (useful for local overrides)
`--print`	off	Preview what would be injected and exit — no command runs
`--shell`	off	Run via the user's shell (enables pipes, `&&`, `$VAR` expansion)
`--no-cache`	off	Skip the cache and always fetch fresh secrets
`--cache-ttl <seconds>`	`3600`	How long cached secrets stay fresh before a fingerprint check
`-q, --quiet`	off	Suppress informational output

How the cache works

envpilot run uses a fingerprint-gated local cache to avoid hitting the vault on every invocation:

Cache state	What happens	Vault calls
Fresh (< 1 h)	Serve from disk	0
Stale, vars unchanged	Cheap metadata check → extend TTL	0
Stale, vars changed	Metadata check detects change → full fetch	1×
First run / cache cleared	Full fetch, write cache	1×

Cache files are stored at ~/.config/envpilot/run-cache/ with 0600 permissions (owner read/write only). A different account, server URL, or token automatically invalidates the cache.

Overriding shell variables

By default fetched secrets override anything already in your shell. Use --keep-existing to reverse this — your local shell values win:

❯terminal

# Override everything with Envpilot secrets (default)
envpilot run -- bun dev
 
# Your shell's DATABASE_URL wins; only missing vars are filled in
DATABASE_URL=postgres://localhost/dev envpilot run --keep-existing -- bun dev

Dry-run preview

❯terminal

envpilot run --print
# Would inject 12 variables from backend/staging:
#
#   DATABASE_URL=post…rd (52 chars)
#   API_SECRET=sk_t…2x (40 chars)
#   ...
# Dry run — no command executed.

CI/CD usage

In CI pipelines, use --quiet and --no-cache to suppress output and guarantee fresh secrets:

❯terminal

envpilot run --env production --quiet --no-cache -- ./scripts/deploy.sh

Browse#

`envpilot list [resource]`

List organizations, projects, variables, or linked projects from the terminal.

❯terminal

envpilot list
envpilot list projects
envpilot list variables

Default resource is projects.

Use linked to inspect local .envpilot project links.

`envpilot usage [--organization <id>] [--json]`

Inspect current plan usage and feature availability for the active organization.

❯terminal

envpilot usage
envpilot usage --json

Shows project, member, and variable limits.

Useful for CLI feature-gate troubleshooting.

Project#

`envpilot switch [--organization <id>] [--project <id>] [--env <environment>] [--active <name-or-id>]`

Switch the active organization, project, environment, or linked project.

❯terminal

envpilot switch --env production
envpilot switch --active api

Updates local CLI state without rewriting the whole project config.

Supports both linked projects and remote project lookup.

`envpilot unlink [project] [--force]`

Remove a linked project from the current directory without deleting local env files.

❯terminal

envpilot unlink
envpilot unlink api --force

Updates .envpilot and active-project state.

Leaves existing .env files on disk.

Account#

`envpilot whoami`

Show the authenticated user, API target, and current active CLI context.

❯terminal

envpilot whoami

Validates the current access token against the website.

Useful for debugging stale auth or wrong API URL targets.

`envpilot config [list|get|set|path|reset]`

Inspect or update local CLI configuration such as the active API URL.

❯terminal

envpilot config
envpilot config path

Useful for local development against non-production API URLs.

Shows both global and project-level config paths.

`envpilot logout`

Revoke the current CLI session and clear local auth state.

❯terminal

envpilot logout

Best way to reset a stale CLI session cleanly.

Clears local tokens even if the revoke call fails.