A whole project

You need this computer connected first: Claude Code in 5 to 8 minutes does that.

The exampleCopy Anchor Link

A project folder acme with .env, .env.staging and .env.production:

vando init --dry-run
vando init
vando run -- pnpm dev
vando run --env staging -- pnpm dev

The first shows what would move, by name only. The second moves it into your vault with one Save on your phone. After that, pnpm dev gets the dev folder’s secrets, and --env staging the staging ones.

See the plan firstCopy Anchor Link

vando init --dry-run

It reads the env files in this folder and prints names and guesses, never a value. Claude may run it for you; it sends nothing and writes nothing.

What vando init would send to your phone from
~/acme
(names and guesses only):

dev → Work/acme/dev · 3 names from .env
    · DATABASE_URL secret
    · PORT setting
    · STRIPE_KEY secret

prod → Work/acme/prod · 2 names from .env.production
    · NODE_ENV setting
    · STRIPE_KEY secret

staging → Work/acme/staging · 1 name from .env.staging
    · STRIPE_KEY secret

  Your phone suggests how careful each folder is from its name (prod the
  strictest) and you choose there.

  Dry run: nothing was sent and nothing was written. No value was printed.
  To import, run vando init in your own terminal.

Each file becomes an environment, and each environment a folder in your vault: .env and .env.local are dev, .env.staging is staging, .env.production is prod. Files like .env.example or .env.bak are left out. A secret is hidden on your phone and in output; a setting (like PORT) is a plain value. A name it isn’t sure about is shown as secret?; you can change it on your phone.

--vault Work --project acme picks another place; --as-file keeps each environment as one env file instead of one thing per name.

Move it into your vaultCopy Anchor Link

Run it yourself, in your own terminal:

vando init

It shows the same plan and asks: Send these values to your phone, locked so only it can open them? Type yes:. (Run by Claude, it opens a page in your browser with the plan instead, and only your Send there sends it.) Then:

Sent to your phone, locked so only it can open it. Open Vando and tap Save (it waits 10 minutes).

Your phone shows Save 6 things from your laptop?, one section per folder, each with How careful?: dev starts at Easy, staging at Just me, prod at Fort Knox. Change any of them, then tap Save once, and do the steps of the strictest folder. Anything already in your vault is left as it is.

Back at the terminal, vando init writes two files for you to commit:

• .vando.toml: where this project’s secrets live. Names only.
• .env.example: every name, settings with their values, secrets blank.

Your .env files are not touched: vando init never deletes them. If one was ever committed to git, it says so: its values are in the repository’s history, so change them at the provider.

The .vando.toml fileCopy Anchor Link

# Vando: where this project's secrets live (names only: commit it). Run commands with vando run -- <command>.
project = "Work/acme"
default = "dev"

[environments]
dev = [".env"]
prod = [".env.production"]
staging = [".env.staging"]

project is the project’s folder in your vault. Each line under [environments] is a folder directly inside it (Work/acme/staging) and the env files whose vando:// references it fills in. default is the environment a command uses when it names none. If the file has a line Vando can’t read, every command refuses and names the line, rather than guess.

Run with itCopy Anchor Link

vando run -- pnpm dev

Your phone asks once for everything directly in Work › acme › dev (not its subfolders), with each secret’s level; the strictest one sets the steps. Pick how long, tap Give. Other environments:

vando run --env staging -- pnpm dev
vando run --folder Work/acme/prod -- node scripts/migrate.js

The time choices, exit codes 75 and 77, and ending access early work as for one secret.

References in .env filesCopy Anchor Link

A line in an env file can point into your vault instead of holding a value:

DB_URL=vando://Work/acme/prod/DB_URL
STRIPE_KEY=vando:STRIPE_KEY

vando run asks for each reference along with the rest, and the program gets the real value. vando:NAME means the thing called NAME in the current environment’s folder. They fail closed: if your phone didn’t give a reference, the program doesn’t start, and the message names the variable. The file itself is never rewritten by vando run.

vando init --rewrite, at your own terminal, replaces each imported secret in your env files with vando:NAME (the old file goes to the trash first).

See what a run would getCopy Anchor Link

vando env
vando env --env staging

vando env lists the names a run would set and where each comes from, without values. It asks your phone like vando run does (a live grant answers it without asking). vando env --reveal prints the values too, in your own terminal only.

Clean up the plain filesCopy Anchor Link

Once every command runs through vando run, move the env files that still hold plain values to the trash:

vando clean

It lists them and asks first, in your own terminal: Move 3 files to the trash? They stay there until you empty it. Type yes:. It never deletes anything; you empty the trash when you’re sure.

vando init --reconcile compares the names in your env files with the names in the vault folder, if you add a variable later.

What can go wrongCopy Anchor Link

Every flag: vando init, vando run, vando env, vando clean.

“vando init sends your env files’ values to your phone, so a person starts it”

Claude tried to run vando init where no terminal and no browser are available. Run it in your own terminal. vando init --dry-run works anywhere.

The phone can’t save the prod folder

prod starts at Fort Knox, which needs a security key. If you have none yet, change prod’s How careful? to Just me before you tap Save, or add a key first.

“It waited too long on your phone and was deleted. Nothing was saved. Run vando init again.”

The import waits 10 minutes for your Save. Run it again: nothing is sent twice while one is waiting.

“DB_URL holds a vando: reference your phone didn’t give, so nothing was run”

Run the command again and tick it on your phone, or remove the vando: value from the file.

“--env staging needs a .vando.toml in this project.”

Run vando init first, or name the folder: --folder Work/acme/staging.

“… names that differ only in case are one variable on some systems, so nothing was sent.”

Two names like API_KEY and api_key in one environment. Rename one, then run vando init again.

Last verified 15 October 2026