diff --git a/src/cli/README.md b/src/cli/README.md
new file mode 100644
index 0000000..a7b2f9f
--- /dev/null
+++ b/src/cli/README.md
@@ -0,0 +1,234 @@
+# XO CLI
+
+Command-line interface for the XO Engine. Create wallets, manage templates, build invitations, sign transactions, and broadcast them to the Bitcoin Cash network.
+
+## Getting Started
+
+```bash
+# Run any command via tsx from the cli/ directory
+npx tsx src/cli/index.ts <command> [options]
+```
+
+### Wallet Setup
+
+Before using most commands you need a mnemonic wallet file.
+
+```bash
+# Generate a new mnemonic and save it to a file
+xo-cli mnemonic create
+
+# Import an existing mnemonic seed phrase
+xo-cli mnemonic import page pencil stock planet limb cluster assault speak off joke private pioneer
+
+# List available mnemonic files in the current directory
+xo-cli mnemonic list
+```
+
+Mnemonic files are stored in the working directory with the prefix `mnemonic-`.
+
+### Wallet Persistence
+
+The first time you pass `-m <file>`, the choice is saved to `.xo-cli-wallet`. Subsequent commands will use that wallet automatically so you can omit `-m`.
+
+```bash
+# First run — pass the wallet explicitly
+xo-cli resource list -m mnemonic-nuclear
+
+# All future runs remember the wallet
+xo-cli resource list
+```
+
+To switch wallets, pass `-m` again with a different file.
+
+## Global Options
+
+| Flag | Description |
+|---|---|
+| `-m`, `--mnemonic-file <file>` | Mnemonic file to use (persisted after first use) |
+| `-v`, `--verbose` | Show detailed debug output |
+| `-h`, `--help` | Show help message |
+
+## Commands
+
+### `mnemonic` — Manage Wallet Files
+
+```bash
+xo-cli mnemonic create                   # Generate a new mnemonic
+xo-cli mnemonic import <seed words...>   # Import a mnemonic from seed words
+xo-cli mnemonic list                     # List mnemonic files in cwd
+```
+
+**Options:**
+- `-o <filename>` — Custom output filename for the mnemonic file.
+
+### `template` — Manage Templates
+
+```bash
+xo-cli template import <template-file>                          # Import a template
+xo-cli template list                                            # List imported templates
+xo-cli template list <category> <template-id>                   # List items in a category
+xo-cli template inspect <category> <template-id> <field>        # Inspect a specific field
+xo-cli template set-default <template-file> <output-id> <role>  # Set default locking params
+```
+
+**Categories:** `action`, `transaction`, `output`, `lockingscript`, `variable`
+
+**Example — discover what a template offers:**
+
+```bash
+xo-cli template import p2pkh-template.json
+xo-cli template list
+xo-cli template list action <template-identifier>
+```
+
+### `resource` — Manage UTXOs
+
+```bash
+xo-cli resource list               # List unreserved (spendable) UTXOs
+xo-cli resource list reserved      # List UTXOs reserved by invitations
+xo-cli resource list all           # List all UTXOs (reserved + unreserved)
+xo-cli resource unreserve <txhash:vout>   # Unreserve a specific UTXO
+xo-cli resource unreserve-all             # Unreserve all reserved UTXOs
+```
+
+Each UTXO is displayed as `<txhash>:<vout> <sats> <outputId> (height <n>)`.
+
+### `receive` — Generate a Receiving Address
+
+```bash
+xo-cli receive <template-file> <output-identifier> [role-identifier]
+```
+
+Generates a single-use BCH cash address from a template. If the role is omitted, the first available role is used.
+
+```bash
+xo-cli receive p2pkh-template.json receiveOutput receiver
+```
+
+### `invitation` — Build, Sign & Broadcast Transactions
+
+This is the core command for sending funds. An invitation goes through these stages: **create** → **sign** → **broadcast**.
+
+```bash
+xo-cli invitation create <template-file> <action-id> [options]
+xo-cli invitation append <invitation-id> [options]
+xo-cli invitation sign <invitation-id>
+xo-cli invitation broadcast <invitation-id>
+xo-cli invitation requirements <invitation-id>
+xo-cli invitation import <invitation-file>
+xo-cli invitation list
+```
+
+#### Create / Append Options
+
+| Flag | Description |
+|---|---|
+| `-var-<name> <value>` | Set a template variable (kebab-case → camelCase) |
+| `--add-input <txhash:vout>` | Add UTXO input(s), comma-separated |
+| `--add-output <id>` | Override output(s) — **omit to auto-discover from template** |
+| `--auto-inputs` | Automatically select UTXOs to cover the required amount |
+| `-role <role>` | Role identifier for variable scoping and bytecode generation |
+| `--sign` | Auto-sign after all requirements are satisfied |
+| `--broadcast` | Auto-broadcast after signing (implies `--sign`) |
+
+When inputs are provided, a **change output is automatically added** if the input total exceeds the required amount + fee (500 sats). Change below the dust threshold (546 sats) is donated as fee.
+
+Outputs are **auto-discovered from the template** when `--add-output` is omitted, so you typically don't need to specify them.
+
+#### Variable Naming
+
+Variable flags use kebab-case which maps to the template's camelCase identifiers:
+
+```
+-var-transferred-satoshis 4678  →  transferredSatoshis = "4678"
+-var-recipient-lockingscript <addr>  →  recipientLockingscript = "<addr>"
+```
+
+## Full Send Flow
+
+### One-Command Send (Recommended)
+
+With `--broadcast`, the entire create → sign → broadcast flow happens in a single invocation:
+
+```bash
+# 1. List UTXOs to pick an input
+xo-cli resource list
+
+# 2. Send in one shot
+xo-cli invitation create p2pkh-template.json sendSatoshis \
+  -var-transferred-satoshis 4678 \
+  -var-recipient-lockingscript "bitcoincash:qz..." \
+  --add-input <txhash>:<vout> \
+  -role sender \
+  --broadcast
+```
+
+Output:
+
+```
+Invitation created: abc123.json (abc123)
+Invitation signed: abc123
+Transaction broadcast: <txid>
+```
+
+### Step-by-Step Send
+
+For multi-party transactions or debugging, you can run each step separately:
+
+```bash
+# 1. Import template (only needed once)
+xo-cli template import p2pkh-template.json
+
+# 2. Check available UTXOs
+xo-cli resource list
+
+# 3. Create the invitation with variables and inputs
+xo-cli invitation create p2pkh-template.json sendSatoshis \
+  -var-transferred-satoshis 4678 \
+  -var-recipient-lockingscript "bitcoincash:qz..." \
+  --add-input <txhash>:<vout> \
+  -role sender
+
+# 4. Sign
+xo-cli invitation sign <invitation-id>
+
+# 5. Broadcast
+xo-cli invitation broadcast <invitation-id>
+```
+
+### Using Auto-Inputs
+
+Instead of manually selecting UTXOs, let the CLI pick them:
+
+```bash
+xo-cli invitation create p2pkh-template.json sendSatoshis \
+  -var-transferred-satoshis 4678 \
+  -var-recipient-lockingscript "bitcoincash:qz..." \
+  --auto-inputs \
+  -role sender \
+  --broadcast
+```
+
+## Shell Completions
+
+Tab-completion is available for bash, zsh, and fish:
+
+```bash
+# Bash
+eval "$(xo-cli completions bash)"
+
+# Zsh
+eval "$(xo-cli completions zsh)"
+
+# Fish
+xo-cli completions fish | source
+```
+
+## File Conventions
+
+| File/Pattern | Purpose |
+|---|---|
+| `mnemonic-*` | Wallet mnemonic files |
+| `.xo-cli-wallet` | Persisted wallet selection |
+| `*.json` | Invitation files (saved by create/append) |
+| `*.db` | Engine database files |