CLI Reference

tvault is a single binary, written in Go: a local-first secrets CLI and an MCP server (via the mcp subcommand). This page documents every command, its usage line, and its command-local flags.

Run tvault help for the long-form manual or tvault docs for machine-readable docs aimed at agents. Every command also supports -h/--help.

Looking for secret generation?

tvault generate KEY stores a random value and prints only metadata. The MCP tool vault_generate_secret does the same for agents. Read the audit log with tvault audit or over MCP (vault_audit_log).

Global flags

These persistent flags are available on every command:

Flag	Description
--config <file>	Compatibility selector for Viper's config input. Typed settings still load from <vault-dir>/config.yaml; use --vault to relocate them.
--vault <dir>	Vault directory (default ~/.tvault).
-p, --project <name>	Project to operate on (default: the active project).
--json	Emit machine-readable JSON instead of human text.
-v, --verbose	Verbose output.
--no-agent	Bypass a running tvault agent and unlock directly (also TVAULT_NO_AGENT).
-h, --help	Help for any command.

Root-only:

Flag	Description
--version	Print the version and exit. There is no version subcommand.

tvault --version
tvault get DATABASE_URL -p api --json
tvault env -p web --no-agent

Exit codes

Commands return meaningful exit codes so scripts and agents can branch on why something failed without parsing stderr.

Code	Meaning
0	OK.
1	Generic error.
3	Vault is locked.
4	Secret or project not found.
5	Not initialized — run tvault init.
6	Wrong passphrase (unlock failed).
7	Vault database is in use by another process.

tvault get MISSING_KEY; echo "exit=$?"   # exit=4

Aliases

Command	Aliases
set	s
get	g
list	ls
delete	rm, remove
projects	project, p
history	versions, hist
mcp	mcp-server
self-update	upgrade
env group	env groups

tvault use <project> is shorthand for tvault projects use <project>.

---

Getting started

init

tvault init

Create the vault and a default project. Prompts for a passphrase interactively; set TVAULT_PASSPHRASE to skip the prompt (useful in CI). Run this once before anything else.

This command takes no command-local flags.

status

tvault status

Show vault state: whether it is initialized, locked or unlocked, and the active project. Takes no command-local flags.

doctor

tvault doctor

Run read-only diagnostics over the vault and configuration. Exits non-zero if any check fails, so it is safe to gate CI on.

---

Secrets

generate

tvault generate SESSION_SECRET
tvault generate API_KEY --length 48 --charset hex
tvault generate TOKEN --json

Generate a cryptographically random secret, store it, and print only metadata (key, length, charset, stored). The value is never written to stdout or stderr. Use tvault run or tvault get when a process needs it.

Flag	Description
--length <N>	Length in characters (default 32, max 256).
--charset <name>	alphanumeric (default), hex, base64, or ascii.

set

tvault set DATABASE_URL postgres://user:pass@localhost/app
tvault set API_KEY --stdin
tvault set TLS_CERT -f ./cert.pem
tvault set NEW_KEY --from-env .env --key OLD_KEY

Store a secret. The current value is encrypted with the project DEK, and the prior version is archived in the same transaction. An empty value is rejected. Alias: s.

Flag	Description
--stdin	Read the value from stdin.
-f, --from-file <path>	Read the value from a file.
--from-env <path>	Read the value from a dotenv file.
--key <name>	Source key when --from-env is used (defaults to <key>).

get

tvault get DATABASE_URL
tvault get API_KEY --version 3
tvault get API_KEY --from .env

Print a single secret value. Reading from the vault decrypts on demand and is audited. Alias: g.

Flag	Description
--from <path>	Read the value from a dotenv file instead of the vault (no unlock).
--version <N>	Print a specific historical version (default: current).
--group <name>	Resolve the key through an environment group's inheritance chain.
--env <name>	Environment within the group (requires --group).
--show-source	Show which environment a resolved value came from (with --group).

list

tvault list
tvault list --prefix STRIPE_

List secret keys in the active project. Metadata only — values are never printed or decrypted. Alias: ls.

Flag	Description
--prefix <str>	Only show keys starting with this prefix.
--names-only	List key names only. Lock-free — never decrypts, so it works on a locked vault.

delete

tvault delete API_KEY
tvault delete API_KEY -y

