init

README.md

@@ -0,0 +1,91 @@
+# pasx
+
+A full-screen terminal password generator. Random characters or passphrases,
+live entropy, clipboard copy. It generates passwords; it never stores them.
+
+Copying delegates to the platform's own clipboard tool — `wl-copy`, `xclip`,
+`xsel` or `pbcopy`, whichever is on PATH. A short-lived process cannot hold a
+Wayland or X11 selection open on its own; those tools daemonize, so the
+password is still there after `pasx` exits. The Nix package puts `wl-copy` on
+PATH for you.
+
+## Run
+
+```
+nix develop --command cargo run
+```
+
+The TUI needs at least a 40x14 terminal; below that it shows a "terminal too
+small" message instead of a broken layout.
+
+## Install
+
+```
+nix build
+./result/bin/pasx
+```
+
+Or add it to a profile: `nix profile install .`
+
+## Keys
+
+| Key | Action |
+|---|---|
+| Up / Down | select a setting |
+| Left / Right | change the selected setting |
+| Space, Enter | toggle the selected setting |
+| `r` | regenerate |
+| `c` | copy to clipboard |
+| Tab | switch between character and passphrase mode |
+| `q`, Esc, Ctrl-C | quit |
+
+## Command line
+
+```
+pasx --length 24 --no-symbols     # open the TUI pre-configured
+pasx gen -l 18                    # print one password and exit
+pasx gen -l 18 --copy             # ...and copy it
+pasx completions nu               # print a shell completion script
+```
+
+Flags: `--mode <charset|passphrase>`, `--length`, `--no-upper`, `--no-lower`,
+`--no-digits`, `--no-symbols`, `--exclude-ambiguous`, `--words`, `--separator`,
+`--capitalize`, `--add-number`.
+
+## Shell completions
+
+`pasx completions <shell>` prints a completion script for `nu`, `bash`, `zsh`,
+or `fish` to stdout; each is generated from the clap definition, so a new flag
+stays covered with no separate edit.
+
+The Nix package ships the Nushell script at `share/pasx/pasx.nu`. Source it
+from your config:
+
+```nu
+source ~/.nix-profile/share/pasx/pasx.nu
+```
+
+Without Nix, save the script wherever your shell loads completions from, e.g.:
+
+```
+pasx completions bash > ~/.local/share/bash-completion/completions/pasx
+pasx completions zsh > ~/.zfunc/_pasx
+pasx completions fish > ~/.config/fish/completions/pasx.fish
+pasx completions nu | save -f ~/.config/nushell/pasx.nu
+```
+
+## Development
+
+```
+nix develop
+cargo test
+cargo clippy --all-targets -- -D warnings
+```
+
+## License
+
+Dual-licensed under either of `LICENSE-MIT` or `LICENSE-APACHE`, at your
+option.
+
+The EFF wordlist bundled in `src/generator/wordlist.txt` is CC BY 3.0 US; see
+`LICENSES/eff-wordlist.md`.