Quick start
Every channel installs the same binary. The first release has not been published yet, so these commands start working with it; until then build from source (below). The release process is in docs/release.md.
| Channel | Command |
|---|---|
| Homebrew (macOS, Linux) | brew install --cask bendechrai/vaultfold/vaultfold |
| Scoop (Windows) | scoop bucket add vaultfold https://github.com/bendechrai/scoop-vaultfold then scoop install vaultfold |
| winget (Windows) | winget install Vaultfold.Vaultfold |
| npm | npm install --global vaultfold |
| Debian, Ubuntu | download the .deb from the latest release and run sudo apt install ./vaultfold_<version>_linux_<arch>.deb |
| Fedora, RHEL | download the .rpm from the latest release and run sudo dnf install ./vaultfold_<version>_linux_<arch>.rpm |
| Any Unix | curl -fsSL https://github.com/bendechrai/vaultfold/releases/latest/download/install.sh | sh (installs to ~/.local/bin; set VAULTFOLD_INSTALL_DIR to change it) |
Verifying a download. Every release asset is listed in checksums.txt, which is signed with the project's minisign key (the public key is packaging/minisign.pub). The release public key is:
RWTYFlucuugO3A1zFOF48/MLp6qLUuzDKLjIKNybr0H+OyLG70A5zKs1
This is the development placeholder, not a release key: it is replaced before the first release (docs/release.md, human item 3), and this line is updated with it. With minisign installed:
minisign -Vm checksums.txt -P RWTYFlucuugO3A1zFOF48/MLp6qLUuzDKLjIKNybr0H+OyLG70A5zKs1
sha256sum --check --ignore-missing checksums.txt
Or, from a clone, minisign -Vm checksums.txt -p packaging/minisign.pub.
install.sh checks the checksums itself, and also the signature when minisign is on PATH (VAULTFOLD_REQUIRE_SIGNATURE=1 makes the signature mandatory). Binaries are not yet signed by Apple or Microsoft, so Gatekeeper or SmartScreen may warn on a direct download; the Homebrew cask clears the macOS quarantine flag, and npm and install.sh do not set it.
Install from source (Go 1.25.5 or newer, and git 2.30 or newer). From a clone of this repository:
go install ./cmd/vaultfold
Create an identity. Where the OS keychain can be used it is protected there (Touch ID or the login password on a Mac, Windows Hello on Windows, the keyring on a Linux desktop); otherwise, or with --passphrase, it is a passphrase-protected key file and key new says why.
vaultfold key new
Create a vault inside a git repository that has a remote. init keeps the vault on its own branch, vaultfold, and registers it under the repository's name (here myapp). It uses git plumbing only: no checkout, nothing is committed on your code branch, and the repository's commit hooks never run. It pushes the branch, and writes vault.toml in the work tree without committing it; commit that file through your usual flow (a pull request is fine) so teammates and fresh clones find the vault. See "In-repo vaults and the vault branch" below for --same-branch, which keeps the vault in .vaultfold/ on the checked-out branch instead:
cd ~/src/myapp
vaultfold init
The first vault command starts the agent daemon in the background. It asks for the passphrase (or the OS keychain's confirmation) once, then keeps the vault unlocked until it locks: after 8 hours, an hour unused, on screen lock or sleep, or with vaultfold agent lock. vaultfold agent status shows what is unlocked; see "The agent daemon" in cmd/vaultfold/README.md for turning auto-start off (VAULTFOLD_NO_AGENT=1), approvals and settings. After upgrading vaultfold, run vaultfold agent stop so the next command starts the new daemon.
Store a secret. Values are never command-line arguments: without --stdin you are prompted with hidden input; with it the value is read from standard input.
vaultfold add app/db#password
printf '%s' "$NEW_DB_PASSWORD" | vaultfold add app/db#password --stdin
Read it back. On a terminal the value is masked unless you pass --reveal; piped, it is written raw for scripts.
vaultfold get app/db#password --reveal
vaultfold ls
Use it without writing it to disk: link writes a vault:// reference into an existing env file (JSON, YAML and TOML files work too, with their formatting kept; link edits a file in place, so it must already exist), and run resolves references into the child's environment (the child's output is masked on a terminal):
touch .env
vaultfold link .env DB_PASSWORD vault://app/db#password
vaultfold run --env-file .env -- npm start
Share the changes through the repository's remote (a vault on its own branch pushes that branch, from whatever branch you have checked out):
vaultfold sync
Add a teammate, or a second machine of your own. On the new machine, create an identity and export its public key:
vaultfold key new
vaultfold key show --public > me.pub
On a machine that already has the vault, an admin adds that key (after comparing the fingerprint words it shows). member add publishes the change itself, so it needs the remote to be reachable, and it prints a chain fingerprint (a link number and eight words) to give to the new member:
vaultfold member add alice --from me.pub
Then on the new machine, clone the repository. Running any vault command in the clone offers to register the vault (when vault.toml is committed, or the clone has the vaultfold branch); vault add does the same by hand. Adding --expect-head <fingerprint> to vault add refuses a remote that shows the new machine a different membership history:
git clone git@example.com:acme/myapp.git
cd myapp
vaultfold vault add myapp . --branch vaultfold
vaultfold sync
vaultfold get app/db#password --reveal
vaultfold doctor checks the vault, the repository and the agent daemon setup at any point. When an AI coding agent runs vaultfold, commands that would print a value are refused, by the CLI and by the daemon; what an agent may do (run, inject, writes) waits for you to approve the collection, in a system dialog or with vaultfold agent approve in your own terminal. vaultfold agent-help describes what agents should use instead.
To change what a member may do without revoking it, use vaultfold member grant <member> <role> and vaultfold member ungrant <member> <role>; root admins are peers, so any root admin can remove another's admin role directly. vaultfold member rename <member> <new-name> changes a display name, and vaultfold init --member-name <name> names the first member. cmd/vaultfold/README.md, "Managing members", has the walkthrough.
Membership changes (adding, revoking, granting, removing and renaming members, revoking devices, new epochs and collections, key rotate) are recorded on a linear policy chain (ADR 0046). Each of these commands pulls first, writes on the latest state and publishes in the same command, so it needs the backend: offline it exits 4 and writes nothing, while reading and writing entries keep working offline. A removal or revocation is final once the command reports it published, though another root admin can grant a removed role back.