https://docs.rs/black-bagg

black-bag

Ultra‑secure, zero‑trace, CLI‑only password manager for high‑risk operators. 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).

Docs: https://docs.rs/black-bagg · Crate: https://crates.io/crates/black-bagg

Install and Build

# 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

# 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

At a glance

• get --otpauth prints TOTP provisioning (text/JSON); add --qr --confirm-qr for ASCII QR output.
• totp doctor shows drift/TTL diagnostics; totp code outputs the current code.
• scan passwords detects duplicates and weak credentials (offline); add --format json for machine output.
• recovery split --threshold N --shares M [--with-checksum] [--qr --confirm-qr] [--duress] emits id- tokens.
• recovery verify --threshold N --shares "1-...,2-..." [--set-id ...] [--duress] checks sets without revealing secrets.
• recovery doctor detects mixed/legacy sets and prints exact remediation.

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):

# 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:

# 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:

# 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

# 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.

Contributing & Sponsorship

We welcome high‑quality contributions that strengthen security, correctness, and usability. Please follow these guidelines:

• Issues: open clear, reproducible reports with version (black-bag version), OS, and steps.
• Pull requests: keep changes focused; include rationale, tests when reasonable, and update docs/CLI help if behavior changes.
• Style: match existing Rust style; prefer small functions, explicit errors, constant‑time patterns for sensitive code; avoid panics in library paths.
• Security: do not disclose vulnerabilities in public issues. Email a private report (or open a confidential channel) with steps and impact. We’ll coordinate a fix and release.
• Supply chain: new dependencies must be audited for license, maintenance, and minimal attack surface; avoid heavy transitive trees.

Professional sponsorship keeps this project independent and security‑focused. If you or your organization rely on it, please consider sponsoring development:

• Bitcoin (BTC, bech32): bc1qhl5jdyzckcg7mtfatt7z0nfnetg480ugqhun7x
• Purpose: security reviews, maintenance, hardening, portability, and documentation quality.

For enterprise support, integration guidance, or security reviews, open an issue to start a private thread and we’ll coordinate next steps.

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

Operations Guide

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

• Argon2id + ML‑KEM‑1024 + XChaCha20‑Poly1305 enabled by default
• TTY‑only reveals; no stdout secrets by default
• Strict input caps; atomic writes; zeroized buffers
• Cross‑platform (macOS/Linux/Windows)
• Comprehensive record families; search/tagging
• Tests green; warnings denied
• 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).

Complete CLI Reference (Auto-generated)

This section is generated from black-bag help to ensure every command and option is included.

black-bag (global)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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