README.md

 1# keycask
 2
 3Command-line password manager. One passphrase-encrypted vault file.
 4Swift, runs on macOS, Linux, and Windows.
 5
 6## install
 7
 8```sh
 9swift build -c release
10cp .build/release/keycask ~/.local/bin/
11```
12
13## use
14
15```sh
16keycask init
17keycask add github -u cmc --url https://github.com --tag dev --generate
18keycask add mail --words 6
19keycask add bank                     # prompts for the password
20keycask show github                  # password masked
21keycask show github --reveal
22keycask show github --field password # raw value, for scripts
23keycask clip github                  # clipboard, clears after 45s
24keycask ls --tag dev
25keycask find example
26keycask edit github --tag work --untag dev
27keycask rm github --yes
28keycask generate --words 5 --copy
29```
30
31Every read command takes `--json`. Passwords are masked unless `--reveal`.
32
33Names are labels and may repeat. Every command that takes a name also
34takes the entry's 8-character id, which `ls` and `add` print. An
35ambiguous name lists the candidates.
36
37## files
38
39| what | default | override |
40|---|---|---|
41| vault | `$XDG_DATA_HOME/keycask/vault.kc`, else `~/.local/share/keycask/vault.kc` (`%LOCALAPPDATA%\keycask\vault.kc` on Windows) | `KEYCASK_VAULT`, `--vault` |
42| passphrase | prompted | `KEYCASK_PASSPHRASE` |
43
44The vault is a JSON envelope: PBKDF2-HMAC-SHA256 (600000 rounds) over
45the passphrase, ChaCha20-Poly1305 over the entries. Writes are atomic.
46
47## exit codes
48
490 ok, 1 failure, 2 usage, 3 not found, 4 cannot decrypt, 5 ambiguous name.
50
51## develop
52
53```sh
54swift build
55swift test
56swift format lint --strict --recursive Sources Tests
57```
58
59Design: `docs/superpowers/specs/2026-09-17-keycask-design.md`.