Organizing Secrets in LocalVault

LocalVault supports two ways to organize secrets depending on how complex your setup is.

Flat keys with --group (simple projects)

For a single project or personal use, just store secrets as plain keys:

printf '%s' "$DATABASE_URL" | localvault set DATABASE_URL --stdin
printf '%s' "$REDIS_URL" | localvault set REDIS_URL --stdin
printf '%s' "$STRIPE_KEY" | localvault set STRIPE_KEY --stdin
printf '%s' "$STRIPE_SECRET" | localvault set STRIPE_SECRET --stdin

Run localvault show --group and LocalVault automatically groups them by their prefix:

Vault: default  (4 secrets)

  STRIPE  (2)
  ╭──────────────────┬────────────╮
  │ STRIPE_KEY       │ ••••• 123  │
  │ STRIPE_SECRET    │ ••••• xyz  │
  ╰──────────────────┴────────────╯

  ungrouped
  ╭──────────────────┬────────────╮
  │ DATABASE_URL     │ ••••• app  │
  │ REDIS_URL        │ ••••• st   │
  ╰──────────────────┴────────────╯

localvault exec -- rails s injects all keys as-is.

Best for: personal machines, single-project vaults.

Dot-notation (team vaults with multiple projects)

For a team vault that holds secrets for several projects, use dot-notation:

printf '%s' "$PLATEPOSE_SECRET_KEY_BASE" | localvault set platepose.SECRET_KEY_BASE --stdin -v intellectaco
printf '%s' "$PLATEPOSE_RAILS_MASTER_KEY" | localvault set platepose.RAILS_MASTER_KEY --stdin -v intellectaco
printf '%s' "$PLATEPOSE_DATABASE_URL" | localvault set platepose.DATABASE_URL --stdin -v intellectaco

printf '%s' "$INVENTLIST_SECRET_KEY_BASE" | localvault set inventlist.SECRET_KEY_BASE --stdin -v intellectaco
printf '%s' "$INVENTLIST_DATABASE_URL" | localvault set inventlist.DATABASE_URL --stdin -v intellectaco

localvault show -v intellectaco renders each project as its own group:

Vault: intellectaco  (5 secrets)

  platepose  (3)
  ╭──────────────────────┬────────────╮
  │ DATABASE_URL         │ ••••• 2aa  │
  │ RAILS_MASTER_KEY     │ ••••• f42  │
  │ SECRET_KEY_BASE      │ ••••• 123  │
  ╰──────────────────────┴────────────╯

  inventlist  (2)
  ╭──────────────────────┬────────────╮
  │ DATABASE_URL         │ ••••• 1aa  │
  │ SECRET_KEY_BASE      │ ••••• 789  │
  ╰──────────────────────┴────────────╯

Scoped commands

View or inject only one project at a time:

# Show only platepose secrets
localvault show -v intellectaco --project platepose

# Start platepose app with its secrets (no other project's keys leak in)
localvault exec --project platepose -v intellectaco -- rails s

# Export as shell vars for a specific project
eval $(localvault env --project platepose -v intellectaco)

When no --project is given and you run env/exec, nested secrets are exported with a GROUP__KEY prefix to avoid collisions:

# PLATEPOSE__DATABASE_URL=postgres://...
# INVENTLIST__DATABASE_URL=postgres://...
eval $(localvault env -v intellectaco)

Sharing a team vault

# Share all projects at once with a team member
localvault share intellectaco --with @bob

# Or share with everyone on a team
localvault share intellectaco --with team:intellectaco

The recipient runs localvault receive — they get the full vault including all project groups.

Bulk import

Instead of setting keys one by one, import from an existing file:

# From a .env file
localvault import .env -v intellectaco --project platepose

# From JSON
localvault import secrets.json -v intellectaco --project platepose

# From YAML
localvault import secrets.yml -v intellectaco --project platepose

# Nested JSON imports structure directly
localvault import all-secrets.json -v intellectaco

Supported formats:

.env — KEY=value lines, comments and blanks ignored:

SECRET_KEY_BASE=abc123
DATABASE_URL=postgres://...
# this is ignored

.json — flat or nested:

{ "SECRET_KEY_BASE": "abc", "DATABASE_URL": "postgres://..." }

{ "platepose": { "SECRET_KEY_BASE": "abc" }, "inventlist": { "API_KEY": "xyz" } }

.yml / .yaml:

SECRET_KEY_BASE: abc123
DATABASE_URL: postgres://...

Moving secrets around

# Rename a key
localvault rename OLD_KEY NEW_KEY -v intellectaco

# Copy a key to another vault (great for promoting staging → production)
localvault copy platepose.DATABASE_URL --to production -v intellectaco

# Delete one key
localvault delete platepose.SECRET_KEY_BASE -v intellectaco

# Delete an entire project group
localvault delete platepose -v intellectaco

Switching vaults

localvault switch              # show current vault + all available
localvault switch intellectaco # make intellectaco the default
localvault switch default      # switch back

Quick reference