CLI Tool

Command reference for @envpilot/cli v1.19.0. Requires Node.js 22+.

Install#

npm install -g @envpilot/cli

Or with bun:

bun install -g @envpilot/cli

Or run a single command without installing:

npx @envpilot/cli login

Quick start#

# 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
 
# Set one secret — key first, value typed into a masked prompt
envpilot secrets set
 
# Compare two environments
envpilot diff staging production

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:

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#

Push never creates approval requests. If you hold at least one write grant, the keys you cannot write are listed as denied and skipped while the rest go through; if your role has no write access to the target environment at all, the whole push is refused rather than written partially. To propose a brand-new variable for review, use envpilot request instead.

Command reference#

Get Started#

envpilot

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

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.

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.

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.

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>] [--environment <env>] [--force] [--add]

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

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>] [--force] [--no-guard]

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

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>] [--prefix <prefix>] [--project <name-or-id>] [--dry-run] [--all] [--force]

Download project variables into a local file or export format.

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] [--format <format>] [--prefix <prefix>] [--project <name-or-id>] [--dry-run] [--force]

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

envpilot push
envpilot push --replace

Writes only the keys you have access to — denied keys are listed, never silently dropped. Push does not create approval requests; see Push behavior by role.

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.

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

How the cache works

envpilot run verifies freshness on every run with one cheap metadata fingerprint check (~50-100 ms, no vault decryption) — a variable changed in the dashboard shows up on your very next run. The expensive vault decryption only happens when something actually changed:

Pass --cache-ttl <seconds> to skip even the fingerprint check for a window (fastest, but blind to changes for that long). run also tells you when accessible variables exist only in other environments — Injected 8 of 12 — 4 not in development: FOO, BAR — instead of silently dropping them.

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:

# 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

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:

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

Secrets#

envpilot secrets set [KEY | KEY=VALUE]

Set (create or update) one secret — no pull → edit → push round-trip. Two-step by default: the key is validated first, then the value is typed into a masked prompt, so it never lands in your shell history or ps output. Alias: envpilot var.

envpilot secrets set                          # guided: key → masked value → sensitive?
envpilot secrets set STRIPE_KEY -e production # key given, value prompted masked
envpilot secrets set API_URL=https://api.example.com  # CI only — lands in shell history

Options: -e, --env <environment> · -p, --project <name-or-id> · -d, --description <text> · --sensitive · --all-envs

Role-aware: if your role can't write variables directly, the same flow files a variable request for review instead of rejecting you.

A value shared across multiple environments lives on one variable — updating it changes all of them, so the CLI asks for confirmation first (--all-envs non-interactively).

Setting a key to its current value is an idempotent no-op, reported as "already has this value".

envpilot secrets rm <KEY>

Delete one secret from one environment.

envpilot secrets rm OLD_FLAG
envpilot secrets rm OLD_FLAG -e staging --yes

A secret that exists only in the selected environment moves to trash (recoverable from the dashboard).

A secret shared across environments is re-scoped instead: the selected environment is detached, and the value stays live in the others.

Variable Requests#

Developers (and any custom role with the request capability) submit requests; reviewers approve them — now entirely from the terminal.

envpilot request

Interactive wizard to submit a new-variable request (key → masked value → description → environments).

envpilot requests [list] [--project <p>] [--status <s>] [--json]

List requests for the linked project, with an ID column for review actions.

envpilot requests
envpilot requests --status pending --json

envpilot requests approve <id> / reject <id> / cancel <id>

Close the review loop without opening the dashboard.

envpilot requests approve k5738xq2…
envpilot requests reject k5738xq2… --reason "use the shared key"
envpilot requests cancel k5738xq2…
 
# Machine (valueless) requests: you supply the secret at approval —
# interactively via a masked prompt, or from stdin in CI:
printf %s "$SECRET" | envpilot requests approve k5738xq2… --value-stdin

Approving a valueless machine request prompts masked for the value and encrypts it server-side. --value exists for CI without stdin and is rejected in interactive sessions (it would land in shell history).

Browse#

envpilot diff <envA> <envB> [--values] [--project <name-or-id>] [--json]

Compare variables between two environments — the drift check before a deploy.

envpilot diff staging production           # keys only: no decryption, no audit noise
envpilot diff staging production --values  # also compare decrypted values
envpilot diff staging production --json    # single parseable JSON document

Default is metadata-only. With --values, keys that fail decryption are reported as an explicit "comparison unknown" bucket — never a false "only in" result.

envpilot list [resource]

List organizations, projects, variables, or linked projects from the 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.

envpilot usage
envpilot usage --json

Shows project, member, and variable limits.

Useful for CLI feature-gate troubleshooting.

Project#

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

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

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.

envpilot unlink
envpilot unlink api --force

Updates .envpilot and active-project state.

Leaves existing .env files on disk.

Account#

envpilot accounts [list | switch <identifier> | remove <identifier>]

List authenticated accounts and switch or remove them without logging out. Each envpilot login adds an account instead of replacing the current session.

envpilot accounts                        # list authenticated accounts
envpilot accounts switch you@example.com
envpilot accounts remove you@example.com

Identifiers can be an account id or the account's email (case-insensitive).

Switching accounts does not log anyone out; use envpilot logout to remove the active session.

envpilot whoami

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

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.

envpilot config
envpilot config path

Useful for local development against non-production API URLs.

Shows both global and project-level config paths.

envpilot logout [--all]

Revoke the current CLI session and clear local auth state.

envpilot logout
envpilot logout --all   # log out of every authenticated account

Best way to reset a stale CLI session cleanly.

Clears local tokens even if the revoke call fails.

--all targets every account added via envpilot login, not just the active one. If a remote revoke fails partway through (e.g. offline), the run stops at that account — re-run envpilot logout --all to clear the rest.