LocalVault CLI Reference

Secrets

Plaintext output requires a terminal (v1.9.0)

get, env, and show --reveal print plaintext freely when stdout is an interactive terminal. When stdout is captured — a pipe, a command substitution, or an AI agent's shell — a human is asked to confirm on /dev/tty:

localvault get API_TOKEN            # terminal: prints
localvault get API_TOKEN | pbcopy   # pipe: "Print plaintext value of 'API_TOKEN'? [y/N]"

An agent's shell has no /dev/tty to answer on, so it is refused and pointed at process-scoped injection. There is no flag or environment variable to bypass the gate; scripts and CI use localvault exec instead:

localvault exec --map API_TOKEN=API_TOKEN -- your-command

Vault management

Login

Identity keys

The keys namespace manages your X25519 keypair. localvault login auto-generates and publishes for you, so you only need these commands when rotating, inspecting, or recovering your identity.

Cloud sync

localvault sync uses per-vault .sync_state files to track what was last synced. If a vault exists on both sides with no baseline yet but the secrets are byte-identical (e.g. it was pushed before sync tracking existed), it records a baseline automatically — action adopt, reason "in sync — recording baseline" — and moves no data. CONFLICT is reserved for genuinely diverged state: both sides changed since the last sync, or both exist with no baseline and the secrets differ. On a conflict it prints how to resolve (keep local or keep remote) and never silently overwrites either side. The summary line can include a N baselined count for adopted vaults.

Team sharing

The leading @ in a handle already signals a person operation, so add/remove/verify are top-level commands. The team namespace holds the vault-level operations (init, list, rotate).

The aliases localvault team add @HANDLE, localvault team remove @HANDLE, and localvault team verify @HANDLE still work for backward compatibility but the top-level forms are preferred.

Legacy direct sharing (pre-v1.2)

These pre-v1.2 commands still work as a fallback when a vault isn't a team vault. For active team vaults, prefer add / remove above.

MCP (AI tool integration)

Global options

Dot-notation for team vaults

When you have many projects in one vault, prefix keys with project.key:

printf '%s' "$PLATEPOSE_DATABASE_URL" | localvault set platepose.DATABASE_URL --stdin -v intellectaco
printf '%s' "$INVENTLIST_STRIPE_KEY" | localvault set inventlist.STRIPE_KEY --stdin -v intellectaco
printf '%s' "$PLATEPOSE_SECRET_KEY_BASE" | localvault set platepose.SECRET_KEY_BASE --stdin -v intellectaco

# Show one project only
localvault show -p platepose -v intellectaco

# Inject one project's secrets into a command
localvault exec -p platepose -v intellectaco -- rails server

When exporting or injecting a whole vault, nested keys become shell-safe env vars:

AWS_IAM.access_key_id
# → AWS_IAM__access_key_id

Use the env DSL to scope and rename injected values:

localvault env --only AWS_IAM.*
localvault exec --only AWS_IAM.*,AWS_SES.* --except AWS_SES.smtp_password -- your-script
localvault exec --profile aws -- aws sts get-caller-identity
localvault env --map AWS_IAM.access_key_id=AWS_ACCESS_KEY_ID

Selectors are exact keys (OPENAI_API_KEY) or one-level namespaces (AWS_IAM.*). The aws profile maps AWS_IAM.access_key_id, AWS_IAM.secret_access_key, and AWS_IAM.session_token to the canonical AWS environment names.

Prefer printf '%s' "$SECRET" | localvault set KEY --stdin for new writes. Positional values may be visible in process lists and shell history.

Dot-notation for vault name

Named vault as a positional argument (sync commands) vs global flag (secrets commands):

# Secrets commands use --vault / -v flag
localvault show -v production
printf '%s' "$SECRET" | localvault set KEY --stdin -v staging

# Sync commands use a positional argument
localvault sync push production
localvault sync pull staging

Environment variables