Metadata-Version: 2.4
Name: kpass-cli
Version: 0.2.0
Summary: A pass-like CLI for KeePass KDBX databases
License: MIT
Keywords: keepass,kdbx,cli,password-store,pass
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pykeepass>=4.1.1.post1

# kpass

`kpass` is a CLI for KeePass KDBX databases, similar to [pass](https://www.passwordstore.org/).

It uses [pykeepass](https://pypi.org/project/pykeepass/) under the hood.

## Usage

```text
kpass [options] [path | command]
```

## Commands

- `kpass` — list the database tree
- `kpass <group/subgroup>` — list a subtree
- `kpass <record>` — show the main fields for a record
- `kpass show <record>` — show a record; use `-u`, `-p`, `-e`, `-l`, `-n`, or `-o` for one field
- `kpass find <terms...>` — search by name or path
- `kpass insert <path> ...` — add or update a record
- `kpass generate <path> ...` — add or update a record with a generated password; use `--quiet` to save without printing it
- `kpass edit <record> ...` — edit one field in `$EDITOR`
- `kpass ls <group>` — list a group subtree
- `kpass cp <source> <destination>` — copy a record or group
- `kpass mv <source> <destination>` — move a record or group
- `kpass rm <target>` — move to the Recycle Bin; use `-f` to delete permanently
- `kpass init [path]` — create a new vault
- `kpass vault ...` — change vault password or keyfile
- `kpass completion <bash|zsh|fish>` — print shell completions

## Common flags

- `--db` — database path
- `--db-password` — database password
- `--db-password-file` — read password from file
- `--db-keyfile` — keyfile for unlocking the database
- `--non-interactive` — never prompt or launch an editor; fail when required input is missing
- `--all` — show all content
- `--clip` — copy exactly one selected field to the local GUI clipboard
- `--xml` — output raw KeePass XML
- `--version` — show the version number

Insert and generate accept the following field values:

- `-u, --username`
- `-e, --email`
- `-l, --url`
- `-n, --notes`
- `--otp`

`insert` also accepts `-p, --password` to read a password from stdin or prompt, and `-o` as a short form of `--otp`. `generate` accepts `-L, --length` (default 32) and `--quiet`, but no password flag or short `-o`.

Environment variables:

- `KPASS_DB`
- `KPASS_PASSWORD`
- `KPASS_PASSWORD_FILE`
- `KPASS_KEYFILE`

## Unattended use

Provision vault access in the command process, then use `--non-interactive` before the command:

```sh
export KPASS_DB="/absolute/path/to/vault.kdbx"
export KPASS_PASSWORD_FILE="/absolute/path/to/vault-password"
kpass --non-interactive find example.com
kpass --non-interactive generate "services/new-entry" -L 32 --quiet
```

Use a dedicated agent vault and restrict password-file/keyfile permissions. A keyfile-only vault needs `KPASS_KEYFILE` but no password; vaults protected by both factors need both. When opening an existing vault interactively with only a keyfile configured, kpass first tries the keyfile alone and prompts once for a password if authentication fails. It does not fall back to prompting for non-interactive runs, explicitly supplied passwords, or non-authentication errors. Do not embed real secrets in command arguments, shell history, source control, or chat. Default entry views, `--all`, `--xml`, and generation without `--quiet` can expose secrets in captured output. Clipboard access requires Tkinter and a working GUI.

`insert -p` and `vault --set-password` read only the first line from non-terminal stdin, preserving surrounding whitespace and removing only its line terminator. For entry passwords, a blank line explicitly supplies an empty password; EOF supplies no password. Password files follow the same first-line rule, but an actually empty file is an error. `vault --set-password` rejects empty passwords from stdin, an explicit argument, or a prompt without modifying the vault; use `vault --clear-password` to remove password protection deliberately. Whitespace-only passwords remain valid literal passwords. In non-interactive mode missing input fails instead of prompting, and `edit` fails instead of opening an editor.

Explicit `init PATH` overrides `KPASS_DB`; if both `--db` and `PATH` are given, they must identify the same database. Extensionless init paths receive `.kdbx`. Existing databases are never overwritten.

OTP reads and edits prefer a populated standard OTP value, then the first populated supported `TOTP Seed` custom property. Editing a custom seed preserves its protection flag.

`insert` updates supplied fields; `generate` replaces an existing password. Both can create a missing database. Verify paths, back up before writes, and serialize writes to the same vault. Vault credential changes require updating the external unlock configuration.

## Links

- [pass](https://www.passwordstore.org/)
- [KeePass](https://keepass.info/)
- [pykeepass](https://pypi.org/project/pykeepass/)
