xo-cli/src/cli/README.md

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

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

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

# 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

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

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:

xo-cli template import p2pkh-template.json
xo-cli template list
xo-cli template list action <template-identifier>

resource — Manage UTXOs

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

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.

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.

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:

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

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

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