Skip to content
Zero Docs

ZeroVault CLI

zv is the ZeroVault command-line tool, published as zerovault-cli on npm. It manages projects, environments, secrets, and API keys. It talks to ZeroVault only; ZeroErrors has no CLI.

Run it

Section titled “Run it”

The current published version is 0.2.2. Run it without installing:

Terminal window
pnpm dlx zerovault-cli@0.2.2 --help

The command is zv. Install it globally to drop the pnpm dlx prefix and run zv … directly:

Terminal window
npm i -g zerovault-cli@0.2.2

Authenticate

Section titled “Authenticate”

The CLI needs an API key. Create one in the dashboard under ZeroVault → API Keys (see Getting started) and copy it. The simplest way to pass it is an environment variable:

Terminal window
export ZEROVAULT_API_KEY=zv_your_key_here
zv whoami

whoami prints your user and organization IDs, which confirms the key works:

User ID: user_…
Org ID: org_…

The key is resolved in this order, first match wins:

  1. --api-key flag
  2. a directory-bound context (see below)
  3. the ZEROVAULT_API_KEY environment variable

The API base URL defaults to https://api.zeroapps.dev/vault. Override it with --base-url or ZEROVAULT_API_URL only if you target a different instance.

Contexts (optional)

Section titled “Contexts (optional)”

If you juggle several keys or organizations, save them as named contexts instead of exporting the variable. Contexts live in ~/.config/zerovault/config.json (mode 0600, since it holds plaintext keys).

Terminal window
zv context add work --api-key zv_your_key_here
zv context use work        # binds the current directory to this context
zv context current         # prints the active context name
zv context list

zv context use binds the directory you run it in (and its subdirectories) to that context, so zv there uses that key without the environment variable.

Manage secrets

Section titled “Manage secrets”

Projects start with development and production environments.

Terminal window
zv projects create demo
zv projects list


zv secrets set API_TOKEN=abc123 -p demo -e development
zv secrets list  -p demo -e development     # values shown masked
zv secrets get   API_TOKEN -p demo -e development   # prints the value

zv secrets set is create-or-update; run it again with the same key to change the value. Set several at once by passing more KEY=VALUE pairs. Delete a secret with:

Terminal window
zv secrets delete API_TOKEN -p demo -e development

Download secrets

Section titled “Download secrets”

zv secrets download writes an environment’s secrets in the format you ask for (env, json, yaml, or shell), to stdout or a file with -o.

Terminal window
zv secrets download -p demo -e development -f env
API_TOKEN=abc123
DB_URL=postgres://localhost

-f json emits a flat { "KEY": "VALUE" } object, which is what wrangler secret bulk expects.

Manage API keys

Section titled “Manage API keys”

Once authenticated, the CLI creates and revokes the same organization-scoped keys as the dashboard. Your first key still has to come from the dashboard, since zv keys needs a key to authenticate with.

Terminal window
zv keys create -l ci            # prints the new key once; save it
zv keys list                    # id, prefix, label, created date
zv keys revoke <id>             # revoke by id from the list

A created key is shown once, same as in the dashboard. Save it immediately; if you lose it, revoke it and create another.

Back up the whole vault

Section titled “Back up the whole vault”

zv export dumps every project and secret across your organization as plaintext JSON, and zv import <file> restores it. Because the file is plaintext, delete it as soon as you are done.

Terminal window
zv export -o vault-backup.json

Next

Section titled “Next”