CLI Reference

Install and authenticate the varsafe CLI, resolve context, and master the run/export workflows — plus the generated command reference.

Installation

The CLI is a self-contained binary — it is not published on npm. Supported platforms: Linux and macOS on x64 and arm64, except Linux on arm64 (currently unsupported). Windows works via WSL.

curl -fsSL https://varsafe.dev/install.sh | bash

The installer downloads the binary to ~/.varsafe/bin and adds it to your shell’s PATH. Verify the install and explore the commands — no account needed:

# docs-test: offline
# Check the CLI is installed and explore its commands — no account needed.
set -euo pipefail

varsafe --version

varsafe --help

echo "OK:help"

To upgrade later, the binary updates itself:

varsafe update

Commands at a glance

The CLI has 11 flat commands — no nested subcommands:

Every command and flag is documented in the generated reference at the bottom of this page.

Authentication

There are three ways to authenticate, from most to least interactive.

Browser login (default)

varsafe login

The CLI opens your browser and prints a short, human-readable confirmation code in the terminal. Approve the request in the browser — after checking the code matches — and the CLI completes automatically via a server push, falling back to polling if the streaming connection drops. Your password never passes through the terminal.

Email and password

For machines without a browser:

varsafe login --no-browser

varsafe login --no-browser --register

API token (CI and automation)

API tokens (created in the dashboard under team settings, prefixed vs_at_) are the non-interactive path. Four ways to supply one:

# The CLI picks the token up automatically — no login step needed
export VARSAFE_API_TOKEN="vsafe_example_ci_token"
varsafe run -- ./deploy.sh

varsafe login -t "vsafe_example_ci_token"

# "-" reads the token from stdin — keeps it out of argv
secret-manager read varsafe-token | varsafe login -t -

# Interactive masked input — never lands in shell history
varsafe login -T

Session commands

varsafe whoami   # show the authenticated user and teams
varsafe logout   # revoke the session server-side and clear local credentials

Logout invalidates the session immediately — a stolen credentials file is useless afterward.

Environment variables

Context

Commands that touch secrets need a project and environment. Resolution order:

1. Flags — -p/--project and -e/--env (or -i/--project-id in automation) always win
2. Local .varsafe file — found by searching from the current directory up to the git root
3. Global saved context — set via varsafe use
4. Auto-selection when only one option exists; interactive prompt otherwise

# Set context — inside a git repo this writes a .varsafe file,
# elsewhere it saves globally
varsafe use -p my-api -e development

# View the current context
varsafe use

# Clear it
varsafe use --clear

This tested script removes a secret and exercises the context lifecycle:

# docs-test: local-stack
# Remove a secret and manage the saved context.
set -euo pipefail

varsafe login --token "$VARSAFE_TOKEN" --api-url "$VARSAFE_API_URL"
varsafe use -p "$VARSAFE_PROJECT" -e development

varsafe set TEMP_FLAG "true"
varsafe unset TEMP_FLAG

# Context can be cleared at any time; commands then need -p/-e flags
varsafe use --clear
varsafe list -p "$VARSAFE_PROJECT" -e development

echo "OK:unset-and-context"

Inject secrets into a process

varsafe run is the core workflow: it fetches secrets over TLS and injects them as environment variables into the child process. Nothing is written to disk; when the process exits, the secrets are gone.

varsafe run -- npm run dev

The command after -- is executed argv-exact — no shell re-parsing, so quoting is preserved and arguments arrive in the child process exactly as you wrote them. Status messages (“Injecting 5 secrets”) go to stderr, so stdout stays clean for piping.

Narrow what gets injected:

# Only secrets matching glob patterns (comma-separated)
varsafe run --include 'VITE_*,CRISP_*' -- bun run build

# Filter by prefix and inject with PREFIX_ prepended
varsafe run --prefix monitoring -- ./run-monitoring.sh

Merge in an encrypted .env file — file values win over API values, and the flag can be repeated:

varsafe run --env-file .env --env-file .env.local -- npm start

The tested version, including the child process assertion:

# docs-test: local-stack
# Inject secrets into a child process as environment variables — no file
# is ever written to disk.
set -euo pipefail

varsafe login --token "$VARSAFE_TOKEN" --api-url "$VARSAFE_API_URL"
varsafe use -p "$VARSAFE_PROJECT" -e development

varsafe set API_KEY "vsafe_example_run_inject_value"

# The child process sees API_KEY; your shell never does.
varsafe run -- sh -c 'test -n "$API_KEY"'

# Only inject secrets matching a pattern
varsafe run --include 'API_*' -- sh -c 'test -n "$API_KEY"'

echo "OK:run-inject"

Read a single value

For piping one secret into another tool, varsafe get prints just the value:

# Use a secret inline without exposing it in your shell profile
psql "$(varsafe get DATABASE_URL)"

