Keep the vault locked. Open a short session when you need it.

Create the local encrypted vault.

Kimen stores its default vault at ~/.config/kimen/vault.kv. Initialize it once:

kimen vault init

You choose a passphrase interactively. Kimen needs that passphrase to decrypt the vault for later commands.

Inspect the selected path or vault metadata without printing secret values:

kimen vault path
kimen vault info

vault info opens the vault and therefore asks for the passphrase unless a session or another unlock method is active.

Store and maintain secret values.

Use the hidden interactive prompt for ordinary entry:

kimen secret set app.dev.database_url
kimen secret set app.dev.api_key

Setting an existing name replaces its value. List names without printing values:

kimen secret list

Rename a key when the project contract changes, or remove one which is no longer referenced:

kimen secret mv app.dev.api_key app.dev.payments_api_key
kimen secret rm app.dev.old_key

Automation can pass a value on standard input:

printf '%s' "$VALUE" | kimen secret set app.dev.api_key --stdin

The shell variable already contains the plaintext value, so this is only appropriate when the surrounding automation protects it.

Expect a passphrase prompt for every invocation.

Without an active session, each command which opens the vault asks for its passphrase:

kimen doctor --profile dev
# Passphrase:

kimen run --profile dev -- ./app
# Passphrase:

This is the secure default. The decrypted material exists only while that Kimen invocation is resolving or projecting values.

Use a session for a bounded work period.

If you will run the application repeatedly, open a short session once:

kimen session start --ttl 30m
# Passphrase:

kimen session status
kimen run --profile dev -- ./app
kimen run --profile dev -- ./test-integration
kimen session lock

The TTL accepts seconds or a suffix such as 30m, 8h or 7d. An expired session is removed the next time Kimen reads it.

kimen session stop also ends the session. lock states the intent more clearly and is preferable in documentation and scripts.

A session is bound to the vault used when it starts. It does not unlock a different vault selected later.

Separate personal and work vaults when useful.

Select a vault for one command:

kimen vault init --vault ~/.config/kimen/work.kv
kimen secret list --vault ~/.config/kimen/work.kv

Or select it for the current shell:

export KIMEN_VAULT="$HOME/.config/kimen/work.kv"
kimen vault path

A command-line --vault selection is explicit. KIMEN_VAULT is convenient when every command in a shell should use the same vault.

You can also set KIMEN_SESSION to choose a non-default session file. Keep it outside the project and protect it with the same care as the default session.

Change the vault passphrase with a backup.

Run a preflight first. Kimen opens the existing vault and validates the new passphrase without changing the file:

kimen vault rekey --dry-run

Then rekey and place the encrypted backup in a chosen directory:

kimen vault rekey --backup-dir "$HOME/.config/kimen/backups"

Without --backup-dir, Kimen writes the backup beside the vault. --no-backup disables the backup, but that removes the easiest recovery path and should be a deliberate choice. A successful rekey removes the active session because its old passphrase is no longer valid.

Non-interactive unlock is an integration choice.

--passphrase-cmd lets Kimen obtain the vault passphrase from another program:

kimen session start --ttl 15m \
  --passphrase-cmd "$HOME/bin/read-kimen-passphrase"

The command must print only the passphrase to standard output. The helper becomes part of the security boundary. A wrapper which contains the passphrase in plaintext is not an improvement.

The same unlock flag can supply the old passphrase during rekeying. The new passphrase can come from the interactive prompt, KIMEN_NEW_PASSPHRASE, --new-passphrase-env NAME or --new-passphrase-stdin.

KIMEN_PASSPHRASE and passphrase input on standard input are also supported for automation, but environment variables and pipeline construction can expose values in places an interactive prompt does not. Prefer a narrowly authorized credential helper when automation is necessary.

Why use this instead of 1Password?

Kimen's vault is local, open source, account-free and usable offline. That is useful for an individual developer who wants runtime projection without adopting a hosted team vault.

1Password is usually stronger when credentials must be centrally shared, recovered, revoked and administered across a team. Kimen does not currently provide organization sync or central access management. Choose based on who must own the values, not only on command syntax.