Delete a secret. This also purges that key's version history. Aliases: rm, remove.

Flag	Description
-y, --yes	Skip the confirmation prompt.

search

tvault search --name-like 'STRIPE_*' --since 2026-01-01T00:00:00Z
tvault search -p api --prefix DB_ --limit 50

Search secret metadata across projects. Never decrypts values.

Flag	Description
-p, --project <name>	Restrict to one project (default: all projects).
--prefix <str>	Keys starting with this prefix.
--name-like <pattern>	SQL-like pattern with * wildcard, e.g. STRIPE_*.
--since <RFC3339>	Updated at or after this timestamp.
--until <RFC3339>	Updated at or before this timestamp.
--min-version <N>	Only secrets with version >= N.
--limit <N>	Maximum results (default 200).

---

Projects

projects

tvault projects <subcommand>

Manage projects. Aliases: project, p. Subcommands below.

projects list

tvault projects list

List all projects. No command-local flags.

projects create

tvault projects create api -d "Backend API secrets"

Flag	Description
-d, --description <str>	Optional project description.

projects delete

tvault projects delete api -y

Flag	Description
-y, --yes	Skip the confirmation prompt.

projects use

tvault projects use api

Set the active project. tvault use <name> is the shorthand. No command-local flags.

projects share

tvault projects share tvault1exampleRecipient

Share the active project with a recipient public key (tvault1…), so they can decrypt it with their X25519 identity. No command-local flags.

projects unshare

tvault projects unshare tvault1exampleRecipient

Remove a recipient from the updated live vault. This rotates the project DEK and re-encrypts every current value and archived version. No command-local flags.

Scope of recipient removal

A recipient may have cached the old DEK, so re-wrapping alone would leave the live vault's existing ciphertext readable. unshare re-encrypts the updated live state under a fresh DEK. A pre-removal snapshot or previously exported, sealed, or decrypted artifact remains readable; rotate underlying credentials when retained data is a concern.

projects recipients

tvault projects recipients

List the recipients of the active project. Metadata only — no unlock required. No command-local flags.

use

tvault use api

Set the active project. Shorthand for tvault projects use. No command-local flags.

---

Run & environment

run

tvault run -- node server.js
tvault run -e .env.local -- ./start.sh
tvault run --no-vault -- env
tvault run --only DATABASE_URL,API_TOKEN -- pulumi up
tvault run --strict --only DATABASE_URL,API_TOKEN -- pulumi up
tvault run --group liftclub --env preview -- ./deploy.sh
tvault run --identity deploy --strict --only DIGITALOCEAN_TOKEN -- pulumi up

Run a command with the project's secrets injected into its environment. Use -- to separate tvault flags from the child command. Forwards SIGINT/SIGTERM to the child and propagates its exit code.

Flag	Description
-e, --env-file <path>	Also load variables from this dotenv file.
--no-vault	Do not inject vault secrets (use only --env-file / inherited env).
--only <k1,k2>	Inject only these secret keys (comma-separated allowlist).
--prefix <p>	Inject only secret keys with this prefix.
--redact	Replace literal injected secret values in child stdout/stderr with [REDACTED:KEY] (safety net; misses short, split, or transformed values).
--strict	Fail before starting the child when an explicit --only key is missing.
--identity <name>	Read shared project values with an X25519 identity instead of the vault passphrase. It also works with --group/--env when the identity has access to every participating project; cannot combine with --no-vault.
--group <name>	Resolve secrets through an environment group's inheritance chain.
--env <name>	Environment within the group (requires --group).

ssh

tvault ssh deploy@prod -- systemctl restart api
tvault ssh --only DATABASE_URL deploy@prod -- ./migrate
tvault ssh --ssh-arg=-p --ssh-arg=2222 deploy@prod -- hostname
tvault ssh --identity ci deploy@prod -- docker compose up

Run a command on a remote host with the project's secrets in that process's environment. Values are streamed over the SSH channel as a POSIX export script on stdin (sh -s); they are never written to a remote file and never appear on the ssh command line. The remote host needs a POSIX sh. Extra OpenSSH client flags go in repeatable --ssh-arg values. Forwards SIGINT/SIGTERM to ssh and propagates its exit code.

