wiki pages

Signed-off-by: Kamal Tufekcic <kamal@lo.sh>

CLI.md

@@ -0,0 +1,127 @@
+# CLI
+
+Native command-line interface for post-quantum cryptographic operations. Wraps the core Rust library directly — no FFI overhead, no runtime dependencies.
+
+## Install
+
+```bash
+cargo install soliton-cli
+```
+
+The binary is named `soliton`.
+
+## Commands
+
+### `soliton keygen`
+
+Generate an identity keypair (X-Wing + Ed25519 + ML-DSA-65).
+
+```bash
+soliton keygen                  # Writes identity.pk, identity.sk to current dir
+soliton keygen -o keys/         # Writes to keys/ directory
+```
+
+Outputs the SHA3-256 fingerprint to stderr. Secret key file is created with mode `0600`.
+
+### `soliton fingerprint <pk>`
+
+Print the SHA3-256 fingerprint of a public key file.
+
+```bash
+soliton fingerprint identity.pk
+```
+
+### `soliton sign <sk> [file]`
+
+Hybrid sign a file (Ed25519 + ML-DSA-65). Reads stdin if no file is given.
+
+```bash
+soliton sign identity.sk message.txt              # Writes message.txt.sig
+soliton sign identity.sk message.txt -o custom.sig # Custom output path
+echo "hello" | soliton sign identity.sk            # Sign from stdin, sig to stdout
+```
+
+### `soliton verify <pk> <file>`
+
+Verify a hybrid signature. Exits 0 on success, 1 on failure.
+
+```bash
+soliton verify identity.pk message.txt              # Reads message.txt.sig
+soliton verify identity.pk message.txt -s custom.sig # Custom sig path
+```
+
+### `soliton xwing-keygen`
+
+Generate an X-Wing keypair (for signed pre-keys or one-time pre-keys).
+
+```bash
+soliton xwing-keygen              # Writes xwing.pk, xwing.sk
+soliton xwing-keygen -o keys/
+```
+
+### `soliton sign-prekey <sk> <spk_pub>`
+
+Sign a pre-key with an identity key.
+
+```bash
+soliton sign-prekey identity.sk xwing.pk            # Writes spk.sig
+soliton sign-prekey identity.sk xwing.pk -o out.sig
+```
+
+### `soliton phrase <pk_a> <pk_b>`
+
+Generate a verification phrase from two public keys (6 EFF diceware words).
+
+```bash
+soliton phrase alice.pk bob.pk
+# Output: "correct horse battery staple donor anxiety"
+```
+
+### `soliton encrypt`
+
+Encrypt a file or stdin with streaming AEAD (XChaCha20-Poly1305, 1 MiB chunks).
+
+```bash
+# With a key file (32 bytes)
+soliton encrypt --key secret.key < plaintext > encrypted
+
+# With a passphrase (Argon2id key derivation)
+soliton encrypt --derive < plaintext > encrypted
+# Prints salt to stderr — save it for decryption
+
+# With a passphrase and explicit salt
+soliton encrypt --derive --salt <hex> -o out.enc plaintext.txt
+```
+
+### `soliton decrypt`
+
+Decrypt a streaming AEAD file. Detects truncation (missing final chunk).
+
+```bash
+soliton decrypt --key secret.key < encrypted > plaintext
+soliton decrypt --derive --salt <hex> -o plaintext.txt encrypted.enc
+```
+
+### `soliton argon2id`
+
+Derive key material from a passphrase via Argon2id. Generates a random salt and prints it to stderr.
+
+```bash
+soliton argon2id                                    # Defaults: 64 MiB, 3 passes, 4 lanes, 32 B
+soliton argon2id -m 19456 -t 2 -p 1 -l 64          # OWASP minimum, 64-byte output
+```
+
+### `soliton version`
+
+Print the library version.
+
+## WASM Alternative
+
+For environments without a Rust toolchain, the WASM package includes a Node-based CLI with the same commands:
+
+```bash
+bunx soliton-wasm keygen
+bunx soliton-wasm sign identity.sk message.txt
+```
+
+See [WASM](WASM) for details. The native CLI is significantly faster.