Getting started

This quickstart takes you from a new install to a child process using a vault secret. It uses a deliberately non-sensitive demo value and never prints that value back to the terminal.

1. Install TinyVault

Every method installs the same single binary. Use whichever your machine already has:

Method	Install	Update
Homebrew (macOS, Linux)	brew install --cask abdul-hamid-achik/tap/tvault	brew upgrade --cask tvault
npm (any OS, Node 18+)	npm install -g @thelacanians/tinyvault	npm install -g @thelacanians/tinyvault@latest
Go toolchain (1.26 or later)	go install github.com/abdul-hamid-achik/tinyvault/cmd/tvault@latest	re-run the same command
Linux packages	.deb, .rpm, or .apk from GitHub Releases	your package manager

The npm package is a thin launcher: it installs the tvault binary for your platform as an optional dependency and runs it directly. That also makes it the zero-install path for an MCP host, which can spawn npx -y @thelacanians/tinyvault mcp. The Go route compiles the tagged release from source; because the version string is stamped by the release pipeline rather than by the Go toolchain, that binary reports tvault version dev — expected, and without effect on behavior.

Direct binary archives (.tar.gz and .zip, for every supported OS and architecture) are on the same releases page. If you installed one of those, tvault self-update replaces the binary in place after verifying the release checksum. Keep using the package manager for Homebrew, npm, and distro packages so its bookkeeping stays correct.

If Homebrew reports that the retired formula is installed, migrate once to the maintained cask:

brew uninstall --formula tvault
brew install --cask abdul-hamid-achik/tap/tvault

Confirm that tvault is on your PATH:

tvault --version

2. Create a vault

tvault init

TinyVault asks you to create and confirm a passphrase, creates the default project, and writes the vault database to ~/.tvault/vault.db.

Secret values and key material in the database are encrypted. Names and operational metadata, including project names and secret key names, are not confidential.

Keep the passphrase

TinyVault has no hosted recovery service or recovery key. Keep the passphrase separately from a backup of the vault database. Losing either one removes the complete owner view; recipient identities configured later can recover only projects explicitly shared to them.

3. Store a value through standard input

When a value arrives on standard input, TinyVault cannot use that same stream to prompt for the vault passphrase. In Bash or zsh, read the passphrase without echo, export it for this operation, and remove it immediately afterward:

printf 'Vault passphrase: ' >&2
read -rs TVAULT_PASSPHRASE
printf '\n' >&2
export TVAULT_PASSPHRASE

printf '%s' 'quickstart-demo-value' | tvault set API_TOKEN --stdin
unset TVAULT_PASSPHRASE

The value above is deliberately non-sensitive. For a real credential, pipe it from your password manager, credential generator, or another trusted source. Avoid putting it directly after the key because command arguments can be retained in shell history or exposed to other local tooling.

set reads the passphrase from TVAULT_PASSPHRASE, unlocks the vault for this command, stores the encrypted value, and closes the vault again.

4. List the key without decrypting values

tvault list --names-only

The output includes:

API_TOKEN

--names-only does not ask for the passphrase and never decrypts a value. This works because key names are readable metadata in the database. The default tvault list path does unlock the vault; use --names-only when names are all you need.

5. Inject the value into a child process

Run a command with only API_TOKEN added to its environment:

tvault run --only API_TOKEN -- sh -c 'test -n "$API_TOKEN" && echo "API_TOKEN is available to the child process"'

TinyVault prompts for the passphrase, decrypts the selected value, and passes it to sh. The command confirms that the variable exists without printing it.

The --only flag narrows injection to an explicit key. The -- separator is optional when there is no flag conflict, but using it consistently makes clear where TinyVault options end and the child command begins.

Trust the child command

The CLI does not redact a child process's terminal output or prevent it from writing files, logs, or network traffic. Run only commands you trust with the selected secrets.

Use the same pattern with your application:

tvault run --only DATABASE_URL -- npm start
tvault run --prefix APP_ -- python manage.py runserver

How unlocking works

TinyVault does not remain unlocked after a normal CLI command. Commands that need plaintext prompt for the passphrase, use the derived key for that invocation, and clear it when the command exits.

If repeated prompts interrupt your local workflow, the optional local agent can hold the unlock key for a limited time on Unix.

Choose your next step

• Run and env — select keys, combine a .env template, or render environment output.
• Projects — separate applications and environments.
• Dotenv workflows — import, diff, sync, and interpolate existing .env files.
• MCP server — connect an AI agent with a fail-closed policy.
• Security and threat model — understand metadata exposure and trust boundaries.
• CLI reference — look up every command and flag.