Flag	Description
--only <k1,k2>	Inject only these secret keys (comma-separated allowlist).
--prefix <p>	Inject only secret keys with this prefix.
--strict	Fail before starting ssh when an explicit --only key is missing.
--identity <name>	Read a shared project with an X25519 identity instead of the passphrase.
--group <name>	Resolve secrets through an environment group's inheritance chain.
--env <name>	Environment within the group (requires --group).
--ssh-arg <arg>	Extra argument passed to the ssh client before the destination (repeatable).

docker

tvault docker build --only NPM_TOKEN -- -t app .
tvault docker compose --only DATABASE_URL -- up
tvault docker run --only DATABASE_URL -- --rm alpine env
tvault docker init

Wrap the Docker CLI so vault secrets reach a build, compose stack, or container without putting values on the docker command line.

Subcommand	What it does
build	docker build --secret id=KEY,env=KEY per selected key (BuildKit tmpfs). Sets DOCKER_BUILDKIT=1.
compose	Injects keys into the compose process so ${KEY} interpolates.
run	docker run -e KEY (name only; Docker reads the value from the client env).
init	Print Dockerfile and compose snippets. Does not unlock the vault.

Persistent flags (all subcommands except init): --only, --prefix, --strict, --identity, --group, --env. Put TinyVault flags before --; everything after is passed to Docker. See Docker.

env

eval "$(tvault env)"
tvault env -f dotenv > .env
tvault env --only DATABASE_URL,MIGRATIONS_DATABASE_URL -f dotenv
tvault env --prefix CHALUPA_ -f dotenv
tvault env -p shared --identity laptop

Print the project's secrets as environment assignments. The default format is shell with export prefixes, ready to eval. Identity-based reads add an audit row; the direct passphrase-unlock path currently does not. There is no output-file flag — redirect stdout to write to a file.

Flag	Description
-f, --format <fmt>	shell, dotenv, json, yaml, k8s-secret, or pulumi-config (default shell).
-e, --export	Prefix shell output with export (default true).
--name <str>	Secret name (for k8s-secret).
--namespace <str>	Namespace (for k8s-secret; default default).
--stack <name>	Pulumi stack to target (pulumi-config format; optional).
--identity <name>	Read a shared project with an X25519 identity — no passphrase needed.
--only <k1,k2>	Emit only these keys; missing explicit keys fail closed.
--prefix <p>	Emit only keys with this prefix; combines with --only as a union.
--group <name>	Resolve secrets through an environment group's inheritance chain.
--env <name>	Environment within the group (requires --group).

env group

tvault env group create liftclub --env production=liftclub --env preview=liftclub-preview -d "LIFT Club"
tvault env group list
tvault env group show liftclub
tvault env group add staging --group liftclub --project liftclub-staging
tvault env group remove staging --group liftclub
tvault env group delete liftclub -y

Link multiple projects as named environments of the same application. Pure metadata — no new crypto, no copied values; deleting a group never touches a secret. A project belongs to at most one group unless --force is used on create. See Environment groups.

Subcommand	Flags
create <name>	-d, --description <str>; --env <name=project> (repeatable, required); --force.
list	—
show <name>	—
add <env>	--group <name> (required); -p, --project <name> (required).
remove <env>	--group <name> (required).
delete <name>	-y, --yes.

env diff

tvault env diff liftclub
tvault env diff liftclub --values
tvault env diff liftclub --keys-only --json

Compare key sets across all environments in a group. Default is metadata-only (no unlock). --values also reports same/different (needs unlock; values never printed). Exit codes: 0 no drift, 1 drift, 2 group not found, 3 locked (--values only).

Flag	Description
--values	Also compare values (same/different; never prints values).
--keys-only	Compare only key sets (fast, no decryption).

env promote

tvault env promote DATABASE_URL --group liftclub --from preview --to production
tvault env promote --all --group liftclub --from preview --to production --dry-run

Copy secret values from one environment to another. The source value is decrypted and re-encrypted into the target, creating a new version (prior value archived). Each promoted key is audited as secret.promote. Promotes always prompt unless --yes is passed.

Flag	Description
--group <name>	Group name (required).
--from <env>	Source environment (required).
--to <env>	Target environment (required).
<keys...>	Positional keys to promote (omit when using --all).
--all	Promote all keys that differ.
--dry-run	Show what would change without writing.
-y, --yes	Skip the confirmation prompt.

