# keepassxc-proxy-getpw

A CLI tool to get passwords from a running KeePassXC instance via its browser integration protocol.

## Installation

```sh
cargo install keepassxc-proxy-getpw
```

## Usage

```sh
# Get password for a URL
keepassxc-proxy-getpw https://github.com  # schema is required

# Get username instead
keepassxc-proxy-getpw -u https://github.com

# Use in scripts (non-interactive, fail immediately if locked)
keepassxc-proxy-getpw --no-wait-unlock https://github.com
```

### Options

```
Usage: keepassxc-proxy-getpw [OPTIONS] <URL>

Arguments:
  <URL>  URL or search term to get credentials for

Options:
  -u, --username                 Print username instead of password
  -f, --filter <FILTER>          Filter entries (field=value for exact match, field~value for contains). Can be specified multiple times. Fields: name, login, uuid, group
      --no-wait-unlock           Do not wait for database unlock and fail immediately if database is locked
  -a, --association-file <PATH>  Path to association file (default: ~/.config/keepassxc-proxy-getpw/association.json)
      --new-association          Force creation of a new association (will prompt in `KeePassXC`)
      --socket <PATH>            Custom socket path for `KeePassXC` proxy
  -h, --help                     Print help
  -V, --version                  Print version
```

## First Run

On first run, KeePassXC will prompt you to approve the association. The association is saved to `~/.config/keepassxc-proxy-getpw/association.json`.

## Requirements

- KeePassXC with Browser Integration enabled (Settings -> Browser Integration)
- No need to enable specific browsers; the integration being enabled is sufficient

## Filtering

KeePassXC always requires the URL to be supplied in order to return entries. However, if you have multiple entries, this program will only display the first in whichever arbitrary order KeePassXC returns them.

This program can filter the entries further. The `--filter` flag supports `=` for a full match or `~` for a partial match. For example, if you know your entry is named `my entry`:
```sh
keepassxc-proxy-getpw https://example.com --filter name="my entry"
```

Example if your entry merely includes `my entry` in the `name` field:
```sh
keepassxc-proxy-getpw https://example.com --filter name~"my entry"
```

## Examples

```sh
# Git credential helper
git config --global credential.helper '!keepassxc-proxy-getpw --no-wait-unlock "https://$(echo $1 | cut -d/ -f3)"'

# Copy password to clipboard (X11)
keepassxc-proxy-getpw https://github.com | xclip -selection clipboard

# Copy password to clipboard (wayland)
keepassxc-proxy-getpw https://github.com | wl-copy

# Use in a script
PASSWORD=$(keepassxc-proxy-getpw https://example.com)
```

## Security Note

The association file contains a key that grants access to any password with a matching URL. Store it securely.

## License

MIT
