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