env inherit / pin / unpin / inherited

tvault env inherit --group liftclub --env preview --from production
tvault env pin API_TOKEN --group liftclub --env preview
tvault env unpin API_TOKEN --group liftclub --env preview
tvault env inherited --group liftclub --env preview

Inheritance is metadata-only: a child resolves missing keys from a base at read time. pin writes the resolved value into the child (breaking inheritance for that key only); unpin deletes it (restoring inheritance). All four take --group <name> and --env <child> (required).

env seal

tvault env seal --group liftclub --recipient tvault1ci… -o ci/migration.sealed
tvault env seal --group liftclub --keys DATABASE_URL,STRIPE_SECRET_KEY --recipient tvault1ci…

Seal all (or a subset of) environments into one .env.encrypted v2 blob keyed by environment name. Output is ciphertext only — values are never returned. In CI, decrypt with tvault decrypt-env --identity <id> --section <env> to extract one environment.

Flag	Description
--group <name>	Group name (required).
--recipient <tvault1…>	X25519 recipient (repeatable; required).
-o, --out <file>	Output file (default: stdout).
--keys <list>	Specific keys to include (comma-separated or repeatable).
--envs <list>	Specific environments to include (comma-separated or repeatable).

---

Import / export / sync

import

tvault import .env
tvault import --dir . --env production --dry-run
tvault import --file .env --file .env.local --overwrite
tvault import --interactive

Import secrets from dotenv files. An explicit file argument cannot be combined with --file.

Flag	Description
--dir <path>	Directory to scan (default .).
--env <name>	Environment name for the default dotenv chain, e.g. production.
--file <path>	Dotenv file to import, in order. Repeatable.
--overwrite	Overwrite existing secrets.
--dry-run	Show what would be imported without writing.
--interactive	Select and preview files before importing.

export

tvault export -f json -o secrets.json
tvault export -f k8s-secret --name app-secrets --namespace prod

Export the project's secrets. Prints plaintext — never commit the output.

Flag	Description
-f, --format <fmt>	dotenv, json, yaml, or k8s-secret (default dotenv).
-o, --output <file>	Write to a file instead of stdout.
--name <str>	Secret name (for k8s-secret).
--namespace <str>	Namespace (for k8s-secret; default default).

Plaintext output

tvault export writes decrypted values. Treat the output like the secrets themselves: keep it out of version control and off shared disks.

diff

tvault diff .env
tvault diff .env --values

Compare a dotenv file against the project. The default (key-level) diff needs no unlock. --values also compares values — each read is audited, but values are never printed.

Flag	Description
--values	Also compare values (audits each read; never prints them).

sync

tvault sync --path .env -d pull
tvault sync -d push --overwrite
tvault sync -d mirror

Reconcile a dotenv file with the project. Note: sync has no -p shorthand for project — use --project.

Flag	Description
--path <file>	Dotenv file path (default .env).
-d, --direction <dir>	pull, push, or mirror (default pull).
--overwrite	Allow overwriting existing keys (push/mirror).

---

Committable & shared secrets

These commands produce or consume the commit-safe .env.encrypted v2 format and other recipient-encrypted blobs.

encrypt-env

tvault encrypt-env -i .env -o .env.encrypted --recipient tvault1exampleRecipient
cat .env | tvault encrypt-env > .env.encrypted

Encrypt a dotenv file. With one or more --recipient, you get v2 output: commit-safe and not tied to your passphrase. Without --recipient, you get v1, encrypted under your passphrase.

Flag	Description
-i, --in <file>	Input file (default stdin).
-o, --out <file>	Output file (default: <in>.encrypted).
--recipient <tvault1…>	Recipient public key. Repeatable. Switches output to v2.

decrypt-env

tvault decrypt-env -i .env.encrypted -o .env --identity laptop

Decrypt a .env.encrypted file. The format is auto-detected: v1 uses your passphrase, v2 uses your identity.

Flag	Description
-i, --in <file>	Input file (default stdin).
-o, --out <file>	Output file (default stdout).
--identity <name>	Identity to unwrap v2 blobs.
--section <env>	Extract only one environment section from a multi-environment sealed blob (e.g. preview).

seal

