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.

Canonical executable surface

Use the generated CLI command reference for the complete KeePass command tree and exact executable usage, flags, and displayed defaults. This page focuses on behavior, examples, output, and security.

Cobra lists but does not label required flags in --help. At execution time, KeePass item create and update require --item-path, --field, and --value-from-env.

Vault commands

Create a vault

Create a new .kdbx file for a vault alias. The command does not persist a runtime alias mapping; configure that separately before using item commands or workflow secrets. 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

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

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

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 command accepts the field value by environment-variable name rather than a direct value flag. This avoids placing the value in command arguments; the process environment and shell setup still require normal secret handling.

export DB_SECRET="s3cret-value"

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

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

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 a command for retrieving secret values. This removes that CLI output path but does not make unrelated logs or terminals safe.
Value-from-env pattern	Mutation commands accept secret values through environment variable names, not direct value flags. This avoids putting values in command arguments.
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. Configure access for item commands and workflow runs
export LOOM_KEEPASS_DB_LOCAL_PATH="$PWD/.loom/keepass/LOCAL.kdbx"
export LOOM_KEEPASS_DB_LOCAL_PASSWORD_ENV="KEEPASS_PASSWORD"

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

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

Expected output from step 4:

services/deploy  token

Save this local verification workflow as .loom/workflow.yml, then run loom check and loom run --local --workflow .loom/workflow.yml:

version: v1
stages: [ci]

check-secret:
  stage: ci
  target: linux
  secrets:
    DEPLOY_TOKEN:
      ref: keepass://local#services/deploy:token
  script:
    - test -r "$DEPLOY_TOKEN" && test -s "$DEPLOY_TOKEN"
    - echo "Secret file is readable and non-empty"

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.

Checkouts with the same Git origin path derive the same alias. Each environment still needs a database path and credentials mapped through LOOM_KEEPASS_DB_<KEY>_*. Override the derived alias with --vault-path when you need a name such as local or 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.