# Exact bytes, no trailing newline — for tools that are byte-sensitive
varsafe get SIGNING_KEY -n > /dev/shm/key

# Structured output: {key, value, version, updatedAt}
varsafe get DATABASE_URL --json

Export secrets to a file

When a tool insists on a file, varsafe export writes one. The .env format is encrypted by default: the file starts with a #@varsafe/v1/ek_<id> header identifying the environment key, and each value is individually encrypted (varsafe:v1:...). Encrypted .env files are readable only by your team — safe to commit — and are decrypted on the fly by varsafe run --env-file.

# Encrypted .env (default)
varsafe export -o .env

# Plaintext requires an explicit opt-in
varsafe export --plain -o .env

# Other formats: dotenv (env), docker, kubectl, json, yaml —
# auto-detected from the output file extension, or forced with -f
varsafe export --plain -o secrets.json
varsafe export --plain -f yaml

# Write to RAM-backed tmpfs (/dev/shm) so the file never touches disk
varsafe export --plain --tmpfs -o app.env

The tested export flow, covering the encrypted default, --plain, and format variants:

# docs-test: local-stack
# docs-test-allow-plaintext
# Export secrets when a file is genuinely required. The default .env export
# is encrypted; --plain is an explicit opt-in.
set -euo pipefail

varsafe login --token "$VARSAFE_TOKEN" --api-url "$VARSAFE_API_URL"
varsafe use -p "$VARSAFE_PROJECT" -e development

varsafe set SMTP_HOST "smtp.example.com"

workdir="$(mktemp -d)"
trap 'rm -rf "$workdir"' EXIT

# Encrypted .env (default) — values are unreadable without your team keys
varsafe export -o "$workdir/.env"
grep -q '#@varsafe/v1/' "$workdir/.env"

# Plaintext requires an explicit flag
varsafe export --plain -o "$workdir/plain.env"
grep -q 'SMTP_HOST=' "$workdir/plain.env"

# Other formats: json, yaml, docker
varsafe export --plain -f json -o "$workdir/secrets.json"
varsafe export --plain -f yaml -o "$workdir/secrets.yaml"

echo "OK:export-formats"

CI/CD usage

For pipelines, set VARSAFE_API_TOKEN from your CI secret store — no varsafe login step is required:

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install varsafe CLI
        run: curl -fsSL https://varsafe.dev/install.sh | bash

      - name: Deploy with secrets
        run: varsafe run -p my-api -e production -- ./deploy.sh
        env:
          VARSAFE_API_TOKEN: ${{ secrets.VARSAFE_API_TOKEN }}

deploy:
  stage: deploy
  script:
    - curl -fsSL https://varsafe.dev/install.sh | bash
    - varsafe run -p my-api -e production -- ./deploy.sh
  variables:
    VARSAFE_API_TOKEN: $VARSAFE_API_TOKEN

Exit codes

varsafe run is an exception: once the child process starts, run exits with the child’s exit code, so wrappers and CI steps behave as if the command ran directly.

Uninstall

To remove varsafe from your system:

# Remove the binary and local data
rm -rf ~/.varsafe

Then remove the PATH entry from your shell configuration:

# Edit ~/.zshrc and remove the line:
# export PATH="$HOME/.varsafe/bin:$PATH"

# Edit ~/.bashrc and remove the line:
# export PATH="$HOME/.varsafe/bin:$PATH"

# Edit ~/.config/fish/config.fish and remove:
# fish_add_path ~/.varsafe/bin

If you used varsafe use in any project directories, you can also delete the .varsafe context files in those repositories.

Troubleshooting

varsafe login

# If you have only one project, it's auto-selected
varsafe list

# Or set context interactively
varsafe use

varsafe use -p my-project -e development

export PATH="$HOME/.varsafe/bin:$PATH"

Command reference

Generated from the CLI’s own --help output — always matches the shipped binary.

varsafe login

Authenticate with varsafe

varsafe login [options]

varsafe whoami

Show the currently authenticated user

varsafe whoami [options]

varsafe logout

Sign out and clear local credentials

varsafe logout [options]

varsafe list

Alias: ls

List secrets for a project and environment

varsafe list|ls [options]

varsafe run

Run a command with secrets as environment variables

varsafe run [options] <command...>

varsafe export

Export secrets to a file or stdout (env format encrypts by default, use –plain to disable)

varsafe export [options]

varsafe get

Print a single secret value to stdout (pipe-friendly)

varsafe get [options] <key>

varsafe set

Set a secret in an environment

varsafe set [options] <key> <value>

varsafe unset

Remove a secret from an environment

varsafe unset [options] <key>

varsafe update

Update varsafe CLI to the latest version

varsafe update [options]

varsafe use

Set default project and environment for commands

varsafe use [options]