tvault seal -r tvault1exampleRecipient -o secrets.sealed
tvault seal --key API_KEY --key DB_URL --format k8s --name app -o sealed.yaml

Seal selected secrets to one or more recipients. Requires an unlock. This is the inverse of open. Recipients default to .tvault-recipients.

Flag	Description
-r, --recipient <tvault1…>	Recipient public key. Repeatable. Defaults to .tvault-recipients.
--key <name>	Secret key to include. Repeatable (default: all).
-o, --out <file>	Output file (default stdout).
--format <fmt>	raw or k8s (default raw).
--name <str>	Kubernetes Secret name (required for --format k8s).
--namespace <str>	Kubernetes namespace (--format k8s).

open

tvault open -i secrets.sealed --identity laptop -o .env

Open a sealed (v2) blob with an identity. No vault unlock — only the identity.

Flag	Description
-i, --in <file>	Sealed input file (default stdin).
--identity <name>	Identity to use (default $TVAULT_IDENTITY, then default).
-o, --out <file>	Output file (default stdout).

git-filter

tvault git-filter install --recipient tvault1exampleRecipient
tvault git-filter track 'secrets/**'
tvault git-filter status
tvault git-filter checkout
tvault git-filter uninstall

Manage the git clean/smudge filter that transparently encrypts tracked files on commit and decrypts them on checkout.

Subcommand	Usage	Notes
install	git-filter install [--recipient …]	Wire the filter into the repo. --recipient is repeatable.
track <pattern>…	git-filter track 'secrets/**'	Add .gitattributes patterns to filter.
status	git-filter status	Show filter and recipient configuration.
checkout	git-filter checkout	Re-run the smudge filter over tracked files.
uninstall	git-filter uninstall	Remove the filter from the repo.

identity

tvault identity new laptop
tvault identity list
tvault identity export laptop

Manage X25519 identities (passphrase-independent keypairs at ~/.tvault/identities/<name>.key). The public half (tvault1…) is shareable; the private half (tvault-key1…) must never be committed.

Subcommand	Usage	Flags
new [name]	identity new [name]	name defaults to default
list	identity list	—
export [name]	identity export [name]	--force (allow printing off a TTY)

identity export prints a private key

tvault identity export prints the tvault-key1… private key. It is TTY-guarded — printing to a non-terminal requires --force. Never commit, log, or paste the private half.

---

Kubernetes

k8s render

# Author the sealed blob with `seal --format k8s`, then render it:
tvault seal --format k8s --name app -r tvault1exampleRecipient -o sealed.yaml
tvault k8s render -i sealed.yaml --identity laptop | kubectl apply -f -

Render a sealed blob into a Kubernetes Secret. Authoring is done with seal --format k8s; k8s render does the decryption side. No vault unlock — only the identity.

Flag	Description
-i, --in <file>	Sealed input file (default stdin).
--identity <name>	Identity to unwrap with.
-o, --out <file>	Output file (default stdout).

Rendered output is plaintext

k8s render emits a plaintext Secret manifest. Pipe it straight to kubectl apply — never commit it.

---

Versioning

history

tvault history API_KEY

Show the version history for a key. Metadata only — no unlock, no values. Aliases: versions, hist. No command-local flags.

rollback

tvault rollback API_KEY --to 3

Restore an earlier version. Non-destructive: it re-stores the old version as a new one, so version numbers stay monotonic and are never reused.

Flag	Description
--to <N>	Version to restore (required).

---

Agent & shell

agent

tvault agent start
tvault agent start --idle 30m
tvault agent start --require-token --token-file ~/.tvault/agent.token
tvault agent status
tvault agent stop

Run the local agent (Unix only). It unlocks the vault once and serves secret reads over a private 0600 unix socket, so the commands that route reads through it — get, env, run, ssh, docker, and tvault mcp — skip the prompt and Argon2id. It caches only the KEK and reopens the vault per request, so direct CLI access keeps working. agent start runs in the foreground: background it yourself (&, nohup), or let agent install register it as a per-user launchd/systemd service.

