@pqc-sdk/cli

CLI for @pqc-sdk/core: post-quantum projects in one command.

# Initialize a project: config + development keys + working example
npx @pqc-sdk/cli init

# Generate keys serialized as base64url
npx @pqc-sdk/cli keygen --algorithm ml-dsa-65 --out keys/

# Heuristically detect pre-quantum crypto (RSA/ECDSA/ECDH) and what to migrate to PQC
npx @pqc-sdk/cli audit

# Encrypt a file for the holder of an ML-KEM-768 key pair…
npx @pqc-sdk/cli encrypt will.pdf --key keys/alice.public.pqc

# …and decrypt it with the matching secret key
npx @pqc-sdk/cli decrypt will.pdf.enc --key keys/alice.secret.pqc --out will.pdf

encrypt / decrypt

encrypt seals a file into a self-contained envelope (ML-KEM-768 key encapsulation + AES-256-GCM, the same format as pqc.encrypt in @pqc-sdk/core — the two interoperate in both directions). decrypt opens it with the matching secret key and refuses corrupted or mismatched inputs instead of writing garbage.

pqc keygen --name alice                                  # keys/alice.{public,secret}.pqc
pqc encrypt report.pdf --key keys/alice.public.pqc       # report.pdf.enc
pqc decrypt report.pdf.enc --key keys/alice.secret.pqc   # report.pdf (0600)

Worth knowing:

• Output defaults: encrypt writes <input>.enc; decrypt strips the .enc (or appends .dec). Neither overwrites an existing file unless you pass --force.

• Decrypted plaintext is written readable only by you (mode 0600), and the CLI warns — without refusing — when a secret key file is readable by other users (fix with chmod 600 <file>).

• Files at or below 8 MiB are loaded fully into memory; larger files stream automatically (bounded memory regardless of size), up to a 1 TiB operational ceiling. No flag needed — the CLI picks the right path from the input size for encrypt, and from the ciphertext's own envelope header for decrypt.

• That 1 TiB ceiling is an operational guard against accidental inputs (pointing the CLI at a mounted block device, say) — not a cryptographic limit. The streaming envelope has no practical size bound of its own. Raise or lower it with --max-size on encrypt/decrypt:

  pqc encrypt archive.tar --key keys/alice.public.pqc --max-size 4TiB

  Accepts a byte count or a binary-unit size (2TiB, 500GiB, 64MiB). When --max-size actually admits a file the 1 TiB default would have refused, the CLI says so explicitly rather than proceeding quietly.

• Expected failures (missing file, wrong key, tampered envelope) print a one-line error on stderr and exit with code 1 — CI- and script-friendly.

audit is a heuristic, non-exhaustive regex scan of your dependencies and source — a starting point for a migration review, not a substitute for one, and not evidence that a codebase is free of pre-quantum crypto. It matches known package names and call patterns, so it will miss crypto reached through wrappers, dynamic imports, transitive dependencies, compiled output, or any name it does not know; and it flags matches it cannot prove are reachable. Expect both false positives and false negatives, and confirm every finding by hand before acting on it. Files larger than 1 MiB are skipped and reported. It exits with code 1 when it finds candidates — usable as a CI gate, with the same caveat: a passing exit means these heuristics matched nothing, not that the codebase is clean. Output uses colors only when there is a TTY: readable in logs and pipes.

License

MIT