Skip to content

Store and read secrets

This guide takes you from nothing to a vault with a few entries in it.

  • vaultfold installed (see the quick start).
  • git 2.30 or newer, and a git repository with a remote for the vault to live in.
  • A terminal, for the hidden-input prompts.

An identity is your key. Create one, then create a vault inside a repository that has a remote. init keeps the vault on its own branch, vaultfold, pushes that branch and registers the vault under the repository name. It uses git plumbing only: nothing is checked out, nothing is committed on your code branch and the repository's commit hooks never run. It writes vault.toml in the work tree without committing it, so commit that file through your usual flow and teammates will find the vault. vaultfold init --same-branch keeps the vault in .vaultfold/ on the checked-out branch instead.

Terminal window
vaultfold key new
cd ~/src/myapp
vaultfold init

An entry address is [<collection>/]<path>[#<field>]. Values are never command-line arguments: without --stdin you get a hidden-input prompt, and with it the value is read from standard input.

Terminal window
vaultfold add app/db#password
printf '%s' "db-pass-FAKE" | vaultfold add app/db#password --stdin
vaultfold add stripe/key --type apikey --tag billing --rotate-every 90d --stdin

--type picks the entry type (login, apikey, note, sshkey, certificate and others), --tag is repeatable, and --rotate-every 90d adds a reminder that vaultfold rotate shows later.

On a terminal get masks the value unless you pass --reveal. Piped, it writes the raw value for scripts.

Terminal window
vaultfold get app/db#password --reveal
vaultfold get app/db --field password --reveal
vaultfold ls
vaultfold ls stripe
vaultfold search billing
Terminal window
vaultfold mv stripe/key payments/stripe
vaultfold rm app/db#password
vaultfold rm payments/stripe

rm with #<field> removes one field; without it, the whole entry.

  • Vault commands start the agent daemon and unlock once: you give the passphrase (or confirm with the OS keychain) on the first command, and later commands ask nothing until the vault locks. Set VAULTFOLD_NO_AGENT=1 to skip the daemon, which unlocks in-process for that command only.
  • In an AI agent session get is refused; see the AI coding agents guide.
  • Values shorter than 8 bytes are not masked in run output.