Subcommand	What it does	Flags
install	Install the agent as a per-user service (launchd on macOS, systemd on Linux).	--dry-run, --idle, --log-dir, --log-level, --no-load, --passphrase-file
logs	Show where the agent logs live, or clear them with --clear.	--clear, --log-dir
restart	Restart the installed agent service (picks up an upgraded binary).	—
start	Unlock the vault and serve secrets over a local socket (foreground).	--idle <dur> (default 15m; 0 = never), --require-token, --token-file <path>, --log-dir <path>, --log-level <level>
status	Show whether the agent is running.	—
stop	Stop the running agent (zeroing its KEK).	—
uninstall	Stop and remove the agent's service definition.	—

Capability tokens are privilege separation, not same-uid defense

--require-token gates an OS-confined (different-uid) delegate only. A malicious same-uid process can read the token file or dial the socket directly, so tokens are not a defense against it. For untrusted/CI/container delegation, use a scoped identity instead.

hook

tvault hook zsh   >> ~/.zshrc
tvault hook direnv

Print a shell snippet that defines tvault_load for loading a project's secrets via the agent. No command-local flags.

Argument	Values
<shell>	bash, zsh, fish, direnv

shell-init

eval "$(tvault shell-init zsh --project personal)"
eval "$(tvault shell-init bash -p personal --only GITHUB_TOKEN,OPENAI_API_KEY)"
tvault shell-init fish --project personal | source
eval "$(tvault shell-init zsh -p personal --allow-unlock --quiet)"

Print export assignments for one project, meant for eval at shell startup (~/.zshrc, ~/.bashrc, config.fish). Unlike hook/tvault_load, it never prompts: values come from a running agent, or — only with --allow-unlock — a non-interactive source (env, passphrase command, or passphrase file, never a TTY). When nothing is available it prints nothing, warns once on stderr (unless --quiet), and exits 0, so a locked vault never blocks shell startup. --project is required. See Keep the passphrase out of plaintext.

Argument	Values
<shell>	bash, zsh, fish

Flag	Description
--only <k1,k2>	Load only these keys.
--prefix <p>	Load only keys with this prefix.
--allow-unlock	Fall back to a non-interactive unlock when no agent is reachable.
-q, --quiet	Suppress the stderr notice when nothing is loaded.

---

CI/CD

ci init

tvault ci init --provider github-actions
tvault ci init --provider gitlab --mode identity --identity ci
tvault ci init --provider github-actions --output -

Scaffold a CI workflow that consumes the vault. --mode passphrase uses TVAULT_PASSPHRASE; --mode identity scaffolds a passphrase-free flow using TVAULT_IDENTITY_KEY.

