black-bagg 0.2.8

# black-bag

[![crates.io](https://img.shields.io/crates/v/black-bagg.svg?style=flat-square)](https://crates.io/crates/black-bagg) [![docs.rs](https://docs.rs/black-bagg/badge.svg)](https://docs.rs/black-bagg) [![license: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg?style=flat-square)](LICENSE-MIT)

Install: `cargo install black-bagg` (binary name: `black-bag`)
Docs: https://docs.rs/black-bagg · Crate: https://crates.io/crates/black-bagg

## Configuration & Paths

- Vault path (default): platform config dir under `black_bag/vault.cbor`.
  - macOS: `~/Library/Application Support/black_bag/vault.cbor`
  - Linux: `~/.config/black_bag/vault.cbor`
  - Windows: `%APPDATA%/black_bag/vault.cbor`
- Duress vault: same directory, filename `vault.duress.cbor` (or override via env).
- Config file: `.../black_bag/config.toml` (permissions must be 0600 on Unix; otherwise ignored).

## Environment Variables

- `BLACK_BAG_VAULT_PATH` — override primary vault path.
- `BLACK_BAG_VAULT_DURESS_PATH` — override duress vault path.
- `BLACK_BAG_HARD_MODE=1` — force safest posture: TTY-only, clipboard disabled, noisy options ignored.
- `BLACK_BAG_UNSAFE_STDOUT=1` — allow stdout emission of secrets (prefer TTY instead).
- `BLACK_BAG_REQUIRE_MLOCK=1` — fail if page-locking cannot be enabled.
- `BLACK_BAG_EMIT=tty|stdout|json` — default emission target.
- `BLACK_BAG_AGENT=none|keychain` — agent backend (when built with feature).
- `BLACK_BAG_UNSAFE_CLIPBOARD=1` — allow clipboard operations (feature-gated, dangerous).
- `BLACK_BAG_DURESS=1` — use duress vault.
- `BLACK_BAG_FORMAT=text|json|ndjson` — default output format for non-secret results.
- `BLACK_BAG_QUIET=1` — suppress non-essential output.
- `BLACK_BAG_SCHEMA_VERSION=<N>` — schema version tag in machine-readable output.
- `BLACK_BAG_POLICY=moderate|strict` — passphrase policy for new/changed secrets.

## Exit Codes

- 0 — success
- 2 — input/validation errors (invalid/missing/too short, etc.)
- 3 — integrity/tamper detection (AEAD auth fail, header MAC mismatch)
- 4 — unlock failures
- 5 — I/O errors (filesystem, serialization)
- 6 — concurrency/locking (vault lock contention)
- 7 — policy violations (unsafe-stdout, mlock required, TTY required, denied)
- 10 — internal/unclassified

## Build Features

- `mlock` (default) — attempt page-locking of sensitive buffers.
- `pq` (default) — ML-KEM-1024 recipients and PQ traits.
- `tui` — optional terminal UI dependencies (ratatui/crossterm).
- `agent` — enable agent abstraction.
- `agent-keychain` — macOS keychain-backed agent (requires `agent`).
- `clipboard` — enable clipboard features (requires `--unsafe-clipboard`).

## Loss & Recovery Guide

What to do if you lose your computer. You can fully recover your vault if you have:
- Your vault file backup: `vault.cbor` plus its integrity sidecar `vault.int` (and optional `vault.int.sig` if you signed it)
- Your master passphrase (remembered) or enough Shamir shares to reconstruct it

### 1) Backup Strategy (before loss)

Keep a recent copy of your vault and integrity sidecar in secure storage (encrypted USB, cloud, password manager attachment):

```bash
# Copy vault + integrity sidecar to secure storage
cp ~/.config/black_bag/vault.cbor /secure/backup/location/
cp ~/.config/black_bag/vault.int  /secure/backup/location/

# Optional: sign integrity tag for authenticity (produces vault.int.sig)
black-bag backup sign --path ~/.config/black_bag/vault.cbor \
  --key /path/to/ed25519.secret --pub-out /secure/backup/location/ed25519.pub

# Verify backup health (bit-rot/tamper detection)
black-bag backup verify --path /secure/backup/location/vault.cbor \
  --pub-key /secure/backup/location/ed25519.pub
```

Split a recovery secret using Shamir (e.g., a paper-printed passphrase or recovery token) and distribute shares:

```bash
# 3-of-5 split with short checksum and optional QR (confirm to print)
black-bag recovery split --threshold 3 --shares 5 --with-checksum --qr --confirm-qr

# Distribute shares to trusted holders/locations
```

Recommendations
- Store `vault.cbor` and `vault.int` together. If you use signatures, store `vault.int.sig` and the Ed25519 public key with the backup.
- Use multiple geographically separated locations. Treat shares and backups as high‑value.

### 2) Recovery Process (after loss)

Install, point to your backup, and unlock:

```bash
# Install CLI on the new machine
cargo install black-bagg  # binary: black-bag

# Point the app to your backed-up vault (adjust the path)
export BLACK_BAG_VAULT_PATH=/path/to/backup/vault.cbor

# (Optional) Verify integrity sidecar and signature
black-bag backup verify --path "$BLACK_BAG_VAULT_PATH" --pub-key /path/to/ed25519.pub

# If you forgot your passphrase, reconstruct from shares
black-bag recovery combine --threshold 3 \
  --shares "1-<base64>,2-<base64>,3-<base64>" \
  --set-id <base32_id>
# Use the reconstructed secret as your vault passphrase (do not paste into chat apps or logs)

# Check readiness and access
black-bag doctor --json
black-bag list --format text
```

Migration and duress
- If prompted for migration, run: `black-bag migrate` (same passphrase). This refreshes on‑disk format and integrity.
- If you operate a duress vault, use `BLACK_BAG_VAULT_DURESS_PATH` to specify its location.

## Deletion & Destruction

Record deletion is secure and confirmation‑gated; total vault destruction is intentionally not a single CLI command.

### Record Deletion

```bash
# Interactive (requires typing DELETE)
black-bag record delete <UUID>

# Non-interactive (for scripting)
black-bag record delete <UUID> --force
```

Guarantees
- Immediate effect: the specified record becomes inaccessible.
- Integrity preserved: the vault remains consistent; deletion is atomic (all‑or‑nothing).
- Confirmation: interactive mode requires typing `DELETE` exactly; `--force` is required to skip it.

Operational notes
- Deleted plaintext does not linger in the vault file; ciphertext is rewritten safely.
- Memory traces are minimized (page‑locking best‑effort), but like any process, transient RAM/swap remnants can exist until overwritten.

### Full Vault Destruction

There is no built‑in “nuke everything” command (to prevent catastrophic accidents). If you must destroy a vault:

- Delete vault files and sidecars, then securely wipe per OS policy.
  - Linux (coreutils): `shred -vfz -n 3 -u ~/.config/black_bag/vault.cbor ~/.config/black_bag/vault.int ~/.config/black_bag/vault.int.sig 2>/dev/null || true`
  - macOS (APFS): prefer full‑disk encryption and secure erase of the encryption keys (FileVault). Overwriting files on APFS is not reliable; as a best effort, use `rm` and ensure the underlying volume is encrypted.
  - Windows: delete, then purge from Recycle Bin, and rely on BitLocker (encrypted volume). For extra assurance, wipe free space using platform tools.
- Always combine with full‑disk encryption for devices holding vaults or shares.

Bottom line
- Individual record deletion is reliable and safe.
- Complete destruction is deliberate and manual, using OS tools plus full‑disk encryption—this is by design to protect against accidental total loss.


`black-bag` is a zero‑trace, ultra‑secure, CLI‑only password manager for high‑risk operators. It ships as a single Rust binary with strict defaults (Argon2id time=10; lanes≥4), ML‑KEM‑1024 cascaded wrapping, XChaCha20‑Poly1305 encryption, and meticulous I/O hygiene (no stdout secrets by default, no temp files, atomic 0600 writes). Cross‑platform (macOS/Linux/Windows).

Core ideas:
- Secrets never go to stdout by default; reveals are TTY‑only unless you consciously opt into unsafe modes.
- Strong crypto: Argon2id → ML‑KEM‑1024 → 32‑byte DEK → XChaCha20‑Poly1305 for payload and per‑record secret fields.
- Strict limits and locking: page‑locking (best effort), input caps, constant‑time ops, sanitized errors.

Contents
- Install and Build
- Quick Start
- Operations Guide (day‑to‑day flows)
- CLI Reference (every command + flags, with examples)
- Security Model (short)
- Technology Deep Dive (all primitives, flows, AADs, sidecars)
- Vault Format (types, blobs, limits)
- Configuration (env/feature flags)
- Troubleshooting

## Install and Build

```bash
# From crates.io (recommended)
cargo install --locked black-bagg --features pq

# Local build
cargo build --release
install -m 0755 target/release/black-bag ~/.local/bin/black-bag

black-bag --version
```

Tips:
- Use an encrypted disk; avoid shell history (e.g., `HISTCONTROL=ignorespace`).
- For mission shells, set `BLACK_BAG_HARD_MODE=1` to force TTY‑only and disable unsafe stdout/clipboard overrides.

## Quick Start

```bash
# 1) Initialize vault (256 MiB Argon2 memory)
black-bag init --mem-kib 262144 --argon-lanes auto

# 2) Add a login
black-bag add login --title "Ops" --username phoenix --url https://ops.example --tags mission

# 3) List masked summaries
black-bag list --query ops

# 4) Reveal one record on a TTY
black-bag get <UUID> --reveal  # TTY required

# 5) Add a TOTP seed (prefer SHA‑256)
black-bag add totp --issuer GitHub --account you@example --secret-file ./totp.txt --algorithm sha256
black-bag totp code <UUID>

# 6) Rotate wrapping keys after missions
black-bag rotate

# 7) Split recovery material (3‑of‑7)
black-bag recovery split --threshold 3 --shares 7
```

## Operations Guide

### Create and Unlock
- `black-bag init --mem-kib 262144 --argon-lanes auto` prompts for a strong passphrase (≥14 NFKC chars and zxcvbn≥3).
- On first use of commands like `list`, `get`, `add`, the CLI prompts to unlock.

### Add Records (selected families)
- Login: `add login --title "Portal" --username alice --url https://example --tags prod`
- Note: `add note --title "Protocol" --tags red-team` then paste body (Ctrl‑D to end).
- API: `add api --service intel --environment prod --access-key AKIA... --scopes read,write`
- TOTP: `add totp --issuer GitHub --account you@example --secret-file ./secret.txt --algorithm sha256`
  - Safer alternative: `printf 'otpauth://...' | black-bag add totp --otpauth-stdin`
  - Optional ASCII QR: add `--qr --confirm-qr`.
- SSH/PGP/Recovery: `add ssh|pgp|recovery` then paste private/armored payload; stored encrypted.

### Search and Inspect
- `list` (masked): filter with `--kind`, `--tag`, `--query`, or `--fuzzy`.
- `get <UUID> --reveal` shows secrets on TTY. Clipboard copy requires build feature and `--unsafe-clipboard`.

### Rotation, Passphrase Changes, Migration
- `rotate [--mem-kib N]` refreshes KEM and rewraps DEK (updates header MAC/epoch).
- `passwd [--mem-kib N] [--argon-lanes auto|N] [--rekey-dek]` changes passphrase and optionally rekeys payload DEK.
- `migrate` bumps an older vault to latest on‑disk version and recomputes header MAC.

### Recovery and Backups
- Shamir split: `recovery split --threshold 3 --shares 7` outputs shares and a share‑set ID (commit). Store separately.
- Combine: `recovery combine --threshold 3 --shares 1-<b64>,2-<b64>,3-<b64> [--set-id ...] [--raw]`
  - `--raw` emits binary to TTY; otherwise base64.
- Backup check: `backup verify --path ~/.config/black_bag/vault.cbor` validates public integrity sidecar without passphrase.

## CLI Reference (Complete)

Global flags (prefix any subcommand):
- `--unsafe-stdout` – allow secrets to flow to stdout/JSON (default off; prefer TTY)
- `--require-mlock` – require page‑locking or abort
- `--emit <tty|stdout|json>` – preferred output mode for non‑reveal flows (stdout/json require `--unsafe-stdout`)
- `--format <text|json|ndjson>` – output format for non‑secret results (defaults to `text`)
- `--schema-version <N>` – include JSON schema version in machine‑readable output (defaults to `1`)
- `--quiet` – suppress warnings and non‑essential notices
- `--agent <none|keychain>` – enable keychain agent (feature‑gated)
- `--unsafe-clipboard` – allow copying secrets to clipboard (feature‑gated)
- `--duress` – operate on a separate duress vault file
- Env hard mode: `BLACK_BAG_HARD_MODE=1` forces TTY‑only/clipboard‑off regardless of flags

### init
Initialize a new vault.

```
black-bag init --mem-kib <KiB> [--argon-lanes auto|N]
```
Args:
- `--mem-kib` (default 262144; min 32768)
- `--argon-lanes` `auto` (CPU cores capped 8, min 4) or integer ≥4

### add
Add records in families. Sensitive values are captured by prompt/stdin/file; never argv.

Common options: `--title <str>` `--tags <t1,t2>` `--notes <str>`

Families:
- `login` – `--username <str>` `--url <str>`
- `contact` – `--full-name <str>` `--emails <e1,e2>` `--phones <p1,p2>`
- `id` – `--id-type <str>` `--name-on-doc <str>` `--number <str>` `--issuing-country <str>` `--expiry <YYYY-MM-DD>` (secret via prompt)
- `note` – paste body after prompt (Ctrl‑D to finish)
- `bank` – `--institution <str>` `--account-name <str>` `--routing-number <str>` (account number via prompt)
- `wifi` – `--ssid <str>` `--security <str>` `--location <str>` (passphrase via prompt)
- `api` – `--service <str>` `--environment <str>` `--access-key <str>` `--scopes <s1,s2>` (secret key via prompt)
- `wallet` – `--asset <str>` `--address <str>` `--network <str>` (secret key via prompt)
- `totp` – `--issuer <str>` `--account <str>` `--secret-file <PATH>` `--secret-stdin` `--otpauth-stdin` `--qr --confirm-qr` `--digits 6..8` `--step <secs>` `--skew <steps>` `--algorithm <sha1|sha256|sha512>`
- `ssh` – `--label <str>` `--comment <str>` then paste private key
- `pgp` – `--label <str>` `--fingerprint <str>` then paste armored private key
- `recovery` – `--description <str>` then paste recovery payload

Examples:
```
black-bag add login --title "Ops" --username alice --url https://ops --tags prod
black-bag add note --title "Protocol" --tags red-team
black-bag add totp --issuer GitHub --account you@example --secret-file ./secret.txt --algorithm sha256
```

### list
```
black-bag list [--kind <family>] [--tag <tag>] [--query <text>] [--fuzzy]
```
Families: `login, contact, id, note, bank, wifi, api, wallet, totp, ssh, pgp, recovery`

### get
```
black-bag get <UUID> [--reveal] [--clipboard]
```
Notes: `--reveal` requires TTY; `--clipboard` requires feature + `--unsafe-clipboard` and auto‑clears.

### rotate
```
black-bag rotate [--mem-kib <KiB>]
```

### doctor
```
black-bag doctor [--json]
```
Prints ready status, Argon2 params, record count, timestamps. JSON/NDJSON include `schema` and `headerMacVerified`.

### passwd
```
black-bag passwd [--mem-kib <KiB>] [--argon-lanes auto|N] [--rekey-dek]
```

### migrate
```
black-bag migrate [--pq ml-kem-1024|kyber1024|next] [--aead xchacha20poly1305|aes256gcm]
```
Notes: flags are accepted for forward compatibility; current builds keep ML‑KEM‑1024 + XChaCha20‑Poly1305.

### export csv
```
black-bag export csv [--kind <family>] --fields <f1,f2,...> [--include-secrets] --unsafe-stdout
```
Common fields: `id,kind,title,tags,summary,username,url,password,secret_key,totp_secret`

### backup verify
```
black-bag backup verify --path <vault.cbor>
```

### recovery split / combine
```
black-bag recovery split --threshold <n> --shares <m> [--duress]
black-bag recovery combine --threshold <n> --shares <id-b64,...> [--set-id <base32>] [--raw] [--duress]
```

### totp code
```
black-bag totp code --id <UUID> [--time <unix>]
```

### selftest
```
black-bag selftest
```

### version
```
black-bag version
```
Prints version + enabled features (PQC, AEAD, Argon caps, compiled features).

### completions
Generate shell completions (print to stdout):
```
black-bag completions <bash|zsh|fish|pwsh>
```

### help-man
Render a manpage to stdout:
```
black-bag help-man | man -l -
```

## Stdout/Stderr & Schema Contract
- Secrets and warnings are sent to the TTY or stderr; machine‑readable data are sent to stdout.
- When `--format json|ndjson` (or `--json`), a `schema` field is included (default `1`). Field names remain stable across schema versions.

## Exit Codes (Scriptable)
- `0` OK
- `2` Input/usage/validation error
- `3` Integrity failure (e.g., header MAC, tag mismatch)
- `4` Unlock error (failed to unlock vault)
- `5` I/O or environment errors
- `6` Concurrency/locking errors
- `7` Policy violations (requires TTY, unsafe flags not set, etc.)
- `10` Internal/unknown error

## Security Model (Short)
- KDF: Argon2id (time=10; lanes≥4, capped 8). Passphrase policy: NFKC, ≥14 chars, uniqueness, zxcvbn≥3.
- Wrapping: ML‑KEM‑1024 public key + ciphertext. Decapsulation secret sealed with KEK.
- Payload & secret fields: XChaCha20‑Poly1305 AEAD with distinct AADs; per‑record rDEKs for secrets at rest.
- Header integrity: keyed BLAKE3 MAC over critical header fields; verified on unlock (constant‑time compare).
- Public integrity sidecar: Blake3 tag keyed by KEM public to detect bit‑rot without secrets.
- Anti‑rollback: header epoch + `.epoch` sidecar (warn/fail); optional keychain epoch pin (feature‑gated) to fail on rollback.
- Process hardening: no coredumps; tracer/ptrace protections; release `panic=abort`; sanitized errors by default.
- Windows ACL: refuse insecure vault directory (Everyone/Authenticated Users write).

References: `docs/CRYPTO_POLICY.md`, `docs/THREAT_MODEL.md`, `docs/SECURITY_MODEL.md`, `docs/VAULT_FORMAT.md`.

Documentation map:
- Full CLI reference: `docs/CLI_REFERENCE.md`
- Technology deep dive: `docs/TECHNOLOGY.md`
- Vault format: `docs/VAULT_FORMAT.md`
- Security model (narrative): `docs/SECURITY_MODEL.md`
- Configuration: `docs/CONFIGURATION.md`
- Crypto policy: `docs/CRYPTO_POLICY.md`
- Threat model: `docs/THREAT_MODEL.md`

## Technology Deep Dive (Essentials)

- KDF (Argon2id)
  - Defaults: time=10; lanes=max(4, min(8, CPU cores)); mem configurable (suggest 256 MiB)
  - Salt=32B from OsRng; output KEK=32B (Zeroizing)

- KEM (ML‑KEM‑1024) via `pqcrypto-mlkem`
  - Sizes: PK=1568, SK=3168, CT=1568, SS=32 (checked at runtime)
  - Decapsulation secret (SK) sealed under KEK; shared secret derived at unlock

- AEAD (XChaCha20‑Poly1305, 24B nonces)
  - AAD labels (exact):
    - Payload: `black-bag::payload`
    - Sealed DEK: `black-bag::sealed-dek`
    - Sealed decapsulation: `black-bag::sealed-dk`
    - Sealed rDEK: `black-bag::record-dek`
    - Secret field blob: `black-bag::record-secret`

- Key hierarchy
  - Passphrase → Argon2id → KEK
  - KEK decrypts decapsulation secret (ML‑KEM‑1024 SK)
  - SK + (PK, CT) → shared (decaps) → decrypt DEK
  - DEK decrypts payload; per‑record rDEKs wrap secret fields

- Header MAC (keyed BLAKE3)
  - Context: `black-bag header mac`; verified constant‑time before any decryption
  - Covers: created/updated, Argon params+salt, epoch, KEM public+ciphertext, sealed blobs (nonces+ciphertexts)

- Integrity & Anti‑rollback
  - Public integrity `.int`: keyed Blake3 over serialized CBOR with context `black-bag public integrity`
  - Epoch `.epoch`: last seen epoch; warn/fail if header epoch behind sidecar; optional keychain epoch pin (feature‑gated)

- Padding & secret blobs
  - Optional payload padding: magic `BBPAD1\0\0` + length (LE u64) + CBOR + random pad (block set by `BLACK_BAG_PAD_BLOCK`)
  - Secret field blob at rest: `BBE1 | 24B nonce | ciphertext(tag)` under rDEK with AAD `record-secret`

- Shamir (recovery)
  - GF(2^8): constant‑time `gf_mul`; fixed addition‑chain `gf_inv`
  - Framed share: `[id | 16B salt | payload | 32B HMAC‑SHA256]`
  - MAC/commit contexts: normal `black-bag share mac/commit`; duress `black-bag share mac duress/duress commit`
  - Share‑set commit (base32) verified on combine; legacy (id|payload) still accepted

- Process & memory hygiene
  - Zeroization on drop; best‑effort page‑locking; TTY‑only reveals by default; atomic 0600 writes; file/dir sync
  - Linux: `O_NOATIME` reads; undumpable + tracer detection; macOS: deny attach; Windows: ACL checks

- Limits and families
  - Vault file ≤ 64 MiB; payload plaintext ≤ 32 MiB; secret field ≤ 8 KiB; notes/keys ≤ 256 KiB
  - Records ≤ 100k; tags/record ≤ 64; tag length ≤ 128; title ≤ 256; URL ≤ 4096; username ≤ 2048
  - Families: login, contact, id, note, bank, wifi, api, wallet, totp, ssh, pgp, recovery

## Configuration
- Env vars: `BLACK_BAG_VAULT_PATH`, `BLACK_BAG_VAULT_DURESS_PATH`, `BLACK_BAG_UNSAFE_STDOUT`, `BLACK_BAG_REQUIRE_MLOCK`, `BLACK_BAG_EMIT`, `BLACK_BAG_AGENT`, `BLACK_BAG_UNSAFE_CLIPBOARD`, `BLACK_BAG_DURESS`, `BLACK_BAG_HARD_MODE`, `BLACK_BAG_STRICT_ROLLBACK`, `BLACK_BAG_ALLOW_ROLLBACK` (see docs for details).
- Features: default `mlock`, `pq`; optional `tui`, `agent-keychain`, `clipboard`, `fuzzing`.

## Troubleshooting
- “vault not initialized” → run `init` or set `BLACK_BAG_VAULT_PATH`.
- “header integrity check failed” → stop; header was altered (rollback/tamper). Restore last known good.
- Windows “insecure vault directory permissions” → restrict ACL to current user only.
- TOTP QR warn → requires `--confirm-qr`.
- Clipboard unavailable → not compiled or `--unsafe-clipboard` not set.

## Mission‑Ready Checklist
- [x] Argon2id + ML‑KEM‑1024 + XChaCha20‑Poly1305 enabled by default
- [x] TTY‑only reveals; no stdout secrets by default
- [x] Strict input caps; atomic writes; zeroized buffers
- [x] Cross‑platform (macOS/Linux/Windows)
- [x] Comprehensive record families; search/tagging
- [x] Tests green; warnings denied
- [x] Operator docs + threat model

For production roll‑out, schedule an independent audit and set up long‑run fuzzing (see `docs/FURTHER_HARDENING.md`).

## Recent Security Changes
- Removed CLI secret parameters (prompt/stdin/file only)
- Constant‑time Shamir GF operations; sanitized errors
- Migrated to ML‑KEM‑1024; runtime size checks
- Input bounds added (pre/post parse caps)
- Argon2 defaults increased (time=10; lanes auto≥4)
## Backups & Integrity
- `backup verify --path <vault.cbor> [--pub-key <ed25519.pub>]` checks the public integrity sidecar (`.int`) and, if a public key is provided, verifies the detached signature sidecar (`.int.sig`). This checks bit‑rot, not authenticity unless a signature is supplied; keep vault and `.int` paired.
- `backup sign --path <vault.cbor> --key <ed25519.sk> [--pub-out <ed25519.pub>]` signs the integrity tag with an operator‑managed Ed25519 key.

## Recovery (Audit‑proof & Human‑proof)

## What Changed (Recent)
- Added `record edit/delete` commands for operator ergonomics.
- Expanded `export csv` with per‑family schemas and `--schema` header‑only mode.
- `get --otpauth` (text/JSON) and ASCII QR for TOTP provisioning; `totp doctor` for skew/TTL diagnostics.
- `scan passwords` finds duplicates and weak (zxcvbn<3) offline; JSON via `--format json`.
- `recovery split --threshold N --shares M [--with-checksum] [--qr --confirm-qr] [--duress]` prints `id-<base64>` tokens; optional checksum is appended as a trailing comment and QR codes can be printed for human transfer.
- `recovery verify --threshold N --shares "1-...,2-..." [--set-id ...] [--duress]` prints `OK`, `mismatch`, or `tamper` without emitting any secret.
- `recovery doctor ...` detects legacy‑only / mixed sets and prints exact remediation (what to re‑split).

<!-- BEGIN AUTO CLI -->
## Complete CLI Reference (Auto-generated)
This section is generated from `black-bag help` to ensure every command and option is included.

### black-bag (global)
```text
Ultra-secure zero-trace CLI vault

Usage: black-bag [OPTIONS] <COMMAND>

Commands:
  init         Initialize a new vault
  add          Add a record to the vault
  list         List records (masked summaries)
  get          Inspect a record by UUID
  rotate       Rewrap the master key with fresh randomness
  doctor       Print health diagnostics
  recovery     Manage Shamir recovery shares
  totp         Work with stored TOTP secrets
  export       Export data (requires --unsafe-stdout for secrets)
  record       Record maintenance
  backup       Backup utilities
  scan         Scan for weak/duplicate passwords (offline)
  passwd       Change master passphrase and/or Argon2 parameters
  migrate      Migrate vault to latest on-disk version
  selftest     Run embedded self-tests
  completions  Generate shell completion scripts
  help-man     Print a man page to stdout
  version      Print extended version and feature set
  help         Print this message or the help of the given subcommand(s)

Options:
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
  -V, --version
          Print version
```
### black-bag add
```text
Add a record to the vault

Usage: black-bag add [OPTIONS] <COMMAND>

Commands:
  login     Add a login/password record
  contact   Add a contact record
  id        Add an identity document record
  note      Add a secure note
  bank      Add a bank account record
  wifi      Add a Wi-Fi profile record
  api       Add an API credential record
  wallet    Add a cryptocurrency wallet record
  totp      Add a TOTP secret
  ssh       Add an SSH key record
  pgp       Add a PGP key record
  recovery  Add a recovery kit record
  help      Print this message or the help of the given subcommand(s)

Options:
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag backup
```text
Backup utilities

Usage: black-bag backup [OPTIONS] <COMMAND>

Commands:
  verify  Verify non-secret integrity tag of a vault backup sidecar
  sign    Sign the integrity tag with an Ed25519 key (writes .int.sig)
  help    Print this message or the help of the given subcommand(s)

Options:
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag completions
```text
Generate shell completion scripts

Usage: black-bag completions [OPTIONS] <SHELL>

Arguments:
  <SHELL>  Target shell [possible values: bash, elvish, fish, powershell, zsh]

Options:
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag doctor
```text
Print health diagnostics

Usage: black-bag doctor [OPTIONS]

Options:
      --json
          Emit machine-readable JSON instead of human text
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag export
```text
Export data (requires --unsafe-stdout for secrets)

Usage: black-bag export [OPTIONS] <COMMAND>

Commands:
  csv   Export records to CSV (requires --unsafe-stdout)
  help  Print this message or the help of the given subcommand(s)

Options:
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag get
```text
Inspect a record by UUID

Usage: black-bag get [OPTIONS] <ID>

Arguments:
  <ID>  Record UUID to inspect

Options:
      --reveal
          Reveal sensitive fields (requires TTY)
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --clipboard
          Copy primary secret to clipboard (requires --unsafe-clipboard)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --clipboard-ttl <CLIPBOARD_TTL>
          Time-to-live in seconds before clearing clipboard (used with --clipboard)
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --otpauth
          Emit an otpauth:// URI for TOTP records
      --qr
          Print an ASCII QR for the otpauth:// URI (requires --confirm-qr)
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --confirm-qr
          Explicit confirmation to print QR codes in terminal
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag help-man
```text
Print a man page to stdout

Usage: black-bag help-man [OPTIONS]

Options:
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag init
```text
Initialize a new vault

Usage: black-bag init [OPTIONS]

Options:
      --mem-kib <MEM_KIB>
          Argon2 memory cost in KiB (default: 262144 => 256 MiB) [default: 262144]
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --argon-lanes <ARGON_LANES>
          Argon2 lanes: integer or "auto" for CPU count capped to 8
      --require-mlock
          Require page-locked memory; abort if locking fails
      --dry-run
          Print what would be written without creating files
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag list
```text
List records (masked summaries)

Usage: black-bag list [OPTIONS]

Options:
      --kind <KIND>
          Filter by record kind [possible values: login, contact, id, note, bank, wifi, api, wallet, totp, ssh, pgp, recovery]
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --tag <TAG>
          Filter by tag (case-insensitive substring match)
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --query <QUERY>
          Full-text query over metadata fields
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --fuzzy
          Fuzzy match the query against summary text
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag migrate
```text
Migrate vault to latest on-disk version

Usage: black-bag migrate [OPTIONS]

Options:
      --pq <PQ>
          Target PQ KEM label (e.g., ml-kem-1024|kyber1024|next)
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --aead <AEAD>
          Target AEAD suite (e.g., xchacha20poly1305|aes256gcm)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --dry-run
          Print what would change without rewriting
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag passwd
```text
Change master passphrase and/or Argon2 parameters

Usage: black-bag passwd [OPTIONS]

Options:
      --mem-kib <MEM_KIB>
          Optionally override Argon2 memory cost in KiB during passphrase change
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --argon-lanes <ARGON_LANES>
          Optionally override Argon2 lanes (integer or "auto")
      --require-mlock
          Require page-locked memory; abort if locking fails
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --rekey-dek
          Rekey the data encryption key (re-encrypts entire payload)
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag record
```text
Record maintenance

Usage: black-bag record [OPTIONS] <COMMAND>

Commands:
  edit    Edit record metadata (title, tags, notes)
  delete  Delete a record by UUID
  help    Print this message or the help of the given subcommand(s)

Options:
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag recovery
```text
Manage Shamir recovery shares

Usage: black-bag recovery [OPTIONS] <COMMAND>

Commands:
  split    Split a secret into Shamir shares
  combine  Combine Shamir shares back into the original secret
  verify   Verify a set of shares without emitting the secret
  doctor   Diagnose share-set format and health
  help     Print this message or the help of the given subcommand(s)

Options:
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag rotate
```text
Rewrap the master key with fresh randomness

Usage: black-bag rotate [OPTIONS]

Options:
      --mem-kib <MEM_KIB>
          Optionally override Argon2 memory cost in KiB during rotation
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag scan
```text
Scan for weak/duplicate passwords (offline)

Usage: black-bag scan [OPTIONS] <COMMAND>

Commands:
  passwords  Analyze passwords for weakness and duplication
  help       Print this message or the help of the given subcommand(s)

Options:
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag selftest
```text
Run embedded self-tests

Usage: black-bag selftest [OPTIONS]

Options:
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag totp
```text
Work with stored TOTP secrets

Usage: black-bag totp [OPTIONS] <COMMAND>

Commands:
  code    Generate a TOTP code for the specified record
  doctor  Diagnose TOTP drift and parameters for a record
  help    Print this message or the help of the given subcommand(s)

Options:
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag version
```text
Print extended version and feature set

Usage: black-bag version [OPTIONS]

Options:
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag add api
```text
Add an API credential record

Usage: black-bag add api [OPTIONS]

Options:
      --title <TITLE>
          Optional title for the record
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --tags <TAGS>
          Comma-separated list of tags
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --notes <NOTES>
          Optional free-form notes (stored alongside metadata)
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --service <SERVICE>
          
      --environment <ENVIRONMENT>
          
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --access-key <ACCESS_KEY>
          
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --scopes <SCOPES>
          
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag add bank
```text
Add a bank account record

Usage: black-bag add bank [OPTIONS]

Options:
      --title <TITLE>
          Optional title for the record
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --tags <TAGS>
          Comma-separated list of tags
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --notes <NOTES>
          Optional free-form notes (stored alongside metadata)
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --institution <INSTITUTION>
          
      --account-name <ACCOUNT_NAME>
          
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --routing-number <ROUTING_NUMBER>
          
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag add contact
```text
Add a contact record

Usage: black-bag add contact [OPTIONS] --full-name <FULL_NAME>

Options:
      --title <TITLE>
          Optional title for the record
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --tags <TAGS>
          Comma-separated list of tags
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --notes <NOTES>
          Optional free-form notes (stored alongside metadata)
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --full-name <FULL_NAME>
          
      --emails <EMAILS>
          
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --phones <PHONES>
          
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag add id
```text
Add an identity document record

Usage: black-bag add id [OPTIONS]

Options:
      --title <TITLE>
          Optional title for the record
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --tags <TAGS>
          Comma-separated list of tags
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --notes <NOTES>
          Optional free-form notes (stored alongside metadata)
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --id-type <ID_TYPE>
          
      --name-on-doc <NAME_ON_DOC>
          
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --number <NUMBER>
          
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --issuing-country <ISSUING_COUNTRY>
          
      --expiry <EXPIRY>
          
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag add login
```text
Add a login/password record

Usage: black-bag add login [OPTIONS]

Options:
      --title <TITLE>
          Optional title for the record
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --tags <TAGS>
          Comma-separated list of tags
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --notes <NOTES>
          Optional free-form notes (stored alongside metadata)
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --username <USERNAME>
          
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --url <URL>
          
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag add note
```text
Add a secure note

Usage: black-bag add note [OPTIONS]

Options:
      --title <TITLE>
          Optional title for the record
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --tags <TAGS>
          Comma-separated list of tags
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --notes <NOTES>
          Optional free-form notes (stored alongside metadata)
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag add pgp
```text
Add a PGP key record

Usage: black-bag add pgp [OPTIONS]

Options:
      --title <TITLE>
          Optional title for the record
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --tags <TAGS>
          Comma-separated list of tags
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --notes <NOTES>
          Optional free-form notes (stored alongside metadata)
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --label <LABEL>
          
      --fingerprint <FINGERPRINT>
          
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag add recovery
```text
Add a recovery kit record

Usage: black-bag add recovery [OPTIONS]

Options:
      --title <TITLE>
          Optional title for the record
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --tags <TAGS>
          Comma-separated list of tags
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --notes <NOTES>
          Optional free-form notes (stored alongside metadata)
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --description <DESCRIPTION>
          
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag add ssh
```text
Add an SSH key record

Usage: black-bag add ssh [OPTIONS]

Options:
      --title <TITLE>
          Optional title for the record
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --tags <TAGS>
          Comma-separated list of tags
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --notes <NOTES>
          Optional free-form notes (stored alongside metadata)
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --label <LABEL>
          
      --comment <COMMENT>
          
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag add totp
```text
Add a TOTP secret

Usage: black-bag add totp [OPTIONS]

Options:
      --title <TITLE>
          Optional title for the record
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --tags <TAGS>
          Comma-separated list of tags
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --notes <NOTES>
          Optional free-form notes (stored alongside metadata)
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --issuer <ISSUER>
          Optional issuer string (display only)
      --account <ACCOUNT>
          Optional account/name label (display only)
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --secret-file <PATH>
          Read base32 secret from file
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --secret-stdin
          Read base32 secret from stdin (no prompt)
      --otpauth-stdin
          Read otpauth:// TOTP URI from stdin (safer than argv)
      --quiet
          Suppress warnings and non-essential notices
      --qr
          Print an ASCII QR to the TTY (requires --confirm-qr)
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --confirm-qr
          Explicit confirmation to print QR in terminal
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --digits <DIGITS>
          Number of digits (6-8) [default: 6]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
      --step <STEP>
          Seconds per step [default: 30]
      --skew <SKEW>
          Allowed skew (number of steps on each side) [default: 1]
      --algorithm <ALGORITHM>
          Hash algorithm [default: sha1] [possible values: sha1, sha256, sha512]
  -h, --help
          Print help
```
### black-bag add wallet
```text
Add a cryptocurrency wallet record

Usage: black-bag add wallet [OPTIONS]

Options:
      --title <TITLE>
          Optional title for the record
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --tags <TAGS>
          Comma-separated list of tags
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --notes <NOTES>
          Optional free-form notes (stored alongside metadata)
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --asset <ASSET>
          
      --address <ADDRESS>
          
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --network <NETWORK>
          
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag add wifi
```text
Add a Wi-Fi profile record

Usage: black-bag add wifi [OPTIONS]

Options:
      --title <TITLE>
          Optional title for the record
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --tags <TAGS>
          Comma-separated list of tags
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --notes <NOTES>
          Optional free-form notes (stored alongside metadata)
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --ssid <SSID>
          
      --security <SECURITY>
          
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --location <LOCATION>
          
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag backup sign
```text
Sign the integrity tag with an Ed25519 key (writes .int.sig)

Usage: black-bag backup sign [OPTIONS] --path <PATH> --key <KEY>

Options:
      --path <PATH>
          
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --key <KEY>
          Path to Ed25519 secret key (64-byte hex or base64)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --pub-out <PUB_OUT>
          Optionally write the derived public key to this path
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag backup verify
```text
Verify non-secret integrity tag of a vault backup sidecar

Usage: black-bag backup verify [OPTIONS] --path <PATH>

Options:
      --path <PATH>
          
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --pub-key <PUB_KEY>
          Optional Ed25519 public key to verify detached signature
      --require-mlock
          Require page-locked memory; abort if locking fails
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag export csv
```text
Export records to CSV (requires --unsafe-stdout)

Usage: black-bag export csv [OPTIONS]

Options:
      --kind <KIND>
          Filter by record kind [possible values: login, contact, id, note, bank, wifi, api, wallet, totp, ssh, pgp, recovery]
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --fields <FIELDS>
          Comma-separated list of fields to include
      --require-mlock
          Require page-locked memory; abort if locking fails
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --include-secrets
          Allow exporting secrets (strongly discouraged)
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --schema
          Print only the header row for the selected kind
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag record delete
```text
Delete a record by UUID

Usage: black-bag record delete [OPTIONS] <ID>

Arguments:
  <ID>  Record UUID to delete

Options:
      --force
          Do not prompt for confirmation
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag record edit
```text
Edit record metadata (title, tags, notes)

Usage: black-bag record edit [OPTIONS] <ID>

Arguments:
  <ID>  Record UUID to edit

Options:
      --title <TITLE>
          Set title (empty to clear)
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --add-tag <ADD_TAG>
          Add tags (comma-separated)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --rm-tag <RM_TAG>
          Remove tags (comma-separated)
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --notes <NOTES>
          Set metadata notes (empty to clear)
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag recovery combine
```text
Combine Shamir shares back into the original secret

Usage: black-bag recovery combine [OPTIONS] --threshold <THRESHOLD> --shares <SHARES>

Options:
      --threshold <THRESHOLD>
          Reconstruction threshold (usually matches value used during split)
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --shares <SHARES>
          Comma-separated list of shares (e.g., 1-<base64>,2-<base64>)
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --set-id <SET_ID>
          Share-set ID printed during split (base32)
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --raw
          Emit raw binary secret to the TTY instead of base64 text
      --duress
          Use duress channel
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag recovery doctor
```text
Diagnose share-set format and health

Usage: black-bag recovery doctor [OPTIONS] --threshold <THRESHOLD> --shares <SHARES>

Options:
      --threshold <THRESHOLD>
          Reconstruction threshold
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --shares <SHARES>
          Comma-separated list of shares
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --set-id <SET_ID>
          Share-set ID, if available
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --duress
          Use duress channel
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag recovery split
```text
Split a secret into Shamir shares

Usage: black-bag recovery split [OPTIONS]

Options:
      --threshold <THRESHOLD>
          Threshold required to reconstruct the secret [default: 3]
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --shares <SHARES>
          Total number of shares to produce [default: 5]
      --duress
          Use duress channel
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --qr
          Print an ASCII QR for each share token (requires --confirm-qr)
      --confirm-qr
          Explicit confirmation to print QR codes to terminal
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --with-checksum
          Append a short Base32 Crockford checksum as a trailing comment
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag recovery verify
```text
Verify a set of shares without emitting the secret

Usage: black-bag recovery verify [OPTIONS] --threshold <THRESHOLD> --shares <SHARES>

Options:
      --threshold <THRESHOLD>
          Reconstruction threshold (usually matches value used during split)
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --shares <SHARES>
          Comma-separated list of shares (e.g., 1-<base64>[ # chk: ...],2-<base64>)
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --set-id <SET_ID>
          Share-set ID printed during split (base32)
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --duress
          Use duress channel
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag scan passwords
```text
Analyze passwords for weakness and duplication

Usage: black-bag scan passwords [OPTIONS]

Options:
      --duplicates
          Report duplicate passwords across records
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --weak
          Report very weak passwords (zxcvbn score < 3)
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag totp code
```text
Generate a TOTP code for the specified record

Usage: black-bag totp code [OPTIONS] <ID>

Arguments:
  <ID>  Record UUID containing the TOTP secret

Options:
      --time <TIME>
          Unix timestamp (seconds) to use instead of now
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
### black-bag totp doctor
```text
Diagnose TOTP drift and parameters for a record

Usage: black-bag totp doctor [OPTIONS] <ID>

Arguments:
  <ID>  Record UUID containing the TOTP secret

Options:
      --ref-time <REF_TIME>
          Optional reference Unix time to compare with system clock
      --unsafe-stdout
          Allow secrets to flow to stdout (unsafe; prefer TTY)
      --require-mlock
          Require page-locked memory; abort if locking fails
      --emit <EMIT>
          Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json) [possible values: tty, stdout, json]
      --agent <AGENT>
          Optional agent integration (feature-gated backends) [possible values: none, keychain]
      --unsafe-clipboard
          Allow copying secrets to clipboard (dangerous)
      --duress
          Use duress vault path (separate ciphertext)
      --format <FORMAT>
          Output format for non-secret command results [default: text] [possible values: text, json, ndjson]
      --quiet
          Suppress warnings and non-essential notices
      --schema-version <SCHEMA_VERSION>
          JSON schema version for machine-readable output
      --policy <POLICY>
          Passphrase policy for new/changed secrets [possible values: moderate, strict]
      --machine
          Machine mode: force quiet JSON for non-secret outputs
  -h, --help
          Print help
```
<!-- END AUTO CLI -->