Skip to content
PulsVaultDocs
Get started
Solo ProTeamBusinessEnterprise

pulsvault CLI

The single-binary CLI — what it is, how to install it, the path shortcut every command shares, and where to go for each task.

pulsvault is a single static binary — no runtime, no interpreter, nothing to install alongside it. It talks to the machine data-plane with a pv_live_… API key, which makes it the shortest path from a shell script or a CI job to a secret.

It is a machine client. There is no user login: a key authenticates as a machine identity, and it can do exactly what its policies allow — never more.

Start here#

I want to… Page
Store a key and point the CLI at a deployment Authenticating
Pick a profile, or set a default project so paths get shorter Profiles & defaults
Find out what secrets exist Finding secrets
Read a value, safely Reading secrets
Create, edit, move or delete a secret Writing secrets
See history, compare or roll back Versions & rotation
Get secrets into a build or a running process Using in CI
Check whether a credential is validated, and still works Validating credentials
Look up one command's exact flags Command reference

Install#

bash
brew tap pulsvault/tap && brew install pulsvault
# or
curl -fsSL https://raw.githubusercontent.com/PulsVault/pulsvault-cli/main/install.sh | sh

Verify a downloaded archive against the published SHA256SUMS before running it. Then check what you have:

bash
pulsvault version
pulsvault help                 # every command, grouped
pulsvault help rotate          # one command's flags and examples

Shell completion is worth the ten seconds — paths are long and completion removes most of the typing:

bash
pulsvault completion zsh  > "${fpath[1]}/_pulsvault"     # or bash / fish

The five minutes that matter#

Everything else on these pages is a variation of this:

bash
pulsvault login                                                  # once per machine; paste the key
pulsvault list acme-web/prod/product/web                         # what's in here?
pulsvault get  acme-web/prod/product/web/db/password --reveal     # read one value
pulsvault run --namespace acme-web/prod/product/web -- ./app      # hand them to a process

Paths, and the --project shortcut#

Every path is {project}/{env}/{namespace}/{secret} — the scheme is explained in Paths, plans & roles. Set a default project and you can drop the leading slug, which is convenient when a pipeline only ever touches one:

bash
pulsvault config project acme-web                 # stored per profile — survives the shell
export PULSVAULT_PROJECT=acme-web                 # this shell, or this CI job
pulsvault --project acme-web get prod/product/web/db/password   # this command only

However it is set, paths may then omit it:

bash
pulsvault get prod/product/web/db/password        # resolves to acme-web/prod/…

A path that already begins with the configured project is never rewritten, so a fully-qualified path always works and mixing the two styles is safe. With no project configured, paths must be fully qualified — the CLI will not guess which segment is which. The stored form, the full resolution order and the config file behind it are covered in Profiles & defaults.

The project shortcut is a prefix, not a default scope

--project only fills in a missing first segment. It does not restrict what a command can reach: a fully-qualified path to another project still works, subject to what the key's policies allow.

Output for humans, output for scripts#

Most read commands take -o json or -o yaml (a stdlib renderer, sorted keys — no extra dependency). Structured output is unmasked, because it exists to be consumed rather than displayed:

bash
pulsvault versions acme-web/prod/product/web/db/password -o json
pulsvault list acme-web/prod/product/web -o yaml

-q suppresses non-essential output — progress lines, hints, the write-target banner — and leaves errors alone. Use it in pipelines where only the exit code and the payload matter.

Exit codes#

Every command exits non-zero on failure, so && chaining and CI gates behave as you would expect:

bash
pulsvault validate acme-web/prod/product/web/db/uri && ./deploy.sh

Two cases worth knowing, because both once looked like success:

  • A rejected or expired key exits non-zero on whoami and status, not just on a read. Gating a pipeline on pulsvault whoami is therefore meaningful — but gate on the plain form: status -o json reports the outcome in its payload and exits 0 either way. See Authenticating.
  • validate and validation-status do not stop at non-zero — they exit with a code that names the outcome: 1 the credential genuinely failed, 3 the check could not be completed, 4 nothing is configured for that path, 5 PulsVault was unreachable. So a timeout does not read as a revoked credential. See Validating credentials.
Writes announce their target before they run

set, delete, rotate, import and the other mutating commands print the resolved profile and host to stderr — → mycorp https://vault.mycorp.com/api/v1 — before doing anything. It is the cheapest protection against writing production values into the wrong deployment. -q suppresses it.

Was this page helpful?