CLI reference: loom secrets keepass

Create, update, and inspect KeePass vaults and entries from the command line. These commands manage vault metadata and mutate entry fields — they never print secret values to stdout.

Command tree

loom secrets keepass
├── vault
│   ├── create    Create a .kdbx vault file
│   ├── update    Rotate vault credentials
│   └── list      List configured vault mappings
└── item
    ├── create    Create an entry field in a vault
    ├── update    Update an entry field value
    └── list      List item metadata (paths and field names)

Vault commands

Create a vault

Create a new .kdbx file and register it under a vault alias. Credentials come from environment variables you specify by name — never from direct flag values.

export KEEPASS_PASSWORD="my-master-password"

loom secrets keepass vault create \
  --password-from-env KEEPASS_PASSWORD

Flags:

Flag	Required	Default	Description
--vault-path	No	Git origin path (e.g. group/project/repo)	Vault alias override
--database-path	No	.loom/keepass/<alias>.kdbx	Where to write the .kdbx file
--password-from-env	No*	—	Env var name containing the master password
--keyfile-from-env	No*	—	Env var name containing the keyfile path
--force	No	false	Overwrite an existing vault file

*At least one credential source (--password-from-env or --keyfile-from-env) must be provided.

Output:

vault created: alias=group/project/repo path=.loom/keepass/GROUP_PROJECT_REPO.kdbx

Examples:

Create a vault with a custom alias and path:

export KEEPASS_PASSWORD="my-master-password"

loom secrets keepass vault create \
  --vault-path local \
  --database-path "$HOME/.config/loom/secrets/local.kdbx" \
  --password-from-env KEEPASS_PASSWORD

Create a vault with both password and keyfile:

export KEEPASS_PASSWORD="my-master-password"
export KEEPASS_KEYFILE="$HOME/.config/loom/secrets/local.key"

loom secrets keepass vault create \
  --password-from-env KEEPASS_PASSWORD \
  --keyfile-from-env KEEPASS_KEYFILE

Overwrite an existing vault:

loom secrets keepass vault create \
  --password-from-env KEEPASS_PASSWORD \
  --force

Update vault credentials

Rotate the master password and/or keyfile on an existing vault. Current credentials are loaded from the runtime alias mapping (LOOM_KEEPASS_DB_<ALIAS>_* environment variables); new credentials come from the flags.

export NEW_KEEPASS_PASSWORD="rotated-password"

loom secrets keepass vault update \
  --password-from-env NEW_KEEPASS_PASSWORD

Flags:

Flag	Required	Default	Description
--vault-path	No	Git origin path	Vault alias override
--password-from-env	No*	—	Env var name containing the new master password
--keyfile-from-env	No*	—	Env var name containing the new keyfile path

*At least one new credential source must be provided.

Output:

vault updated: alias=group/project/repo path=.loom/keepass/GROUP_PROJECT_REPO.kdbx

caution

After rotating credentials, update the LOOM_KEEPASS_DB_<KEY>_PASSWORD_ENV / _KEYFILE_ENV environment variables and the credential values they reference. Workflows using the old credentials will fail with SECRETS_PROVIDER_UNAVAILABLE.

List vaults

List configured vault mappings with alias, database path, and credential mode. Does not expose credential values.

loom secrets keepass vault list

Filter by a specific alias:

loom secrets keepass vault list --vault-path local

Flags:

Flag	Required	Default	Description
--vault-path	No	—	Filter results to a specific alias

Output:

alias=group/project/repo path=.loom/keepass/GROUP_PROJECT_REPO.kdbx credentials=password-env

When no vaults are configured:

no keepass vault mappings found

The credentials field shows which credential modes are active: password-env, keyfile-env, or both (password-env,keyfile-env). If neither is configured, the value is none.

Item commands

Create an item field

Create a new entry and field in a vault. The field value comes from an environment variable — never from a direct flag — to keep secrets out of shell history and ps output.

export DB_SECRET="s3cret-value"