Flag	Description
--provider <name>	github-actions or gitlab (required).
--mode <mode>	passphrase or identity (default passphrase).
--identity <name>	Identity to reference (default default).
--output <path>	Write here; - prints to stdout (default: the provider's conventional path).

---

Maintenance

key rotate

tvault key rotate

Re-encrypt the vault under a new passphrase. It rewraps the DEKs; the secret values themselves are untouched.

Invalidates old v1 encrypted files

A passphrase rotation invalidates any v1 .env.encrypted files made under the old passphrase. v2 (recipient-encrypted) files are unaffected because they are KEK-independent.

backup

tvault backup ./tvault-backup.db
tvault backup ./tvault-backup.db.gz
tvault backup --dir ~/Backups/tvault --keep 30 --immutable
tvault backup   # uses backup.dir / backup.keep / backup.immutable from config.yaml

Write a consistent, verified snapshot of the vault — taken inside a bbolt read transaction (Tx.WriteTo), never a raw file copy, so it's never a torn copy even if another tvault writes concurrently. Secret payloads and key material remain encrypted, while operational metadata (project/key names, audit log) remains readable. With [path], writes one snapshot there (gzip-compressed if it ends in .gz). Without a path, writes a rotated, timestamped, compressed snapshot into --dir/backup.dir and prunes the oldest beyond --keep/backup.keep. See Backups & recovery.

Flag	Description
--dir <path>	Directory for timestamped, rotated snapshots (default: backup.dir in config.yaml).
--keep <N>	Number of snapshots to keep in --dir (default: backup.keep, else 30).
--immutable	Mark snapshots immutable (macOS/BSD user flag) so rm cannot delete them; unsupported on Linux/Windows (warning printed, snapshot still written).

restore

tvault restore ./tvault-backup.db -y
tvault restore ./tvault-backup.db.gz

Restore the vault from a backup file (plain or gzip, auto-detected). The backup is staged and verified before anything about the current vault is touched; the current vault is saved first (into backup.dir when configured, else next to vault.db as vault.db.pre-restore-<time>); then the staged file is renamed atomically over vault.db.

Flag	Description
-y, --yes	Skip the confirmation prompt. Required with --json, because a prompt cannot be answered on a machine-readable stream.

unlock

tvault unlock

Unlock the vault for the session. No command-local flags.

lock

tvault lock

Lock the vault and clear cached keys. No command-local flags.

self-update

tvault self-update
tvault self-update --check
tvault self-update --version v0.11.1

Update the tvault binary in place: download the latest release for this OS/arch from the official GitHub releases, verify its SHA-256 checksum, and atomically replace the running binary. Alias: upgrade. The download source is fixed and cannot be overridden at runtime — a self-replacing binary must not let an attacker redirect it.

--check reports whether an update is available without installing. --version installs a specific release tag (to pin or downgrade). If you installed via Homebrew or a system package (apt/dnf/apk), update through that package manager instead so its bookkeeping stays correct.

Flag	Description
-c, --check	Only report whether an update is available; don't install.
--version <tag>	Install a specific release tag (e.g. v0.11.1) instead of the latest.

---

Audit

audit

tvault audit
tvault audit --limit 20
tvault audit --action secret.read
tvault audit --since 2026-01-01T00:00:00Z --json

List recent audit-log entries (newest first). Metadata only: actions, resource names, timestamps. Secret values are never stored in the log and never printed. Lock-free — works on a locked vault.

Flag	Description
--limit <N>	Maximum entries (default 100, max 1000).
--since <RFC3339>	Only entries at or after this timestamp.
--until <RFC3339>	Only entries at or before this timestamp.
--action <name>	Only this action (e.g. secret.read).
--resource-type <name>	Only this resource type (e.g. secret).

The same trail is available over MCP as vault_audit_log / vault_audit_log_since.

---

AI / MCP

TinyVault speaks MCP through the same binary. See the MCP overview and the tools reference.

mcp

tvault mcp
tvault mcp --connect unix://$HOME/.tvault/agent.sock

Start the MCP server over stdio. Loads ~/.tvault/mcp-policy.yaml and serves the agent-facing tools, resources, and prompts. Your MCP host usually launches this for you. If a local tvault agent is running, secret reads go through it and TVAULT_PASSPHRASE is not required; writes still need the passphrase. --connect auto (default) prefers a passphrase when set, otherwise the agent; unix://PATH pins the socket; none (or --no-agent) forces a passphrase unlock. Alias: mcp-server.

Flag	Description
--connect auto / none / unix://PATH	How to unlock: agent auto-detect, passphrase only, or an explicit agent socket.

MCP output redaction is a safety net, not a control

When policy enables redact_output, redaction replaces literal values longer than three characters and can be evaded by shortening or transforming a value (e.g. base64). It is a last line of defense, not access control. vault_get_secret deliberately returns plaintext, and vault_run_with_secrets can carry plaintext through arbitrary child output.

Internal commands

A few commands are hidden because they are wired up by other tools, not run by hand:

• git-clean / git-smudge — the clean/smudge endpoints invoked by git through git-filter install.

---

Help & docs

help

tvault help
tvault help workflow
tvault help safety --json

Long-form manual. Topics: workflow, safety, recipes, output, agent, troubleshooting, topics.

Flag	Description
--json	Emit the manual as JSON.

docs

tvault docs
tvault docs run
tvault docs -t mcp

Machine-readable docs for agents. Topics: agent, versioning, docker, run, mcp, self-update, interpolate, sync, encrypted-env, k8s, committable-secrets, safety, quickstart, audit, codemap.

Flag	Description
-t, --topic <name>	Print a specific topic (alias for the positional argument).

completion

tvault completion zsh > "${fpath[1]}/_tvault"

Generate a shell completion script.

Argument	Values
<shell>	bash, zsh, fish, powershell

---

See also

• Getting started — install, init, and your first secret.
• Run & env — inject secrets into processes.
• Backups & recovery — rotation, --immutable, safety snapshots, and scheduling.
• MCP tools — the agent-facing tool surface.
• Configuration — config file and environment variables.