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