loom secrets keepass item create \
  --item-path services/loom/deploy \
  --field password \
  --value-from-env DB_SECRET

Flags:

Flag	Required	Default	Description
--vault-path	No	Git origin path	Vault alias override
--item-path	Yes	—	Entry path in the vault (e.g. services/loom/deploy)
--field	Yes	—	Field name to set (e.g. password, token, username)
--value-from-env	Yes	—	Env var name that holds the field value

Output:

item field created: vault=group/project/repo item=services/loom/deploy field=password

Update an item field

Update the value of an existing field. Same flag surface as create.

export DB_SECRET="new-rotated-value"

loom secrets keepass item update \
  --item-path services/loom/deploy \
  --field password \
  --value-from-env DB_SECRET

Output:

item field updated: vault=group/project/repo item=services/loom/deploy field=password

List items

List entry paths and field names in a vault. Values are never printed.

loom secrets keepass item list

Filter by entry path prefix:

loom secrets keepass item list --item-prefix services/loom

Flags:

Flag	Required	Default	Description
--vault-path	No	Git origin path	Vault alias override
--item-prefix	No	—	Filter results by item path prefix

Output:

services/loom/deploy	password,token
services/loom/db	username,password

When no items match:

no keepass items found

Security design

The CLI enforces three security invariants:

Invariant	Implementation
No read/show commands	The CLI intentionally omits any command that prints secret values to stdout. This prevents leaks in shell history, logs, and shared terminals.
Value-from-env pattern	All mutation commands accept secret values through environment variable names, not direct flag arguments. This keeps values out of ps output and shell history.
Metadata-only output	All output is limited to alias, path, field name, and credential mode metadata.

End-to-end example

Create a vault, add a secret, verify, then reference it in a workflow:

export KEEPASS_PASSWORD="vault-master-pw"
export DEPLOY_TOKEN="ghp_abc123"

# 1. Create the vault
loom secrets keepass vault create \
  --vault-path local \
  --password-from-env KEEPASS_PASSWORD

# 2. Add a secret entry
loom secrets keepass item create \
  --vault-path local \
  --item-path services/deploy \
  --field token \
  --value-from-env DEPLOY_TOKEN

# 3. Verify the entry exists
loom secrets keepass item list --vault-path local

Expected output from step 3:

services/deploy	token

Then reference the secret in your workflow YAML:

deploy:
  stage: ci
  target: linux
  secrets:
    DEPLOY_TOKEN:
      ref: keepass://local#services/deploy:token
  script:
    - curl -H "Authorization: Bearer $(cat $DEPLOY_TOKEN)" https://api.example.com/deploy

Troubleshooting

Symptom	Likely cause	Fix
value source env var is unset	The env var named in --value-from-env is not exported	Run export VAR_NAME="value" before the command
keepass database is unavailable or credentials are invalid	Wrong password, missing keyfile, or corrupt .kdbx	Verify credential env vars and database file integrity
no keepass vault mappings found	No LOOM_KEEPASS_DB_* env vars are set	Set up alias mapping per Install and setup
missing keepass path config	LOOM_KEEPASS_DB_<KEY>_PATH is unset or empty	Export the path variable with the correct alias key
allowlisted env var is unset	The env var named by _PASSWORD_ENV or _KEYFILE_ENV does not exist	Export the credential variable that the pointer references

Default vault path behavior

When --vault-path is omitted, the CLI derives the alias from the current Git remote origin URL. For a repo at gitlab.com/group/project/repo, the default vault path is group/project/repo and the alias key becomes GROUP_PROJECT_REPO.

This means teams sharing a repository automatically get a consistent alias without explicit configuration. Override with --vault-path when you need a custom alias (e.g. local, staging).

Related pages

• KeePass provider overview — URI format, resolution model, and error reference.
• KeePass install and setup — First-time environment configuration.
• KeePass in workflows — Injection modes and workflow patterns.
• Secrets overview — Cross-provider secrets system documentation.