CLI Commands

Global Usage

envault [command] [flags]

Global flags:

• --config <path>: custom CLI config file
• -e, --env <slug>: target environment
• -v, --version: print version

login

Authenticate with Envault using secure device flow.

envault login

This opens a browser for approval and stores a personal access token in local CLI config.

init

Initialize current directory and link/select a project.

envault init

If no project is linked, operational commands (pull, diff, deploy, run) can also trigger project selection. When creating a new project from CLI, you will also be prompted for:

• workspace mode (simple or advanced)
• default environment (development, preview, production)

pull

Fetch remote secrets and write them to a local env file.

envault pull --project <project-id> --env preview --file .env.preview

Flags:

• -p, --project <id>: project UUID
• --file <path>: output file path override
• -f, --force: skip overwrite confirmation

File resolution (if --file not provided):

1. mapped file for environment
2. auto-detected .env* file
3. fallback .env

Automatic safety on every pull

Every time pull writes secrets to disk it runs three automatic safeguards:

1. Tracked-file hard block

   • If the target file is already tracked in your git repository the command refuses to write anything. Overwriting a tracked file would silently include secrets in your next commit. The CLI prints the exact commands needed to untrack it before retrying.

2. Auto-gitignore - If the target file is not already covered by .gitignore (or .gitignore does not exist), the CLI adds an entry automatically. You will see a confirmation line whenever this happens.

3. Pre-commit hook

   • If a git repository is present and the audit hook has not been installed, it is installed automatically. If no git repository is detected yet the CLI reminds you to run envault audit --install-hook after git init.

Secret ordering

Secrets returned by pull are always sorted alphabetically (A–Z) by key before being written to disk. This ordering is consistent across all surfaces:

• Local .env file written by envault pull
• .env file downloaded from the dashboard
• Variables displayed in the in-app project table
• Import dialog preview and processing order

This makes diffs, version-control reviews, and manual comparisons predictable regardless of the insertion order in the vault.

git rm --cached .env
echo '.env' >> .gitignore
git commit -m 'stop tracking .env'

Access Request Flow

If the project has a GitHub repository linked and you are a collaborator on that repository, pull automatically and permanently grants you Viewer membership in that project. Your account is recorded in the project's access list - no manual invite or owner approval required. Subsequent commands like envault status work immediately, and the project appears in your "Shared with me" dashboard.

If you do not have access and are not a recognized GitHub collaborator, the CLI prompts:

You do not have access to this project. Would you like to send an access request to the project owner? (y/N)

• y: an access request notification is sent to the project owner. Run envault pull again once approved.
• N: exits cleanly without sending a request.

If a request was already submitted and is still pending:

You already have a pending access request for this project.

When you run pull with --env <slug>, that requested environment is carried through approval notifications so owners can grant scoped access directly.

Environment access denials (403)

pull, diff, deploy, and run now return a specific environment access error when your role is valid for the project but blocked for the selected environment.

• Check your active environment with envault status.
• Retry with an environment you can access: --env <slug>.
• If needed, request additional environment access from the project owner.

deploy

Push local env file values to remote vault for target environment.

envault deploy --env production --file .env.production

Alias: envault push

Behavior:

• Reads local env file
• Computes and prints diff summary first
• Prompts confirmation unless --force
• Sends secrets to target environment

Flags:

• -p, --project <id>: project UUID
• --file <path>: local env file override
• --dry-run: print what would be pushed
• -f, --force: skip confirmation

Tracked-file hard block

Before reading a single byte from your env file, deploy checks whether that file is tracked in git. If it is, the command refuses to run and prints:

BLOCKED: .env is tracked in your git repository. Your secrets may already be exposed in your git history.

The CLI prints the exact git rm --cached commands needed to fix the situation and reminds you to rotate any secrets that may have been visible in your history.

status

Show current session and execution context.

envault status --project <project-id>

Output includes:

• authenticated user email
• resolved project and role
• permission scope
• default environment
• active target environment
• resolved local env file

diff

Compare local file against remote secrets for one environment.

envault diff --env production --file .env.production

Output markers:

• Green +: additions (local only)
• Red -: deletions (remote only)
• Yellow ~: modifications (same key, different value)

run

Run a command with target environment secrets injected into process env.

envault run --env production -- npm start

Example:

envault run --project <project-id> --env preview -- printenv API_URL

Offline behavior:

• run performs a strict short secrets fetch timeout (~3s).
• On successful online fetch, secrets are also encrypted and cached locally at ~/.envault/offline_cache.enc.
• On timeout/network transport failures, run falls back to the last cached secrets for the same project+environment.
• Auth/authorization/API errors (401/403/404) do not trigger cache fallback.
• Optional override for slow networks/bootstrap: set ENVAULT_RUN_TIMEOUT_SECONDS (for example 10) to increase the run fetch timeout.

audit

Make sure your local environment files are structurally valid and safe to commit. audit performs four checks:

# run a quick check in your repository
envault audit

# specify a different file or template
envault audit --file .env.staging --template .env.staging.example

Strict mode & machine output

• --strict upgrades all warnings to errors and will exit non-zero if any issue is found.
• --format=json emits a structured JSON object suitable for CI pipelines.

Pre-commit hook

The audit check can be embedded into a git pre-commit hook so every attempted commit is validated automatically:

envault audit --install-hook

The hook is idempotent (safe to run multiple times), preserves any existing content in .git/hooks/pre-commit, and embeds the absolute path of the binary that installed it - so git always invokes the correct version regardless of what is on $PATH at commit time.

You typically do not need to run this manually. The hook is installed automatically when you run envault init (if a git repository is present) and whenever envault pull writes secrets for the first time in a new repository.

env

Manage local environment mappings and default environment.

envault env map --env development --file .env.development
envault env default --env development
envault env unmap --env preview

Subcommands:

• env map --env <slug> --file <path>
• env unmap --env <slug>
• env default --env <slug>

completion

Generate shell completion scripts.

envault completion zsh
envault completion bash
envault completion fish
envault completion powershell

version

Print CLI version.

envault version
envault --version
envault -v

Error Behavior

• Invalid/missing auth token returns 401 and exits non-zero.
• Unauthorized access (403) prints a clear Access denied message and exits non-zero. If JIT access via GitHub is configured, the user is prompted to send an access request instead.
• Invalid --project value (non-UUID) is rejected client-side before API call.