Accept XOInvitationCommit when identifying paricipants

.gitignore

@@ -3,6 +3,7 @@ Electrum.sqlite
 XO.sqlite
 node_modules/
 dist/
+coverage/
 *.db
 *.db-shm
 *.db-wal
@@ -10,5 +11,5 @@ dist/
 *.sqlite-journal
 resolvedTemplate.json
 mnemonic-*
-.xo-cli-wallet
+inv-*.json
-inv-*.json
+.xo-cli-wallet

package.json

@@ -3,17 +3,25 @@
   "version": "1.0.0",
   "main": "dist/index.js",
   "type": "module",
+  "bin": {
+    "xo-cli": "./dist/cli/index.js",
+    "xo-tui": "./dist/index.js",
+    "xo-complete": "./dist/cli/autocomplete/complete.js"
+  },
   "scripts": {
     "dev": "SYNC_SERVER_URL=https://sync.xo.harvmaster.com tsx src/index.ts",
-    "build": "tsc",
+    "build": "tsc && npm run build:copy-scripts",
+    "build:copy-scripts": "cp -r src/cli/autocomplete/scripts dist/cli/autocomplete/",
     "start": "SYNC_SERVER_URL=https://sync.xo.harvmaster.com node dist/index.js",
-    "test": "vitest --run",
+    "test": "vitest --run --passWithNoTests",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
+    "test:coverage": "vitest run --coverage --passWithNoTests",
-    "nuke": "tsx scripts/rm-dbs.ts",
-    "nuke:dry": "tsx scripts/rm-dbs.ts --dry",
     "format": "prettier --write \"**/*.{js,ts,md,json}\" --ignore-path .gitignore",
-    "format:check": "prettier --check ."
+    "format:check": "prettier --check .",
+    "autocomplete:install": "node dist/cli/index.js completions bash --install",
+    "autocomplete:install:bash": "node dist/cli/index.js completions bash --install",
+    "autocomplete:install:zsh": "node dist/cli/index.js completions zsh --install",
+    "autocomplete:install:fish": "node dist/cli/index.js completions fish --install"
   },
   "keywords": [
     "crypto",
@@ -27,10 +35,12 @@
   "dependencies": {
     "@bitauth/libauth": "^3.0.0",
     "@electrum-cash/protocol": "^2.3.1",
+    "@generalprotocols/oracle-client": "^0.0.1-development.11945476152",
+    "@xo-cash/crypto": "^0.0.1",
     "@xo-cash/engine": "file:../engine",
     "@xo-cash/state": "file:../state",
     "@xo-cash/templates": "file:../templates",
-    "@xo-cash/types": "file:../types",
+    "@xo-cash/types": "^0.0.1",
     "better-sqlite3": "^12.6.2",
     "clipboardy": "^5.1.0",
     "ink": "^6.6.0",
@@ -44,6 +54,7 @@
     "@types/node": "^25.0.10",
     "@types/qrcode": "^1.5.6",
     "@types/react": "^19.2.14",
+    "@vitest/coverage-v8": "^4.1.2",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.1.2"

readme.md

@@ -0,0 +1,107 @@
+# XO-CLI & XO-TUI
+
+## Installation
+
+### Full Installation
+```bash
+# Create a new directory since we are going to be pulling in engine too
+mkdir xo-terminal && cd xo-terminal
+
+# ----- Start Engine Setup -----
+# Clone the Engine Repo (Note, this uses harvey's fork of the engine repo to access the cli-test branch)
+git clone git@gitlab.com:Harvmaster/engine.git
+
+# Move into teh engine directory
+cd engine
+
+# Checkout the cli-test branch
+git checkout cli-test
+
+# Install the dependencies
+npm ci
+
+# Build the engine
+npm run build
+# ----- End Engine Setup -----
+
+# Move back to the top level directory
+cd ..
+
+# ----- Start State Setup -----
+# Clone the State Repo
+git clone git@gitlab.com:Harvmaster/state.git
+
+# Move into the state directory
+cd state
+
+git checkout in-memory-adapter
+
+# Install the dependencies
+npm ci
+
+# Build the state
+npm run build
+# ----- End State Setup -----
+
+# Move back to the top level directory
+cd ..
+
+# ----- Start CLI Setup -----
+# Clone the CLI Repo
+git clone git@git.harvmaster.com:Harvmaster/xo-cli.git 
+
+# Move into the cli directory
+cd xo-cli
+
+# Install the dependencies
+npm ci
+
+# Build the cli
+npm run build
+# ----- End CLI Setup -----
+```
+
+### Run TUI in dev mode
+
+```bash
+npm run dev
+```
+
+### Install globally
+
+```bash
+# (From the xo-cli directory)
+npm install -g .
+```
+
+### Install autocomplete completions (From the xo-cli directory)
+
+#### Install for bash
+```bash
+npm run autocomplete:install:bash
+```
+
+#### Install for zsh
+```bash
+npm run autocomplete:install:zsh
+```
+
+#### Install for fish
+```bash
+npm run autocomplete:install:fish
+```
+
+### Run the CLI
+```bash
+# If globally installed (Not really usable if not globally installed)
+xo-cli
+```
+
+### Run the TUI
+```bash
+# If globally installed
+xo-tui
+
+# If not globally installed
+npm run dev
+```

scripts/rm-dbs.ts

@@ -1,40 +0,0 @@
-import fs from "fs/promises";
-
-/**
- * Remove all the databases without the use of external tools
- * TODO: Fix the ts linking issue here. Should just be adding this as a dir in tsconfig.json
- */
-const rmDbs = async (dry = false) => {
-  // First, we need to find all the database base files
-  // These end in either .db.sqlite, .sqlite, .db
-  // Get all the files in the current directory
-  const files = await fs.readdir("./");
-
-  // Filter out the files that end in .db.sqlite, .sqlite, .db
-  const dbFiles = files.filter(
-    (file) =>
-      file.endsWith(".db.sqlite") ||
-      file.endsWith(".sqlite") ||
-      file.endsWith(".db"),
-  );
-
-  // We need to remove all the files
-  await deleteFiles(dbFiles, dry);
-};
-
-const deleteFiles = async (files: string[], dry = false) => {
-  if (dry) {
-    console.log("Dry run, would delete:", files);
-    return;
-  }
-
-  await Promise.all(files.map((file) => fs.rm(file)));
-  console.log("All databases removed");
-};
-
-// Read args
-const args = process.argv.slice(2);
-const dry = args.includes("--dry");
-
-// Delete the files
-await rmDbs(dry);

src/app.ts

@@ -3,9 +3,11 @@
  * Simplified to render TUI immediately and let it handle AppService creation.
  */
 
+import { join } from "node:path";
 import React from "react";
 import { render, type Instance } from "ink";
 import { App as AppComponent } from "./tui/App.js";
+import { getDataDir } from "./utils/paths.js";
 
 /**
  * Configuration options for the CLI application.
@@ -46,13 +48,14 @@ export class App {
    * @returns Running App instance
    */
   static async create(config: Partial<AppConfig> = {}): Promise<App> {
+    const dataDir = getDataDir();
     // Set default configuration
     const fullConfig: AppConfig = {
       syncServerUrl: config.syncServerUrl ?? "http://localhost:3000",
-      databasePath: config.databasePath ?? "./",
+      databasePath: config.databasePath ?? dataDir,
       databaseFilename: config.databaseFilename ?? "xo-wallet.db",
       invitationStoragePath:
-        config.invitationStoragePath ?? "./xo-invitations.db",
+        config.invitationStoragePath ?? join(dataDir, "xo-invitations.db"),
     };
 
     console.log("Full config:", fullConfig);

src/cli/README.md

@@ -2,96 +2,143 @@
 
 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
+There are two global commands after install:
+
+- **`xo-cli`** — non-interactive commands (this document).
+- **`xo-tui`** — interactive terminal wallet UI (Ink/React).
+
+## Global config directory
+
+Wallet state lives under **`~/.config/xo-cli/`** (XDG-style), so you can run commands from any directory:
+
+| Path                          | Purpose                                                                 |
+| ----------------------------- | ----------------------------------------------------------------------- |
+| `~/.config/xo-cli/mnemonics/` | Mnemonic files (`mnemonic-*`)                                           |
+| `~/.config/xo-cli/data/`      | Engine DB (`xo-wallet.db`) and invitation storage (`xo-invitations.db`) |
+| `~/.config/xo-cli/.wallet`    | JSON settings (`default-mnemonic`, `currency`)                          |
+
+**Local to your shell’s current directory:** template JSON paths, invitation JSON you create/import, and any path you pass explicitly (e.g. `-m /abs/path/to/file`).
+
+## Install (global, from this repo)
+
+`@xo-cash/*` dependencies use `file:` paths, so publish to npm is a separate step. For local development:
 
 ```bash
-# Run any command via tsx from the cli/ directory
+cd engine/cli
-npx tsx src/cli/index.ts <command> [options]
+npm install
+npm run build
+npm link
+# xo-cli and xo-tui are now on your PATH
 ```
 
+Development without linking:
+
+```bash
+cd engine/cli
+npx tsx src/cli/index.ts <command> [options]
+npx tsx src/index.ts   # TUI
+```
+
+### Environment variables (TUI / `xo-tui`)
+
+| Variable                  | Default                                   |
+| ------------------------- | ----------------------------------------- |
+| `SYNC_SERVER_URL`         | `http://localhost:3000`                   |
+| `DB_PATH`                 | `~/.config/xo-cli/data`                   |
+| `DB_FILENAME`             | `xo-wallet.db`                            |
+| `INVITATION_STORAGE_PATH` | `~/.config/xo-cli/data/xo-invitations.db` |
+
+## Getting Started
+
 ### Wallet Setup
 
-Before using most commands you need a mnemonic wallet file.
-
 ```bash
-# Generate a new mnemonic and save it to a file
+# Generate a new mnemonic (saved under ~/.config/xo-cli/mnemonics/)
 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
+# List mnemonic basenames (use with -m)
 xo-cli mnemonic list
 ```
 
-Mnemonic files are stored in the working directory with the prefix `mnemonic-`.
+**Options:** `-o <filename>` — basename only; file is written under the global mnemonics directory.
 
 ### 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`.
+The first time you pass `-m <name>`, that reference is saved as
+`default-mnemonic` in `~/.config/xo-cli/.wallet`. Later runs can omit `-m`.
+
+`currency` controls the fiat unit used when showing BCH/sats conversions in the TUI.
+
+Mnemonic resolution order:
+
+1. Absolute path, if the file exists
+2. Path relative to the current working directory
+3. `~/.config/xo-cli/mnemonics/<basename>`
 
 ```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 (`xo-cli`)
 
-## Global Options
+| Flag                           | Description                                         |
+| ------------------------------ | --------------------------------------------------- |
+| `-m`, `--mnemonic-file <file>` | Mnemonic file (basename, cwd-relative, or absolute) |
+| `--currency <code>`            | Fiat display currency (e.g. `USD`, `AUD`)            |
+| `-o`, `--output <filename>`    | Output filename (used by `mnemonic create`/`import`) |
+| `-v`, `--verbose`              | Verbose output                                      |
+| `-h`, `--help`                 | Help                                                |
 
-| Flag | Description |
+Advanced: you can pass `--database-path`, `--database-filename`, and `--invitation-storage-path` to override the defaults under `~/.config/xo-cli/data/` (see `src/cli/index.ts`).
-|---|---|
-| `-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 create
-xo-cli mnemonic import <seed words...>   # Import a mnemonic from seed words
+xo-cli mnemonic import <seed words...>
-xo-cli mnemonic list                     # List mnemonic files in cwd
+xo-cli mnemonic list
+xo-cli mnemonic expose <mnemonic-file>
 ```
 
-**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 import <template-file>
-xo-cli template list                                            # List imported templates
+xo-cli template list
-xo-cli template list <category> <template-id>                   # List items in a category
+xo-cli template list <category> <template-id>
-xo-cli template inspect <category> <template-id> <field>        # Inspect a specific field
+xo-cli template inspect <category> <template-id> <field>
-xo-cli template set-default <template-file> <output-id> <role>  # Set default locking params
+xo-cli template set-default <template-file> <output-id> <role>
 ```
 
 **Categories:** `action`, `transaction`, `output`, `lockingscript`, `variable`
 
-**Example — discover what a template offers:**
+Template paths are resolved relative to the **current working directory**.
-
-```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
-xo-cli resource list reserved      # List UTXOs reserved by invitations
+xo-cli resource list reserved
-xo-cli resource list all           # List all UTXOs (reserved + unreserved)
+xo-cli resource list all
-xo-cli resource unreserve <txhash:vout>   # Unreserve a specific UTXO
+xo-cli resource unreserve <txhash:vout>
-xo-cli resource unreserve-all             # Unreserve all reserved UTXOs
+xo-cli resource unreserve-all
 ```
 
-Each UTXO is displayed as `<txhash>:<vout> <sats> <outputId> (height <n>)`.
+### `settings` — Manage Persisted Settings
+
+```bash
+xo-cli settings show
+xo-cli settings get currency
+xo-cli settings get default-mnemonic
+xo-cli settings set currency AUD
+xo-cli settings set default-mnemonic mnemonic-nuclear
+```
 
 ### `receive` — Generate a Receiving Address
 
@@ -99,15 +146,7 @@ Each UTXO is displayed as `<txhash>:<vout> <sats> <outputId> (height <n>)`.
 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.
+### `invitation` — Build, Sign & Broadcast
-
-```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]
@@ -116,45 +155,28 @@ 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 inspect <invitation-file>
 xo-cli invitation list
 ```
 
-#### Create / Append Options
+**Create / append options:**
 
-| Flag | Description |
+| Flag                        | Description                              |
-|---|---|
+| --------------------------- | ---------------------------------------- |
-| `-var-<name> <value>` | Set a template variable (kebab-case → camelCase) |
+| `-var-<name> <value>`       | Template variable                        |
-| `--add-input <txhash:vout>` | Add UTXO input(s), comma-separated |
+| `--add-input <txhash:vout>` | Inputs (comma-separated)                 |
-| `--add-output <id>` | Override output(s) — **omit to auto-discover from template** |
+| `--add-output <id>`         | Override outputs (omit to auto-discover) |
-| `--auto-inputs` | Automatically select UTXOs to cover the required amount |
+| `--auto-inputs`             | Auto-select UTXOs                        |
-| `-role <role>` | Role identifier for variable scoping and bytecode generation |
+| `-role <role>`              | Role for variables / bytecode            |
-| `--sign` | Auto-sign after all requirements are satisfied |
+| `--sign`                    | Auto-sign when complete                  |
-| `--broadcast` | Auto-broadcast after signing (implies `--sign`) |
+| `--broadcast`               | Auto-broadcast (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.
+Invitation JSON files from `create` / `append` are written to the **current working directory**.
 
-Outputs are **auto-discovered from the template** when `--add-output` is omitted, so you typically don't need to specify them.
+### One-command send
-
-#### 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..." \
@@ -163,72 +185,25 @@ xo-cli invitation create p2pkh-template.json sendSatoshis \
   --broadcast
 ```
 
-Output:
+### `xo-tui`
-
-```
-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-tui
-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
+Launches the full-screen wallet UI; uses the same global data directory unless overridden by env vars.
-
-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 |
+| Location            | Purpose                                    |
-|---|---|
+| ------------------- | ------------------------------------------ |
-| `mnemonic-*` | Wallet mnemonic files |
+| `~/.config/xo-cli/` | Global wallet state                        |
-| `.xo-cli-wallet` | Persisted wallet selection |
+| `./` (cwd)          | Templates, invitation JSON, explicit paths |
-| `*.json` | Invitation files (saved by create/append) |
-| `*.db` | Engine database files |

src/cli/arguments.ts

@@ -1,6 +1,6 @@
 /**
  * CLI Argument extraction and validation.
- * 
+ *
  * Converts `-${key}` or `--${key}` to `key` in the args object.
  */
 import { z } from "zod";
@@ -15,27 +15,31 @@ import { z } from "zod";
  *     verbose: "true",
  *   },
  * }
- * 
+ *
  * @param args - The CLI args to convert.
  * @returns The key-value object.
  */
-export function convertArgsToObject(args: string[]): { args: string[], options: Record<string, string> } {
+export function convertArgsToObject(args: string[]): {
+  args: string[];
+  options: Record<string, string>;
+} {
   // Map of single-character short flags to their canonical long names
   const shortToFull: Record<string, string> = {
-    'm': 'mnemonicFile',
+    m: "mnemonicFile",
-    'o': 'output',
+    o: "output",
-    'v': 'verbose',
+    v: "verbose",
-    'h': 'help',
+    h: "help",
   };
 
   // Flags that are always boolean and never consume the next argument as a value.
   // Uses the canonical (expanded) names so the check works after short-form resolution.
   const booleanFlags = new Set<string>([
-    'verbose',
+    "verbose",
-    'help',
+    "help",
-    'autoInputs',
+    "autoInputs",
-    'sign',
+    "sign",
-    'broadcast',
+    "broadcast",
+    "install",
   ]);
 
   const positionalArgs: string[] = [];
@@ -54,7 +58,9 @@ export function convertArgsToObject(args: string[]): { args: string[], options:
     // - Remove the leading `-`s
     // - Convert kebab-case to camelCase
     // - Expand known short forms to their full names
-    let key = arg.replace(/^-+/, "").replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    let key = arg
+      .replace(/^-+/, "")
+      .replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
     key = shortToFull[key] ?? key;
 
     // Known boolean flags never take a value
@@ -77,4 +83,4 @@ export function convertArgsToObject(args: string[]): { args: string[], options:
   }
 
   return { args: positionalArgs, options: optionsObject };
-}
+}

src/cli/autocomplete/complete.ts

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+/**
+ * Lightweight shell completion helper for xo-cli.
+ *
+ * This script reads from local SQLite only - no network connections.
+ * It's designed to be fast enough for interactive tab completion.
+ *
+ * Usage: xo-complete <context> [args...]
+ *
+ * Contexts:
+ *   mnemonics                         - List mnemonic file names
+ *   templates                         - List template names/IDs
+ *   actions <template>                - List actions for a template
+ *   fields <category> <template>      - List fields for a template category
+ *   invitations                       - List invitation IDs
+ *   resources                         - List UTXO outpoints (txhash:vout)
+ *   subcommands <command>             - List subcommands for a top-level command
+ *
+ * Output: One completion suggestion per line, suitable for shell completion.
+ *
+ * Exit codes:
+ *   0 - Success (may output zero or more completions)
+ *   1 - Error (no output, fails silently for shell integration)
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+
+import {
+  getDataDir,
+  getMnemonicsDir,
+  getWalletConfigPath,
+} from "../../utils/paths.js";
+import { loadMnemonic } from "../mnemonic.js";
+import { Storage } from "../../services/storage.js";
+import { SettingsService } from "../../services/settings.js";
+import { COMMAND_TREE } from "./completions.js";
+
+// Lazy-loaded modules (only loaded when needed for dynamic completions)
+let _offlineEngineModule: typeof import("./offline-engine.js") | null = null;
+let _engineModule: typeof import("@xo-cash/engine") | null = null;
+
+async function getOfflineEngineModule() {
+  if (!_offlineEngineModule) {
+    _offlineEngineModule = await import("./offline-engine.js");
+  }
+  return _offlineEngineModule;
+}
+
+async function getEngineModule() {
+  if (!_engineModule) {
+    _engineModule = await import("@xo-cash/engine");
+  }
+  return _engineModule;
+}
+
+/**
+ * Outputs completions to stdout, one per line.
+ * Optionally filters by a prefix (for partial word completion).
+ */
+function outputCompletions(items: readonly string[], prefix?: string): void {
+  const filtered = prefix
+    ? items.filter((item) =>
+        item.toLowerCase().startsWith(prefix.toLowerCase()),
+      )
+    : items;
+
+  for (const item of filtered) {
+    console.log(item);
+  }
+}
+
+/**
+ * Lists mnemonic file names from the mnemonics directory.
+ * Fast path: no engine needed, just filesystem.
+ */
+function listMnemonics(prefix?: string): void {
+  try {
+    const mnemonicsDir = getMnemonicsDir();
+    const files = readdirSync(mnemonicsDir).filter((f) =>
+      f.startsWith("mnemonic-"),
+    );
+    outputCompletions(files, prefix);
+  } catch {
+    // Silently fail - no completions available
+  }
+}
+
+/**
+ * Lists subcommands for a given top-level command.
+ * Uses the static COMMAND_TREE.
+ */
+function listSubcommands(command: string, prefix?: string): void {
+  if (command in COMMAND_TREE) {
+    const subcommands = COMMAND_TREE[command as keyof typeof COMMAND_TREE];
+    outputCompletions(subcommands, prefix);
+  }
+}
+
+/**
+ * Gets the current wallet's mnemonic seed from the saved config.
+ * Returns null if no wallet is configured.
+ */
+function getCurrentMnemonic(): string | null {
+  try {
+    const settings = new SettingsService(getWalletConfigPath());
+    const mnemonicFile = settings.getDefaultMnemonic();
+    if (!mnemonicFile) {
+      return null;
+    }
+
+    const mnemonicsDir = getMnemonicsDir();
+    return loadMnemonic(mnemonicsDir, mnemonicFile);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Lists templates from the engine.
+ */
+async function listTemplates(prefix?: string): Promise<void> {
+  const mnemonic = getCurrentMnemonic();
+  if (!mnemonic) return;
+
+  const { tryCreateOfflineEngine } = await getOfflineEngineModule();
+  const { generateTemplateIdentifier } = await getEngineModule();
+
+  const engine = await tryCreateOfflineEngine(mnemonic, {
+    databasePath: getDataDir(),
+    databaseFilename: "xo-wallet.db",
+  });
+
+  if (!engine) return;
+
+  try {
+    const templates = await engine.listImportedTemplates();
+    const completions: string[] = [];
+
+    for (const template of templates) {
+      // Add template name (for user-friendly completion)
+      if (template.name) {
+        completions.push(template.name);
+      }
+      // Also add template identifier (for precise matching)
+      const id = generateTemplateIdentifier(template);
+      if (id && !completions.includes(id)) {
+        completions.push(id);
+      }
+    }
+
+    outputCompletions(completions, prefix);
+  } finally {
+    await engine.stop();
+  }
+}
+
+/**
+ * Resolves a template by name or ID.
+ */
+async function resolveTemplate(
+  engine: Awaited<
+    ReturnType<
+      Awaited<
+        ReturnType<typeof getOfflineEngineModule>
+      >["tryCreateOfflineEngine"]
+    >
+  >,
+  templateQuery: string,
+) {
+  if (!engine) return null;
+
+  const { generateTemplateIdentifier } = await getEngineModule();
+  const templates = await engine.listImportedTemplates();
+
+  // Try exact match on name or ID
+  let template = templates.find(
+    (t) =>
+      t.name === templateQuery ||
+      generateTemplateIdentifier(t) === templateQuery,
+  );
+
+  // Try partial match on name
+  if (!template) {
+    template = templates.find((t) =>
+      t.name?.toLowerCase().includes(templateQuery.toLowerCase()),
+    );
+  }
+
+  return template ?? null;
+}
+
+/**
+ * Lists actions for a specific template.
+ */
+async function listActions(
+  templateQuery: string,
+  prefix?: string,
+): Promise<void> {
+  const mnemonic = getCurrentMnemonic();
+  if (!mnemonic) return;
+
+  const { tryCreateOfflineEngine } = await getOfflineEngineModule();
+
+  const engine = await tryCreateOfflineEngine(mnemonic, {
+    databasePath: getDataDir(),
+    databaseFilename: "xo-wallet.db",
+  });
+
+  if (!engine) return;
+
+  try {
+    const template = await resolveTemplate(engine, templateQuery);
+
+    if (template && template.actions) {
+      const actions = Object.keys(template.actions);
+      outputCompletions(actions, prefix);
+    }
+  } finally {
+    await engine.stop();
+  }
+}
+
+/**
+ * Lists fields (actions, transactions, outputs, etc.) for a specific template category.
+ * Used for completing the 3rd argument of `template inspect <category> <template> <field>`.
+ */
+async function listFields(
+  category: string,
+  templateQuery: string,
+  prefix?: string,
+): Promise<void> {
+  const mnemonic = getCurrentMnemonic();
+  if (!mnemonic) return;
+
+  const { tryCreateOfflineEngine } = await getOfflineEngineModule();
+
+  const engine = await tryCreateOfflineEngine(mnemonic, {
+    databasePath: getDataDir(),
+    databaseFilename: "xo-wallet.db",
+  });
+
+  if (!engine) return;
+
+  try {
+    const template = await resolveTemplate(engine, templateQuery);
+    if (!template) return;
+
+    let fields: string[] = [];
+
+    switch (category) {
+      case "action":
+        fields = Object.keys(template.actions || {});
+        break;
+      case "transaction":
+        fields = Object.keys(template.transactions || {});
+        break;
+      case "output":
+        fields = Object.keys(template.outputs || {});
+        break;
+      case "lockingscript":
+        fields = Object.keys(template.lockingScripts || {});
+        break;
+      case "variable":
+        fields = Object.keys(template.variables || {});
+        break;
+    }
+
+    outputCompletions(fields, prefix);
+  } finally {
+    await engine.stop();
+  }
+}
+
+/**
+ * Lists invitation IDs from the invitation storage.
+ */
+async function listInvitations(prefix?: string): Promise<void> {
+  const mnemonic = getCurrentMnemonic();
+  if (!mnemonic) return;
+
+  try {
+    // Compute seed hash to find the right storage namespace
+    const seedHash = createHash("sha256").update(mnemonic).digest("hex");
+    const invitationsDbPath = join(getDataDir(), "xo-invitations.db");
+
+    if (!existsSync(invitationsDbPath)) {
+      return;
+    }
+
+    const storage = await Storage.create(invitationsDbPath);
+    const walletStorage = storage.child(seedHash.slice(0, 8));
+    const invitationsStorage = walletStorage.child("invitations");
+
+    const invitations = await invitationsStorage.all();
+    const ids = invitations.map((inv) => inv.key);
+
+    outputCompletions(ids, prefix);
+  } catch {
+    // Silently fail - no completions available
+  }
+}
+
+/**
+ * Lists UTXO outpoints (resources) from the engine.
+ */
+async function listResources(prefix?: string): Promise<void> {
+  const mnemonic = getCurrentMnemonic();
+  if (!mnemonic) return;
+
+  const { tryCreateOfflineEngine } = await getOfflineEngineModule();
+
+  const engine = await tryCreateOfflineEngine(mnemonic, {
+    databasePath: getDataDir(),
+    databaseFilename: "xo-wallet.db",
+  });
+
+  if (!engine) return;
+
+  try {
+    const utxos = await engine.listUnspentOutputsData();
+    const outpoints = utxos.map(
+      (u) => `${u.outpointTransactionHash}:${u.outpointIndex}`,
+    );
+    outputCompletions(outpoints, prefix);
+  } finally {
+    await engine.stop();
+  }
+}
+
+/**
+ * Main entry point.
+ */
+async function main(): Promise<void> {
+  const context = process.argv[2];
+  const arg1 = process.argv[3];
+  const arg2 = process.argv[4];
+
+  if (!context) {
+    // No context provided - output nothing
+    process.exit(0);
+  }
+
+  switch (context) {
+    case "mnemonics":
+      listMnemonics(arg1);
+      break;
+
+    case "subcommands":
+      if (arg1) {
+        listSubcommands(arg1, arg2);
+      }
+      break;
+
+    case "templates":
+      await listTemplates(arg1);
+      break;
+
+    case "actions":
+      if (arg1) {
+        await listActions(arg1, arg2);
+      }
+      break;
+
+    case "fields":
+      // fields <category> <template> [prefix]
+      if (arg1 && arg2) {
+        await listFields(arg1, arg2, process.argv[5]);
+      }
+      break;
+
+    case "invitations":
+      await listInvitations(arg1);
+      break;
+
+    case "resources":
+      await listResources(arg1);
+      break;
+
+    default:
+      // Unknown context - output nothing
+      break;
+  }
+}
+
+main().catch(() => {
+  // Silently fail for shell integration
+  process.exit(1);
+});

src/cli/autocomplete/completions.ts

@@ -0,0 +1,311 @@
+/**
+ * Shell completion script generation.
+ *
+ * Loads shell-native template files and replaces placeholders with
+ * dynamic values. This approach keeps the shell scripts readable
+ * and auditable in their native format.
+ *
+ * The generated scripts use the `xo-complete` helper binary for dynamic
+ * completions (invitation IDs, template names, resources, etc.).
+ *
+ * Usage:
+ *   eval "$(xo-cli completions bash)"
+ *   eval "$(xo-cli completions zsh)"
+ *   xo-cli completions fish | source
+ *
+ * Install to shell config:
+ *   xo-cli completions bash --install
+ *   xo-cli completions zsh --install
+ *   xo-cli completions fish --install
+ */
+
+import {
+  existsSync,
+  readFileSync,
+  appendFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+
+/**
+ * Single source of truth for the CLI command tree.
+ * Each top-level key is a command, and its value is an array of sub-commands.
+ *
+ * IMPORTANT: Keep this in sync with actual switch statements in command handlers:
+ * - mnemonic.ts: create, import, list, expose
+ * - template.ts: import, list, inspect, set-default
+ * - invitation.ts: create, append, sign, broadcast, requirements, import, inspect, list
+ * - resource.ts: list, unreserve, unreserve-all
+ * - settings.ts: show, get, set
+ */
+
+/** Subcommands for the mnemonic command */
+const MNEMONIC_SUBS = ["create", "import", "list", "expose"];
+/** Subcommands for the template command */
+const TEMPLATE_SUBS = ["import", "list", "inspect", "set-default"];
+/** Subcommands for the invitation command */
+const INVITATION_SUBS = [
+  "create",
+  "append",
+  "sign",
+  "broadcast",
+  "requirements",
+  "import",
+  "inspect",
+  "list",
+];
+/** Subcommands for the resource command */
+const RESOURCE_SUBS = ["list", "unreserve", "unreserve-all"];
+/** Subcommands for the settings command */
+const SETTINGS_SUBS = ["show", "get", "set"];
+/** Subcommands for the completions command */
+const COMPLETIONS_SUBS = ["bash", "zsh", "fish"];
+
+export const COMMAND_TREE = {
+  mnemonic: MNEMONIC_SUBS,
+  template: TEMPLATE_SUBS,
+  invitation: INVITATION_SUBS,
+  receive: [],
+  resource: RESOURCE_SUBS,
+  settings: SETTINGS_SUBS,
+  help: [],
+  completions: COMPLETIONS_SUBS,
+} as const;
+
+/** Global option flags available on every command. */
+const GLOBAL_OPTIONS = [
+  "-h",
+  "--help",
+  "-v",
+  "--verbose",
+  "-m",
+  "--mnemonic-file",
+  "--currency",
+  "-o",
+  "--output",
+];
+
+/**
+ * Gets the path to the scripts directory containing shell templates.
+ */
+function getScriptsDir(): string {
+  const currentFile = fileURLToPath(import.meta.url);
+  return join(dirname(currentFile), "scripts");
+}
+
+/**
+ * Loads a shell template file and replaces placeholders.
+ * @param templateName - The template file name (e.g., "bash.sh")
+ * @param binName - The CLI binary name
+ */
+function loadAndProcessTemplate(templateName: string, binName: string): string {
+  const scriptsDir = getScriptsDir();
+  const templatePath = join(scriptsDir, templateName);
+
+  if (!existsSync(templatePath)) {
+    throw new Error(`Template file not found: ${templatePath}`);
+  }
+
+  let content = readFileSync(templatePath, "utf8");
+  const funcName = binName.replace(/-/g, "_");
+  const commands = Object.keys(COMMAND_TREE).join(" ");
+  const options = GLOBAL_OPTIONS.join(" ");
+
+  // Replace all placeholders
+  content = content.replace(/\{\{BIN_NAME\}\}/g, binName);
+  content = content.replace(/\{\{FUNC_NAME\}\}/g, funcName);
+  content = content.replace(/\{\{COMMANDS\}\}/g, commands);
+  content = content.replace(/\{\{OPTIONS\}\}/g, options);
+  content = content.replace(/\{\{MNEMONIC_SUBS\}\}/g, MNEMONIC_SUBS.join(" "));
+  content = content.replace(/\{\{TEMPLATE_SUBS\}\}/g, TEMPLATE_SUBS.join(" "));
+  content = content.replace(
+    /\{\{INVITATION_SUBS\}\}/g,
+    INVITATION_SUBS.join(" "),
+  );
+  content = content.replace(/\{\{RESOURCE_SUBS\}\}/g, RESOURCE_SUBS.join(" "));
+
+  // Fish-specific placeholders
+  if (templateName.endsWith(".fish")) {
+    content = content.replace(
+      /\{\{TOP_LEVEL_COMMANDS\}\}/g,
+      generateFishTopLevelCommands(binName),
+    );
+    content = content.replace(
+      /\{\{STATIC_SUBCOMMANDS\}\}/g,
+      generateFishStaticSubcommands(binName),
+    );
+  }
+
+  return content;
+}
+
+/**
+ * Generates fish top-level command completions.
+ */
+function generateFishTopLevelCommands(binName: string): string {
+  const lines: string[] = [];
+  for (const cmd of Object.keys(COMMAND_TREE)) {
+    lines.push(
+      `complete -c ${binName} -n "__fish_use_subcommand" -a "${cmd}" -d "${cmd} command"`,
+    );
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Generates fish static subcommand completions.
+ */
+function generateFishStaticSubcommands(binName: string): string {
+  const lines: string[] = [];
+  for (const [cmd, subs] of Object.entries(COMMAND_TREE)) {
+    for (const sub of subs) {
+      lines.push(
+        `complete -c ${binName} -n "__fish_seen_subcommand_from ${cmd}; and not __fish_seen_subcommand_from ${subs.join(" ")}" -a "${sub}" -d "${cmd} ${sub}"`,
+      );
+    }
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Generates a bash completion script.
+ * @param binName - The name of the CLI binary.
+ */
+export function generateBashCompletions(binName: string): string {
+  return loadAndProcessTemplate("bash.sh", binName);
+}
+
+/**
+ * Generates a zsh completion script.
+ * @param binName - The name of the CLI binary.
+ */
+export function generateZshCompletions(binName: string): string {
+  return loadAndProcessTemplate("zsh.zsh", binName);
+}
+
+/**
+ * Generates a fish completion script.
+ * @param binName - The name of the CLI binary.
+ */
+export function generateFishCompletions(binName: string): string {
+  return loadAndProcessTemplate("fish.fish", binName);
+}
+
+type ShellType = "bash" | "zsh" | "fish";
+
+const generators: Record<ShellType, (binName: string) => string> = {
+  bash: generateBashCompletions,
+  zsh: generateZshCompletions,
+  fish: generateFishCompletions,
+};
+
+/**
+ * Shell config file paths and eval commands for each shell type.
+ */
+const shellConfigs: Record<
+  ShellType,
+  { configFile: string; evalCommand: (binName: string) => string }
+> = {
+  bash: {
+    configFile: join(homedir(), ".bashrc"),
+    evalCommand: (binName) => `eval "$(${binName} completions bash)"`,
+  },
+  zsh: {
+    configFile: join(homedir(), ".zshrc"),
+    evalCommand: (binName) => `eval "$(${binName} completions zsh)"`,
+  },
+  fish: {
+    configFile: join(homedir(), ".config", "fish", "config.fish"),
+    evalCommand: (binName) => `${binName} completions fish | source`,
+  },
+};
+
+/**
+ * Installs completions to the user's shell config file.
+ * Adds the eval command if not already present.
+ * @param shell - The shell type
+ * @param binName - The CLI binary name
+ * @returns true if installed, false if already present
+ */
+function installCompletions(shell: ShellType, binName: string): boolean {
+  const config = shellConfigs[shell];
+  const evalCommand = config.evalCommand(binName);
+
+  // Check if config file exists and already has the completion line
+  let existingContent = "";
+  if (existsSync(config.configFile)) {
+    existingContent = readFileSync(config.configFile, "utf8");
+    if (existingContent.includes(evalCommand)) {
+      return false; // Already installed
+    }
+  }
+
+  // Append the completion line
+  const newLine =
+    existingContent.endsWith("\n") || existingContent === "" ? "" : "\n";
+  const completionBlock = `${newLine}\n# ${binName} shell completions\n${evalCommand}\n`;
+
+  appendFileSync(config.configFile, completionBlock);
+  return true;
+}
+
+/**
+ * Handles the `completions` command.
+ * Prints the generated completion script for the given shell to stdout,
+ * or installs it to the shell config file with --install.
+ * @param args - Positional args after "completions", e.g. ["bash"].
+ * @param options - Parsed command options (may include "install").
+ * @param binName - The CLI binary name to use in the completion script.
+ */
+export function handleCompletionsCommand(
+  args: string[],
+  options: Record<string, string> = {},
+  binName: string = "xo-cli",
+): void {
+  const shell = args[0] as ShellType | undefined;
+  const installFlag = options["install"] === "true";
+
+  if (!shell || !generators[shell]) {
+    const supported = Object.keys(generators).join(", ");
+    console.error(`Usage: ${binName} completions <${supported}> [--install]`);
+    console.error("");
+    console.error("Examples:");
+    console.error(
+      `  eval "$(${binName} completions bash)"   # Output to stdout (add to ~/.bashrc)`,
+    );
+    console.error(
+      `  eval "$(${binName} completions zsh)"    # Output to stdout (add to ~/.zshrc)`,
+    );
+    console.error(
+      `  ${binName} completions fish | source    # Output to stdout (add to fish config)`,
+    );
+    console.error("");
+    console.error("Install directly to shell config:");
+    console.error(
+      `  ${binName} completions bash --install   # Appends to ~/.bashrc`,
+    );
+    console.error(
+      `  ${binName} completions zsh --install    # Appends to ~/.zshrc`,
+    );
+    console.error(
+      `  ${binName} completions fish --install   # Appends to ~/.config/fish/config.fish`,
+    );
+    process.exit(1);
+  }
+
+  if (installFlag) {
+    const config = shellConfigs[shell];
+    const installed = installCompletions(shell, binName);
+
+    if (installed) {
+      console.log(`Completions installed to ${config.configFile}`);
+      console.log(`Restart your shell or run: source ${config.configFile}`);
+    } else {
+      console.log(`Completions already installed in ${config.configFile}`);
+    }
+    return;
+  }
+
+  process.stdout.write(generators[shell](binName));
+}

src/cli/autocomplete/offline-engine.ts

@@ -0,0 +1,103 @@
+/**
+ * Offline Engine Factory
+ *
+ * Creates a lightweight engine instance that reads from SQLite without any
+ * network connections. Used for fast shell completion queries.
+ *
+ * This bypasses the normal Engine.create() which initializes electrum connections,
+ * and instead constructs the engine directly with an in-memory blockchain provider.
+ */
+
+import {
+  BlockchainMonitor,
+  Engine,
+  InMemoryBlockchainProvider,
+} from "@xo-cash/engine";
+import { createStorageAdapter, State, StorageType } from "@xo-cash/state";
+import { convertMnemonicToSeedBytes } from "@xo-cash/crypto";
+import { binToHex, hash256 } from "@bitauth/libauth";
+import { createHash } from "crypto";
+
+/**
+ * Options for creating an offline engine.
+ */
+export interface OfflineEngineOptions {
+  /** Path to the directory containing SQLite database files. */
+  databasePath: string;
+  /** Filename of the SQLite database (will be prefixed with seed hash). */
+  databaseFilename: string;
+}
+
+/**
+ * Creates an engine instance in offline mode - SQLite only, no network.
+ * Used for fast completion queries where we only need to read local data.
+ *
+ * This is significantly faster than Engine.create() because it:
+ * - Skips electrum application initialization
+ * - Uses an in-memory blockchain provider (no network)
+ * - Skips state sync initialization
+ *
+ * @param seed - The wallet seed phrase
+ * @param options - Database configuration options
+ * @returns An engine instance configured for offline/read-only use
+ */
+export async function createOfflineEngine(
+  seed: string,
+  options: OfflineEngineOptions,
+): Promise<Engine> {
+  // Compute the seed hash (same logic as AppService.create)
+  const seedHash = createHash("sha256").update(seed).digest("hex");
+  const prefixedDatabaseFilename = `${seedHash.slice(0, 8)}-${options.databaseFilename}`;
+
+  // Generate account hash for storage namespace (must match Engine.create which uses hash256)
+  const seedAccountHash = hash256(convertMnemonicToSeedBytes(seed));
+
+  // Create the IndexedDB storage adapter (matches Engine.create default)
+  // Note: IndexedDB in Node uses a shim that stores data in SQLite files with .sqlite extension
+  const storageAdapter = await createStorageAdapter({
+    storageType: StorageType.INDEXEDDB,
+    databasePath: options.databasePath,
+    databaseFilename: prefixedDatabaseFilename,
+    accountHash: binToHex(seedAccountHash),
+  });
+
+  // Initialize the storage adapter
+  await storageAdapter.initialize();
+
+  // Create the state instance
+  const state = new State(storageAdapter);
+
+  // Use in-memory blockchain provider (no network connections)
+  const blockchainProvider = new InMemoryBlockchainProvider();
+  await blockchainProvider.initialize({
+    applicationIdentifier: "xo-cli-completions",
+    electrumOptions: {},
+  });
+
+  // Create a minimal blockchain monitor
+  const blockchainMonitor = new BlockchainMonitor(state, blockchainProvider);
+
+  // Construct engine directly without state sync
+  const engine = new Engine(seed, state, blockchainMonitor, blockchainProvider);
+
+  return engine;
+}
+
+/**
+ * Attempts to create an offline engine, returning null on failure.
+ * Useful for completion scripts where we don't want to crash on errors.
+ *
+ * @param seed - The wallet seed phrase
+ * @param options - Database configuration options
+ * @returns An engine instance or null if creation failed
+ */
+export async function tryCreateOfflineEngine(
+  seed: string,
+  options: OfflineEngineOptions,
+): Promise<Engine | null> {
+  try {
+    return await createOfflineEngine(seed, options);
+  } catch {
+    return null;
+  }
+}

src/cli/autocomplete/scripts/bash.sh

@@ -0,0 +1,240 @@
+# ------------------------------------------------------------------------------
+# Bash completion template for {{BIN_NAME}}
+# ------------------------------------------------------------------------------
+# Installation:
+#   eval "$({{BIN_NAME}} completions bash)"
+#
+# This file is generated from a template. Placeholders (for example `{{OPTIONS}}`)
+# are replaced at build/runtime with concrete command data from the CLI.
+# ------------------------------------------------------------------------------
+
+# Prefer a globally-installed helper, but fall back to a helper co-located with
+# the CLI binary. This lets completions work in both "installed via PATH" and
+# "single extracted directory" workflows.
+__xo_complete_bin=""
+if command -v xo-complete &>/dev/null; then
+  __xo_complete_bin="xo-complete"
+elif command -v {{BIN_NAME}} &>/dev/null; then
+  __xo_complete_bin="$(dirname "$(command -v {{BIN_NAME}})")/xo-complete"
+fi
+
+# @description
+# Calls the dynamic completion helper and suppresses helper stderr so the shell
+# completion menu stays clean even when the helper is unavailable or errors.
+# @param "$@" Arguments forwarded to xo-complete.
+__xo_complete() {
+  [[ -n "${__xo_complete_bin}" ]] && "${__xo_complete_bin}" "$@" 2>/dev/null
+}
+
+# @description
+# Main completion dispatcher invoked by bash's `complete -F`.
+# It determines context (command/subcommand/argument position) and then mixes:
+# - static completions (known command words)
+# - dynamic completions (resolved by xo-complete)
+# - filesystem completions (when a subcommand expects file paths)
+_{{FUNC_NAME}}_completions() {
+  local cur prev words cword
+  # Populates `cur`, `prev`, `words`, and `cword`.
+  # `_init_completion` is provided by bash-completion.
+  _init_completion || return
+
+  # If the previous token is `-m/--mnemonic-file`, this argument expects a
+  # mnemonic file alias/path. Ask the helper for mnemonic suggestions.
+  if [[ "${prev}" == "-m" || "${prev}" == "--mnemonic-file" ]]; then
+    local mnemonics
+    mnemonics=$(__xo_complete mnemonics "${cur}")
+    if [[ -n "${mnemonics}" ]]; then
+      while IFS= read -r line; do
+        COMPREPLY+=("$line")
+      done <<< "${mnemonics}"
+      return 0
+    fi
+  fi
+
+  # Option context: show global options when the current token starts with `-`.
+  if [[ "${cur}" == -* ]]; then
+    COMPREPLY=($(compgen -W "{{OPTIONS}}" -- "${cur}"))
+    return 0
+  fi
+
+  # Parse command/subcommand from non-option tokens before the current cursor.
+  # We track indices so argument-position logic can be computed later.
+  local cmd="" subcmd="" cmd_idx=0 subcmd_idx=0
+  for ((i=1; i < cword; i++)); do
+    if [[ "${words[i]}" != -* ]]; then
+      if [[ -z "${cmd}" ]]; then
+        cmd="${words[i]}"
+        cmd_idx=$i
+      else
+        subcmd="${words[i]}"
+        subcmd_idx=$i
+        break
+      fi
+    fi
+  done
+
+  # No command selected yet: complete top-level commands.
+  if [[ -z "${cmd}" ]]; then
+    COMPREPLY=($(compgen -W "{{COMMANDS}}" -- "${cur}"))
+    return 0
+  fi
+
+  # Command-specific completion rules.
+  case "${cmd}" in
+    mnemonic)
+      if [[ -z "${subcmd}" ]]; then
+        COMPREPLY=($(compgen -W "{{MNEMONIC_SUBS}}" -- "${cur}"))
+      fi
+      ;;
+
+    template)
+      if [[ -z "${subcmd}" ]]; then
+        COMPREPLY=($(compgen -W "{{TEMPLATE_SUBS}}" -- "${cur}"))
+      elif [[ "${subcmd}" == "list" || "${subcmd}" == "inspect" ]]; then
+        # template list/inspect <category> <template> [field]
+        # Position is computed relative to the subcommand token:
+        #   1 => category, 2 => template, 3 => field (inspect only)
+        local pos=$((cword - subcmd_idx))
+        if [[ $pos -eq 1 ]]; then
+          COMPREPLY=($(compgen -W "action transaction output lockingscript variable" -- "${cur}"))
+        elif [[ $pos -eq 2 ]]; then
+          local templates
+          templates=$(__xo_complete templates "${cur}")
+          if [[ -n "${templates}" ]]; then
+            while IFS= read -r line; do
+              COMPREPLY+=("$line")
+            done <<< "${templates}"
+          fi
+        elif [[ $pos -eq 3 && "${subcmd}" == "inspect" ]]; then
+          # Field names depend on both selected category and template.
+          local category="${words[subcmd_idx + 1]}"
+          local template_arg="${words[subcmd_idx + 2]}"
+          local fields
+          fields=$(__xo_complete fields "${category}" "${template_arg}" "${cur}")
+          if [[ -n "${fields}" ]]; then
+            while IFS= read -r line; do
+              COMPREPLY+=("$line")
+            done <<< "${fields}"
+          fi
+        fi
+      elif [[ "${subcmd}" == "set-default" ]]; then
+        # template set-default <template> <output> <role>
+        # We only complete the first positional argument (template) here.
+        local pos=$((cword - subcmd_idx))
+        if [[ $pos -eq 1 ]]; then
+          local templates
+          templates=$(__xo_complete templates "${cur}")
+          if [[ -n "${templates}" ]]; then
+            while IFS= read -r line; do
+              COMPREPLY+=("$line")
+            done <<< "${templates}"
+          fi
+        fi
+      fi
+      ;;
+
+    invitation)
+      if [[ -z "${subcmd}" ]]; then
+        COMPREPLY=($(compgen -W "{{INVITATION_SUBS}}" -- "${cur}"))
+      else
+        case "${subcmd}" in
+          create)
+            # invitation create <template> <action>
+            # The available actions depend on the selected template.
+            local pos=$((cword - subcmd_idx))
+            if [[ $pos -eq 1 ]]; then
+              local templates
+              templates=$(__xo_complete templates "${cur}")
+              if [[ -n "${templates}" ]]; then
+                while IFS= read -r line; do
+                  COMPREPLY+=("$line")
+                done <<< "${templates}"
+              fi
+            elif [[ $pos -eq 2 ]]; then
+              local template_arg="${words[subcmd_idx + 1]}"
+              local actions
+              actions=$(__xo_complete actions "${template_arg}" "${cur}")
+              if [[ -n "${actions}" ]]; then
+                while IFS= read -r line; do
+                  COMPREPLY+=("$line")
+                done <<< "${actions}"
+              fi
+            fi
+            ;;
+          append|sign|broadcast|requirements|inspect)
+            # These subcommands expect an invitation identifier as first arg.
+            local pos=$((cword - subcmd_idx))
+            if [[ $pos -eq 1 ]]; then
+              local invitations
+              invitations=$(__xo_complete invitations "${cur}")
+              if [[ -n "${invitations}" ]]; then
+                while IFS= read -r line; do
+                  COMPREPLY+=("$line")
+                done <<< "${invitations}"
+              fi
+            fi
+            ;;
+          import)
+            # File import path: delegate to bash's built-in file completion.
+            COMPREPLY=($(compgen -f -- "${cur}"))
+            ;;
+        esac
+      fi
+      ;;
+
+    resource)
+      if [[ -z "${subcmd}" ]]; then
+        COMPREPLY=($(compgen -W "{{RESOURCE_SUBS}}" -- "${cur}"))
+      elif [[ "${subcmd}" == "unreserve" ]]; then
+        # resource unreserve <txhash:vout>
+        # Suggest known reserved outpoints from the helper.
+        local pos=$((cword - subcmd_idx))
+        if [[ $pos -eq 1 ]]; then
+          local resources
+          resources=$(__xo_complete resources "${cur}")
+          if [[ -n "${resources}" ]]; then
+            while IFS= read -r line; do
+              COMPREPLY+=("$line")
+            done <<< "${resources}"
+          fi
+        fi
+      fi
+      ;;
+
+    settings)
+      if [[ -z "${subcmd}" ]]; then
+        COMPREPLY=($(compgen -W "show get set" -- "${cur}"))
+      elif [[ "${subcmd}" == "get" || "${subcmd}" == "set" ]]; then
+        local pos=$((cword - subcmd_idx))
+        if [[ $pos -eq 1 ]]; then
+          COMPREPLY=($(compgen -W "currency default-mnemonic" -- "${cur}"))
+        fi
+      fi
+      ;;
+
+    receive)
+      # receive <template> [output]
+      # Template is the first positional argument after `receive`.
+      local pos=$((cword - cmd_idx))
+      if [[ $pos -eq 1 ]]; then
+        local templates
+        templates=$(__xo_complete templates "${cur}")
+        if [[ -n "${templates}" ]]; then
+          while IFS= read -r line; do
+            COMPREPLY+=("$line")
+          done <<< "${templates}"
+        fi
+      fi
+      ;;
+
+    completions)
+      # Shell target for generating completion scripts.
+      if [[ -z "${subcmd}" ]]; then
+        COMPREPLY=($(compgen -W "bash zsh fish" -- "${cur}"))
+      fi
+      ;;
+  esac
+}
+
+# Register the completion function for the CLI binary.
+complete -F _{{FUNC_NAME}}_completions {{BIN_NAME}}

src/cli/autocomplete/scripts/fish.fish

@@ -0,0 +1,97 @@
+# ------------------------------------------------------------------------------
+# Fish completion template for {{BIN_NAME}}
+# ------------------------------------------------------------------------------
+# Installation:
+#   {{BIN_NAME}} completions fish | source
+#
+# This file is generated from a template. Placeholders (for example
+# `{{TOP_LEVEL_COMMANDS}}`) are replaced with concrete completion definitions.
+# ------------------------------------------------------------------------------
+
+# Fish offers file completion by default. Disable that globally first so command
+# words are preferred, then selectively re-enable `-F` where paths are expected.
+complete -c {{BIN_NAME}} -f
+
+# @description
+# Resolves and calls `xo-complete` for dynamic values (templates, invitations,
+# fields, etc.). We first try PATH, then a helper next to `{{BIN_NAME}}`.
+# @param $argv Arguments forwarded directly to xo-complete.
+function __{{FUNC_NAME}}_complete_dynamic
+  set -l xo_complete_bin ""
+  if command -q xo-complete
+    set xo_complete_bin xo-complete
+  else if command -q {{BIN_NAME}}
+    set xo_complete_bin (dirname (command -s {{BIN_NAME}}))/xo-complete
+  end
+  if test -n "$xo_complete_bin"
+    $xo_complete_bin $argv 2>/dev/null
+  end
+end
+
+# Global option flags available across top-level command contexts.
+complete -c {{BIN_NAME}} -s h -d "Show help"
+complete -c {{BIN_NAME}} -l help -d "Show help"
+complete -c {{BIN_NAME}} -s v -d "Verbose output"
+complete -c {{BIN_NAME}} -l verbose -d "Verbose output"
+complete -c {{BIN_NAME}} -s o -d "Output file"
+complete -c {{BIN_NAME}} -l output -d "Output file"
+complete -c {{BIN_NAME}} -l currency -d "Set fiat display currency"
+
+# Dynamic completion for `-m/--mnemonic-file`.
+complete -c {{BIN_NAME}} -s m -l mnemonic-file -xa '(__{{FUNC_NAME}}_complete_dynamic mnemonics)'
+
+# Top-level command registrations inserted by template expansion.
+{{TOP_LEVEL_COMMANDS}}
+
+# Static subcommand registrations inserted by template expansion.
+{{STATIC_SUBCOMMANDS}}
+
+# ---------------------------------------------------------------------------
+# Dynamic completions by command/subcommand.
+#
+# Fish condition notes:
+# - `__fish_seen_subcommand_from <name>` checks whether `<name>` exists in the
+#   current tokenized command line.
+# - `count (commandline -opc)` returns how many tokens were entered.
+#   We use this to infer positional argument index.
+# ---------------------------------------------------------------------------
+
+# invitation create <template> <action>
+# Position 3 => template argument.
+complete -c {{BIN_NAME}} -n "__fish_seen_subcommand_from invitation; and __fish_seen_subcommand_from create; and test (count (commandline -opc)) -eq 3" -xa '(__{{FUNC_NAME}}_complete_dynamic templates)'
+
+# invitation create <template> <action>
+# Position 4 => action argument, filtered by selected template token.
+complete -c {{BIN_NAME}} -n "__fish_seen_subcommand_from invitation; and __fish_seen_subcommand_from create; and test (count (commandline -opc)) -eq 4" -xa '(__{{FUNC_NAME}}_complete_dynamic actions (commandline -opc)[4])'
+
+# invitation append/sign/broadcast/requirements/inspect <invitation-id>
+# Position 3 => invitation identifier.
+complete -c {{BIN_NAME}} -n "__fish_seen_subcommand_from invitation; and __fish_seen_subcommand_from append; and test (count (commandline -opc)) -eq 3" -xa '(__{{FUNC_NAME}}_complete_dynamic invitations)'
+complete -c {{BIN_NAME}} -n "__fish_seen_subcommand_from invitation; and __fish_seen_subcommand_from sign; and test (count (commandline -opc)) -eq 3" -xa '(__{{FUNC_NAME}}_complete_dynamic invitations)'
+complete -c {{BIN_NAME}} -n "__fish_seen_subcommand_from invitation; and __fish_seen_subcommand_from broadcast; and test (count (commandline -opc)) -eq 3" -xa '(__{{FUNC_NAME}}_complete_dynamic invitations)'
+complete -c {{BIN_NAME}} -n "__fish_seen_subcommand_from invitation; and __fish_seen_subcommand_from requirements; and test (count (commandline -opc)) -eq 3" -xa '(__{{FUNC_NAME}}_complete_dynamic invitations)'
+complete -c {{BIN_NAME}} -n "__fish_seen_subcommand_from invitation; and __fish_seen_subcommand_from inspect; and test (count (commandline -opc)) -eq 3" -xa '(__{{FUNC_NAME}}_complete_dynamic invitations)'
+
+# invitation import <path>
+# Re-enable default filesystem completion for path argument.
+complete -c {{BIN_NAME}} -n "__fish_seen_subcommand_from invitation; and __fish_seen_subcommand_from import" -F
+
+# template list/inspect <category> <template> [field]
+# Position 3 => category, 4 => template, 5 => field (inspect only).
+complete -c {{BIN_NAME}} -n "__fish_seen_subcommand_from template; and __fish_seen_subcommand_from list; and test (count (commandline -opc)) -eq 3" -xa 'action transaction output lockingscript variable'
+complete -c {{BIN_NAME}} -n "__fish_seen_subcommand_from template; and __fish_seen_subcommand_from list; and test (count (commandline -opc)) -eq 4" -xa '(__{{FUNC_NAME}}_complete_dynamic templates)'
+complete -c {{BIN_NAME}} -n "__fish_seen_subcommand_from template; and __fish_seen_subcommand_from inspect; and test (count (commandline -opc)) -eq 3" -xa 'action transaction output lockingscript variable'
+complete -c {{BIN_NAME}} -n "__fish_seen_subcommand_from template; and __fish_seen_subcommand_from inspect; and test (count (commandline -opc)) -eq 4" -xa '(__{{FUNC_NAME}}_complete_dynamic templates)'
+complete -c {{BIN_NAME}} -n "__fish_seen_subcommand_from template; and __fish_seen_subcommand_from inspect; and test (count (commandline -opc)) -eq 5" -xa '(__{{FUNC_NAME}}_complete_dynamic fields (commandline -opc)[4] (commandline -opc)[5])'
+
+# template set-default <template> <output> <role>
+# Position 3 => template argument.
+complete -c {{BIN_NAME}} -n "__fish_seen_subcommand_from template; and __fish_seen_subcommand_from set-default; and test (count (commandline -opc)) -eq 3" -xa '(__{{FUNC_NAME}}_complete_dynamic templates)'
+
+# resource unreserve <txhash:vout>
+# Position 3 => outpoint to unreserve.
+complete -c {{BIN_NAME}} -n "__fish_seen_subcommand_from resource; and __fish_seen_subcommand_from unreserve; and test (count (commandline -opc)) -eq 3" -xa '(__{{FUNC_NAME}}_complete_dynamic resources)'
+
+# receive <template> [output]
+# Position 2 => template argument.
+complete -c {{BIN_NAME}} -n "__fish_seen_subcommand_from receive; and test (count (commandline -opc)) -eq 2" -xa '(__{{FUNC_NAME}}_complete_dynamic templates)'

src/cli/autocomplete/scripts/zsh.zsh

@@ -0,0 +1,216 @@
+# ------------------------------------------------------------------------------
+# Zsh completion template for {{BIN_NAME}}
+# ------------------------------------------------------------------------------
+# Installation:
+#   eval "$({{BIN_NAME}} completions zsh)"
+#
+# This file is generated from a template. Placeholders (for example
+# `{{MNEMONIC_SUBS}}`) are replaced with concrete command values.
+# ------------------------------------------------------------------------------
+
+# Prefer a helper on PATH; otherwise fall back to helper next to the CLI binary.
+# This keeps dynamic completion functional in both installed and portable layouts.
+__xo_complete_bin=""
+if (( $+commands[xo-complete] )); then
+  __xo_complete_bin="xo-complete"
+elif (( $+commands[{{BIN_NAME}}] )); then
+  __xo_complete_bin="${commands[{{BIN_NAME}}]:h}/xo-complete"
+fi
+
+# @description
+# Calls the dynamic helper while silencing helper stderr to avoid noisy
+# completion menus if helper lookup fails.
+# @param "$@" Arguments forwarded to xo-complete.
+__xo_complete() {
+  [[ -n "${__xo_complete_bin}" ]] && "${__xo_complete_bin}" "$@" 2>/dev/null
+}
+
+# @description
+# Main zsh completion dispatcher registered via `compdef`.
+# It resolves command context from `$words`/`$CURRENT` and serves:
+# - static command words via `compadd`
+# - dynamic values from `xo-complete`
+# - filesystem completions where file paths are expected
+_{{FUNC_NAME}}_completions() {
+  local -a commands
+  commands=({{COMMANDS}})
+
+  # If previous token is `-m/--mnemonic-file`, complete mnemonic sources.
+  if [[ "${words[CURRENT-1]}" == "-m" || "${words[CURRENT-1]}" == "--mnemonic-file" ]]; then
+    local mnemonics
+    mnemonics=("${(@f)$(__xo_complete mnemonics "${words[CURRENT]}")}")
+    if [[ ${#mnemonics[@]} -gt 0 ]]; then
+      compadd -- "${mnemonics[@]}"
+      return
+    fi
+  fi
+
+  # Option context: if current token starts with `-`, complete known options.
+  if [[ "${words[${CURRENT}]}" == -* ]]; then
+    compadd -- {{OPTIONS}}
+    return
+  fi
+
+  # Find first and second non-option tokens before the cursor.
+  # `cmd_idx` and `subcmd_idx` are used for positional argument calculations.
+  local cmd="" subcmd="" cmd_idx=0 subcmd_idx=0
+  for ((i=2; i < CURRENT; i++)); do
+    if [[ "${words[i]}" != -* ]]; then
+      if [[ -z "${cmd}" ]]; then
+        cmd="${words[i]}"
+        cmd_idx=$i
+      else
+        subcmd="${words[i]}"
+        subcmd_idx=$i
+        break
+      fi
+    fi
+  done
+
+  # No command token yet: offer top-level commands.
+  if [[ -z "${cmd}" ]]; then
+    compadd -- ${commands[@]}
+    return
+  fi
+
+  # Command-specific completion behavior.
+  case "${cmd}" in
+    mnemonic)
+      if [[ -z "${subcmd}" ]]; then
+        compadd -- {{MNEMONIC_SUBS}}
+      fi
+      ;;
+
+    template)
+      if [[ -z "${subcmd}" ]]; then
+        compadd -- {{TEMPLATE_SUBS}}
+      elif [[ "${subcmd}" == "list" || "${subcmd}" == "inspect" ]]; then
+        # template list/inspect <category> <template> [field]
+        # Relative positions from subcommand:
+        #   1 => category, 2 => template, 3 => field (inspect only)
+        local pos=$((CURRENT - subcmd_idx))
+        if [[ $pos -eq 1 ]]; then
+          compadd -- action transaction output lockingscript variable
+        elif [[ $pos -eq 2 ]]; then
+          local templates
+          templates=("${(@f)$(__xo_complete templates "${words[CURRENT]}")}")
+          if [[ ${#templates[@]} -gt 0 ]]; then
+            compadd -- "${templates[@]}"
+          fi
+        elif [[ $pos -eq 3 && "${subcmd}" == "inspect" ]]; then
+          # Field suggestions depend on selected category and template.
+          local category="${words[subcmd_idx + 1]}"
+          local template_arg="${words[subcmd_idx + 2]}"
+          local fields
+          fields=("${(@f)$(__xo_complete fields "${category}" "${template_arg}" "${words[CURRENT]}")}")
+          if [[ ${#fields[@]} -gt 0 ]]; then
+            compadd -- "${fields[@]}"
+          fi
+        fi
+      elif [[ "${subcmd}" == "set-default" ]]; then
+        # template set-default <template> <output> <role>
+        # First positional argument is template name.
+        local pos=$((CURRENT - subcmd_idx))
+        if [[ $pos -eq 1 ]]; then
+          local templates
+          templates=("${(@f)$(__xo_complete templates "${words[CURRENT]}")}")
+          if [[ ${#templates[@]} -gt 0 ]]; then
+            compadd -- "${templates[@]}"
+          fi
+        fi
+      fi
+      ;;
+
+    invitation)
+      if [[ -z "${subcmd}" ]]; then
+        compadd -- {{INVITATION_SUBS}}
+      else
+        case "${subcmd}" in
+          create)
+            # invitation create <template> <action>
+            # Action list is template-specific.
+            local pos=$((CURRENT - subcmd_idx))
+            if [[ $pos -eq 1 ]]; then
+              local templates
+              templates=("${(@f)$(__xo_complete templates "${words[CURRENT]}")}")
+              if [[ ${#templates[@]} -gt 0 ]]; then
+                compadd -- "${templates[@]}"
+              fi
+            elif [[ $pos -eq 2 ]]; then
+              local template_arg="${words[subcmd_idx + 1]}"
+              local actions
+              actions=("${(@f)$(__xo_complete actions "${template_arg}" "${words[CURRENT]}")}")
+              if [[ ${#actions[@]} -gt 0 ]]; then
+                compadd -- "${actions[@]}"
+              fi
+            fi
+            ;;
+          append|sign|broadcast|requirements|inspect)
+            # These subcommands take invitation ID as first argument.
+            local pos=$((CURRENT - subcmd_idx))
+            if [[ $pos -eq 1 ]]; then
+              local invitations
+              invitations=("${(@f)$(__xo_complete invitations "${words[CURRENT]}")}")
+              if [[ ${#invitations[@]} -gt 0 ]]; then
+                compadd -- "${invitations[@]}"
+              fi
+            fi
+            ;;
+          import)
+            # invitation import <path>: delegate to zsh file completion.
+            _files
+            ;;
+        esac
+      fi
+      ;;
+
+    resource)
+      if [[ -z "${subcmd}" ]]; then
+        compadd -- {{RESOURCE_SUBS}}
+      elif [[ "${subcmd}" == "unreserve" ]]; then
+        # resource unreserve <txhash:vout>
+        local pos=$((CURRENT - subcmd_idx))
+        if [[ $pos -eq 1 ]]; then
+          local resources
+          resources=("${(@f)$(__xo_complete resources "${words[CURRENT]}")}")
+          if [[ ${#resources[@]} -gt 0 ]]; then
+            compadd -- "${resources[@]}"
+          fi
+        fi
+      fi
+      ;;
+
+    settings)
+      if [[ -z "${subcmd}" ]]; then
+        compadd -- show get set
+      elif [[ "${subcmd}" == "get" || "${subcmd}" == "set" ]]; then
+        local pos=$((CURRENT - subcmd_idx))
+        if [[ $pos -eq 1 ]]; then
+          compadd -- currency default-mnemonic
+        fi
+      fi
+      ;;
+
+    receive)
+      # receive <template> [output]
+      local pos=$((CURRENT - cmd_idx))
+      if [[ $pos -eq 1 ]]; then
+        local templates
+        templates=("${(@f)$(__xo_complete templates "${words[CURRENT]}")}")
+        if [[ ${#templates[@]} -gt 0 ]]; then
+          compadd -- "${templates[@]}"
+        fi
+      fi
+      ;;
+
+    completions)
+      # Shell target for completion generation.
+      if [[ -z "${subcmd}" ]]; then
+        compadd -- bash zsh fish
+      fi
+      ;;
+  esac
+}
+
+# Register completion function for the executable name.
+compdef _{{FUNC_NAME}}_completions {{BIN_NAME}}

src/cli/cli-utils.ts

@@ -1,48 +0,0 @@
-import util from "node:util";
-
-/**
- * Text formatting utilities for the CLI.
- * 
- * Uses ANSI escape codes to format text.
- * 
- * AI Generated links:
- * @see https://en.wikipedia.org/wiki/ANSI_escape_code
- * @see https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters
- * @see https://en.wikipedia.org/wiki/ANSI_escape_code#Colors
- * @see https://en.wikipedia.org/wiki/ANSI_escape_code#Formatting
- * @see https://en.wikipedia.org/wiki/ANSI_escape_code#Cursor_movement
- * @see https://en.wikipedia.org/wiki/ANSI_escape_code#Screen_manipulation
- */
-
-const BOLD = "\x1b[1m";
-export const bold = (text: string) => `${BOLD}${text}${RESET}`;
-
-const DIM = "\x1b[2m";
-export const dim = (text: string) => `${DIM}${text}${RESET}`;
-
-const UNDERLINE = "\x1b[4m";
-export const underline = (text: string) => `${UNDERLINE}${text}${RESET}`;
-
-const INVERSE = "\x1b[7m";
-export const inverse = (text: string) => `${INVERSE}${text}${RESET}`;
-
-const HIDDEN = "\x1b[8m";
-export const hidden = (text: string) => `${HIDDEN}${text}${RESET}`;
-
-const STRIKETHROUGH = "\x1b[9m";
-export const strikethrough = (text: string) => `${STRIKETHROUGH}${text}${RESET}`;
-
-const RESET = "\x1b[0m";
-export const reset = (text: string) => `${RESET}${text}${RESET}`;
-
-export const formatObject = (obj: unknown) => {
-  return util.inspect(obj, {
-    depth: null,
-    colors: true,
-    compact: false
-  });
-};
-
-export const objectPrint = (obj: unknown) => {
-  console.log(formatObject(obj));
-};

src/cli/commands/index.ts

@@ -1,7 +1,8 @@
-export type { CommandDependencies } from "./types.js";
-
 export { handleMnemonicCommand, printMnemonicHelp } from "./mnemonic.js";
+export { handleSettingsCommand, printSettingsHelp } from "./settings.js";
 export { handleTemplateCommand, printTemplateHelp } from "./template.js";
 export { handleInvitationCommand, printInvitationHelp } from "./invitation.js";
 export { handleReceiveCommand, printReceiveHelp } from "./receive.js";
 export { handleResourceCommand, printResourceHelp } from "./resource.js";
+
+export * from "./types.js";

src/cli/commands/mnemonic.ts

@@ -1,73 +1,151 @@
-import { bold, dim } from "../cli-utils.js";
+import { bold, dim } from "../utils.js";
-import { listMnemonicFiles, createMnemonicFile, createMnemonicSeed } from "../mnemonic.js";
+import {
-import type { CommandDependencies } from "./types.js";
+  listMnemonicFiles,
+  createMnemonicFile,
+  createMnemonicSeed,
+  loadMnemonic,
+} from "../mnemonic.js";
+import type { BaseCommandDependencies, CommandIO } from "./types.js";
+import { CommandError } from "./types.js";
 
 /**
  * Prints the help message for the mnemonic command
  */
-export const printMnemonicHelp = () => {
+export const printMnemonicHelp = (io: CommandIO): void => {
-  console.log(
+  io.out(
-`
+    `
 ${bold("Usage:")} xo-cli mnemonic <sub-command>
 
 ${bold("Sub-commands:")}
     - create <mnemonic-seed> ${dim("Create a new mnemonic file")}
     - list ${dim("List all mnemonic files")}
+    - import <mnemonic-seed> ${dim("Import a mnemonic seed from a file")}
+    - expose <mnemonic-file> ${dim("Expose a mnemonic file")}
 
 ${bold("Options:")}
     -o --output <output-filename> ${dim("Output filename for the mnemonic file")}
     -h --help ${dim("Show this help message")}
-`);
+`,
+  );
 };
 
 /**
  * Handles the mnemonic command.
+ * Throws CommandError on failure, returns result data on success.
  * @param deps - The command dependencies.
  * @param args - Positional args after the command name, e.g. ["create"] or ["import", "page", "pencil", ...].
  * @param options - Parsed option flags, e.g. { output: "mnemonic.txt" }.
  */
-export const handleMnemonicCommand = async (deps: Omit<CommandDependencies, "app">, args: string[], options: Record<string, string>): Promise<void> => {
+export const handleMnemonicCommand = async (
+  deps: BaseCommandDependencies,
+  args: string[],
+  options: Record<string, string>,
+): Promise<{ savedAs?: string; count?: number; mnemonic?: string }> => {
+  // Get the sub-command from the arguments
   const subCommand = args[0];
+  const { mnemonicsDir } = deps.paths;
 
+  // If no sub-command is provided, print the help message and throw an error
   if (!subCommand) {
-    deps.verboseLogger("No sub-command provided");
+    deps.io.verbose("No sub-command provided");
-    printMnemonicHelp();
+    printMnemonicHelp(deps.io);
-    return;
+    throw new CommandError(
+      "mnemonic.subcommand.missing",
+      "No sub-command provided",
+    );
   }
 
+  // Handle the sub-command
   switch (subCommand) {
     case "create": {
+      // Create a new mnemonic seed
       const mnemonicSeed = createMnemonicSeed();
-      await createMnemonicFile(mnemonicSeed, options["output"]);
 
-      console.log(`Mnemonic file created: ${options["output"]} (${mnemonicSeed})`);
+      // Create a new mnemonic file
-      break;
+      const savedAs = createMnemonicFile(
+        mnemonicsDir,
+        mnemonicSeed,
+        options["output"],
+      );
+
+      // Display the mnemonic file to the user
+      deps.io.out(`Mnemonic file created: ${savedAs} (${mnemonicSeed})`);
+      return { savedAs };
     }
 
     case "import": {
-      // The mnemonic seed words are all the positional args after the sub-command
+      // Get the mnemonic seed from the arguments
       const mnemonicSeed = args.slice(1).join(" ");
 
+      // If no mnemonic seed is provided, print the help message and throw an error
       if (!mnemonicSeed) {
-        deps.verboseLogger("No mnemonic seed provided");
+        deps.io.verbose("No mnemonic seed provided");
-        printMnemonicHelp();
+        printMnemonicHelp(deps.io);
-        return;
+        throw new CommandError(
+          "mnemonic.import.seed_missing",
+          "No mnemonic seed provided",
+        );
       }
 
-      deps.verboseLogger(`Mnemonic seed: ${mnemonicSeed}`);
+      // Create a new mnemonic file
-      await createMnemonicFile(mnemonicSeed, options["output"]);
+      deps.io.verbose(`Mnemonic seed: ${mnemonicSeed}`);
-      break;
+      const savedAs = createMnemonicFile(
+        mnemonicsDir,
+        mnemonicSeed,
+        options["output"],
+      );
+
+      // Display the mnemonic file to the user
+      deps.io.out(`Mnemonic file created: ${savedAs}`);
+      return { savedAs };
     }
 
     case "list": {
-      const mnemonicFiles = listMnemonicFiles();
+      // List all the mnemonic files
-      console.log(mnemonicFiles.join('\n'));
+      const mnemonicFiles = listMnemonicFiles(mnemonicsDir);
-      break;
+      deps.io.out(mnemonicFiles.join("\n"));
+
+      // Return the number of mnemonic files
+      return { count: mnemonicFiles.length };
+    }
+
+    case "expose": {
+      // Get the mnemonic file from the arguments
+      const mnemonicFile = args[1];
+
+      // If no mnemonic file is provided, print the help message and throw an error
+      if (!mnemonicFile) {
+        deps.io.verbose("No mnemonic file provided");
+        printMnemonicHelp(deps.io);
+        throw new CommandError(
+          "mnemonic.expose.file_missing",
+          "No mnemonic file provided",
+        );
+      }
+
+      // Try to load the mnemonic file
+      try {
+        const mnemonic = loadMnemonic(mnemonicsDir, mnemonicFile);
+        deps.io.out(mnemonic);
+
+        // Return the mnemonic
+        return { mnemonic };
+      } catch (error) {
+        // If the mnemonic file is not found, print an error and throw an error
+        throw new CommandError(
+          "mnemonic.expose.file_not_found",
+          `Mnemonic file not found: ${mnemonicFile}`,
+        );
+      }
     }
 
     default:
-      console.error(`Unknown sub-command: ${subCommand}`);
+      // If the sub-command is not found, print an error and throw an error
-      printMnemonicHelp();
+      deps.io.err(`Unknown sub-command: ${subCommand}`);
-      return;
+      printMnemonicHelp(deps.io);
+      throw new CommandError(
+        "mnemonic.subcommand.unknown",
+        `Unknown sub-command: ${subCommand}`,
+      );
   }
 };

src/cli/commands/receive.ts

@@ -1,17 +1,18 @@
-import { existsSync, readFileSync } from "fs";
-import path from "path";
 import { generateTemplateIdentifier } from "@xo-cash/engine";
 import { hexToBin, lockingBytecodeToCashAddress } from "@bitauth/libauth";
 
-import { bold, dim } from "../cli-utils.js";
+import { bold, dim } from "../utils.js";
-import type { CommandDependencies } from "./types.js";
+import type { CommandDependencies, CommandIO } from "./types.js";
+import { CommandError } from "./types.js";
+
+import { resolveTemplate } from "../utils.js";
 
 /**
  * Prints the help message for the receive command
  */
-export const printReceiveHelp = () => {
+export const printReceiveHelp = (io: CommandIO): void => {
-  console.log(
+  io.out(
-`
+    `
 ${bold("Usage:")} xo-cli receive <template-file> <output-identifier> [role-identifier]
 
 ${bold("Description:")}
@@ -24,41 +25,49 @@ ${bold("Arguments:")}
 
 ${bold("Options:")}
     -h --help ${dim("Show this help message")}
-`);
+`,
+  );
 };
 
 /**
  * Command which creates a single-use address/lockingScript for a given template and role.
+ * Throws CommandError on failure, returns address data on success.
+ *
  * @param deps - The command dependencies.
  * @param args - Positional args after the command name, e.g. ["template.json", "receiveOutput", "receiver"].
  * @param options - Parsed option flags.
+ * @returns The address data.
+ * @throws CommandError if the command fails.
  */
-export const handleReceiveCommand = async (deps: CommandDependencies, args: string[], options: Record<string, string>): Promise<void> => {
+export const handleReceiveCommand = async (
-  const templateFile = args[0];
+  deps: CommandDependencies,
+  args: string[],
+  _options: Record<string, string>,
+): Promise<{ address: string }> => {
+  // Get the template query, output identifier, and role identifier from the arguments
+  const templateQuery = args[0];
   const outputIdentifier = args[1];
   const roleIdentifier = args[2];
 
-  deps.verboseLogger(`Receive args - template: ${templateFile}, output: ${outputIdentifier}, role: ${roleIdentifier}`);
+  // Log the receive args
+  deps.io.verbose(
+    `Receive args - template: ${templateQuery}, output: ${outputIdentifier}, role: ${roleIdentifier}`,
+  );
 
-  if (!templateFile || !outputIdentifier) {
+  // If no template query or output identifier is provided, print the help message and throw an error
-    deps.verboseLogger("Missing required arguments");
+  if (!templateQuery || !outputIdentifier) {
-    printReceiveHelp();
+    deps.io.verbose("Missing required arguments");
-    return;
+    printReceiveHelp(deps.io);
+    throw new CommandError(
+      "receive.arguments.missing",
+      "Missing required arguments",
+    );
   }
 
   // Resolve and read the template file
-  const templatePath = path.resolve(`${process.cwd()}/${templateFile}`);
+  const template = await resolveTemplate(deps, templateQuery);
-  deps.verboseLogger(`Template path: ${templatePath}`);
+  const templateIdentifier = generateTemplateIdentifier(template);
-
+  deps.io.verbose(`Template identifier: ${templateIdentifier}`);
-  if (!existsSync(templatePath)) {
-    console.error(`Template file does not exist: ${templatePath}`);
-    printReceiveHelp();
-    return;
-  }
-
-  const template = readFileSync(templatePath, "utf8");
-  const templateIdentifier = generateTemplateIdentifier(JSON.parse(template));
-  deps.verboseLogger(`Template identifier: ${templateIdentifier}`);
 
   // Generate the locking bytecode (returned as a hex string)
   const lockingBytecodeHex = await deps.app.engine.generateLockingBytecode(
@@ -66,15 +75,22 @@ export const handleReceiveCommand = async (deps: CommandDependencies, args: stri
     outputIdentifier,
     roleIdentifier,
   );
-  deps.verboseLogger(`Locking bytecode hex: ${lockingBytecodeHex}`);
+  deps.io.verbose(`Locking bytecode hex: ${lockingBytecodeHex}`);
 
   // Convert the locking bytecode to a BCH cash address
-  const result = lockingBytecodeToCashAddress({ bytecode: hexToBin(lockingBytecodeHex), prefix: 'bitcoincash' });
+  const result = lockingBytecodeToCashAddress({
+    bytecode: hexToBin(lockingBytecodeHex),
+    prefix: "bitcoincash",
+  });
 
-  if (typeof result === 'string') {
+  if (typeof result === "string") {
-    console.error(`Failed to encode address: ${result}`);
+    deps.io.err(`Failed to encode address: ${result}`);
-    return;
+    throw new CommandError(
+      "receive.address.encode_failed",
+      `Failed to encode address: ${result}`,
+    );
   }
 
-  console.log(result.address);
+  deps.io.out(result.address);
+  return { address: result.address };
 };

src/cli/commands/resource.ts

@@ -1,14 +1,16 @@
 import { hexToBin } from "@bitauth/libauth";
 
-import { bold, dim } from "../cli-utils.js";
+import { bold, dim } from "../utils.js";
-import type { CommandDependencies } from "./types.js";
+import type { CommandDependencies, CommandIO } from "./types.js";
+import type { UnspentOutputData } from "@xo-cash/state";
+import { CommandError } from "./types.js";
 
 /**
  * Prints the help message for the resource command.
  */
-export const printResourceHelp = () => {
+export const printResourceHelp = (io: CommandIO): void => {
-  console.log(
+  io.out(
-`
+    `
 ${bold("Usage:")} xo-cli resource <sub-command>
 
 ${bold("Sub-commands:")}
@@ -17,129 +19,216 @@ ${bold("Sub-commands:")}
     - list all              ${dim("List all resources (reserved + unreserved)")}
     - unreserve <txhash:vout> ${dim("Unreserve a specific UTXO")}
     - unreserve-all         ${dim("Unreserve all reserved UTXOs")}
-  `);
+  `,
+  );
 };
 
 /**
  * Formats a single UTXO for display, optionally including reservation info.
  */
-function formatResource(resource: { outpointTransactionHash: string; outpointIndex: number; valueSatoshis: number; outputIdentifier: string; minedAtHeight: number; reserved?: boolean; invitationIdentifier?: string }, showReserved = false): string {
+function formatResource(
-  const outpoint = bold(`${resource.outpointTransactionHash}:${resource.outpointIndex}`);
+  resource: UnspentOutputData,
+  showReserved = false,
+): string {
+  // Format the outpoint
+  const outpoint = bold(
+    `${resource.outpointTransactionHash}:${resource.outpointIndex}`,
+  );
+
+  // Format the value
   const value = dim(`${resource.valueSatoshis} sats`);
+
+  // Format the output
   const output = dim(resource.outputIdentifier);
+  
+  // Format the height
   const height = dim(`(height ${resource.minedAtHeight})`);
 
-  if (showReserved && resource.reserved) {
+  // If the resource is reserved, format the reservation info
-    const inv = dim(`reserved for ${resource.invitationIdentifier}`);
+  if (showReserved && resource.reservedBy) {
+    const inv = dim(`reserved for ${resource.reservedBy}`);
     return `${outpoint} ${value} ${output} ${height} ${inv}`;
   }
 
+  // Otherwise, format the resource without reservation info
   return `${outpoint} ${value} ${output} ${height}`;
 }
 
 /**
  * Handles the resource command.
+ * Throws CommandError on failure, returns result data on success.
  * @param deps - The command dependencies.
  * @param args - Positional args after the command name, e.g. ["list"].
  * @param options - Parsed option flags.
  */
-export const handleResourceCommand = async (deps: CommandDependencies, args: string[], options: Record<string, string>): Promise<void> => {
+export const handleResourceCommand = async (
+  deps: CommandDependencies,
+  args: string[],
+  _options: Record<string, string>,
+): Promise<{ count?: number }> => {
   const subCommand = args[0];
-  deps.verboseLogger(`Resource sub-command: ${subCommand}`);
+  deps.io.verbose(`Resource sub-command: ${subCommand}`);
 
+  // If no sub-command is provided, print the help message and throw an error
   if (!subCommand) {
-    deps.verboseLogger("No sub-command provided");
+    deps.io.verbose("No sub-command provided");
-    printResourceHelp();
+    printResourceHelp(deps.io);
-    return;
+    throw new CommandError(
+      "resource.subcommand.missing",
+      "No sub-command provided",
+    );
   }
 
+  // Handle the sub-command
   switch (subCommand) {
     case "list": {
-      const qualifier = args[1]; // "reserved", "all", or undefined (defaults to unreserved)
+      // Get the qualifier from the arguments - This could be "reserved", "all", or omitted (which defaults to "unreserved")
+      const qualifier = args[1];
+
+      // List all the unspent outputs data
       const allResources = await deps.app.engine.listUnspentOutputsData();
 
       let filtered;
+      // If the qualifier is "reserved", return only the reserved resources
       if (qualifier === "reserved") {
-        filtered = allResources.filter((r) => r.reserved);
+        filtered = allResources.filter((r) => r.reservedBy);
-      } else if (qualifier === "all") {
+      }
+      // If the qualifier is "all", return all the resources
+      else if (qualifier === "all") {
         filtered = allResources;
-      } else {
+      }
-        // Default: show only unreserved (selectable) resources
+      // If the qualifier is not "reserved" or "all", return only the unreserved resources
-        filtered = allResources.filter((r) => !r.reserved);
+      else {
+        filtered = allResources.filter((r) => !r.reservedBy);
       }
 
+      // If no resources are found, print a message and return 0
       if (filtered.length === 0) {
-        console.log(dim("No resources found."));
+        deps.io.out(dim("No resources found."));
-        return;
+        return { count: 0 };
       }
 
+      // Format the resources into a list of strings that we can display to the user
       const showReserved = qualifier === "all" || qualifier === "reserved";
-      const formattedResources = filtered.map((r) => formatResource(r, showReserved));
+      const formattedResources = filtered.map((r) =>
-      console.log(formattedResources.join("\n"));
+        formatResource(r, showReserved),
-      console.log(`Total satoshis: ${filtered.reduce((acc, r) => acc + r.valueSatoshis, 0)}`);
+      );
-      console.log(`Total resources: ${filtered.length}`);
+
-      break;
+      // Display the resources to the user
+      deps.io.out(formattedResources.join("\n"));
+
+      // Display the total satoshis
+      deps.io.out(
+        `Total satoshis: ${filtered.reduce((acc, r) => acc + r.valueSatoshis, 0)}`,
+      );
+
+      // Display the total resources
+      deps.io.out(`Total resources: ${filtered.length}`);
+      return { count: filtered.length };
     }
 
     case "unreserve": {
+      // Get the outpoint from the arguments
       const outpointArg = args[1];
+
+      // If no outpoint is provided, print a message and throw an error
       if (!outpointArg) {
-        console.error("Please provide a UTXO in <txhash>:<vout> format.");
+        deps.io.err("Please provide a UTXO in <txhash>:<vout> format.");
-        printResourceHelp();
+        printResourceHelp(deps.io);
-        return;
+        throw new CommandError(
+          "resource.unreserve.outpoint_missing",
+          "Please provide a UTXO in <txhash>:<vout> format.",
+        );
       }
 
+      // Get the separator index
       const separatorIndex = outpointArg.lastIndexOf(":");
       if (separatorIndex === -1) {
-        console.error(`Invalid format "${outpointArg}". Expected <txhash>:<vout>.`);
+        // If the separator index is -1 (not found), print a message and throw an error
-        return;
+        deps.io.err(
+          `Invalid format "${outpointArg}". Expected <txhash>:<vout>.`,
+        );
+        throw new CommandError(
+          "resource.unreserve.outpoint_invalid",
+          `Invalid format "${outpointArg}". Expected <txhash>:<vout>.`,
+        );
       }
 
+      // Get the tx hash and vout
       const txHash = outpointArg.substring(0, separatorIndex);
       const vout = parseInt(outpointArg.substring(separatorIndex + 1), 10);
+
+      // If the tx hash or vout is not a string or isNaN, print a message and throw an error
       if (!txHash || isNaN(vout)) {
-        console.error(`Invalid format "${outpointArg}". Expected <txhash>:<vout>.`);
+        deps.io.err(
-        return;
+          `Invalid format "${outpointArg}". Expected <txhash>:<vout>.`,
+        );
+        throw new CommandError(
+          "resource.unreserve.outpoint_invalid",
+          `Invalid format "${outpointArg}". Expected <txhash>:<vout>.`,
+        );
       }
 
-      // Look up the UTXO to get its invitation identifier (required by the engine).
+      // Gather all of our resources
       const allResources = await deps.app.engine.listUnspentOutputsData();
+
+      // Find the target resource
       const target = allResources.find(
         (r) => r.outpointTransactionHash === txHash && r.outpointIndex === vout,
       );
 
+      // If the target resource is not found, print a message and throw an error
       if (!target) {
-        console.error(`UTXO not found: ${txHash}:${vout}`);
+        deps.io.err(`UTXO not found: ${txHash}:${vout}`);
-        return;
+        throw new CommandError(
+          "resource.unreserve.utxo_missing",
+          `UTXO not found: ${txHash}:${vout}`,
+        );
       }
 
-      if (!target.reserved) {
+      // If the target resource is not reserved, print a message and return
-        console.log(dim("UTXO is not reserved. Nothing to do."));
+      if (!target.reservedBy) {
-        return;
+        deps.io.out(dim("UTXO is not reserved. Nothing to do."));
+        return {};
       }
 
+      // Unreserve the resources
       await deps.app.engine.unreserveResources(
         [{ outpointTransactionHash: hexToBin(txHash), outpointIndex: vout }],
-        target.invitationIdentifier,
+        target.reservedBy,
       );
-      console.log(`Unreserved ${bold(`${txHash}:${vout}`)} (was reserved for ${target.invitationIdentifier})`);
+
-      break;
+      deps.io.out(
+        `Unreserved ${bold(`${txHash}:${vout}`)} (was reserved for ${target.reservedBy})`,
+      );
+      
+      // TODO: What do I want to return here?
+      return {};
     }
 
     case "unreserve-all": {
+      // Unreserve all the resources
       const count = await deps.app.unreserveAllResources();
+
+      // If no resources are reserved, print a message and return
       if (count === 0) {
-        console.log(dim("No reserved resources to unreserve."));
+        deps.io.out(dim("No reserved resources to unreserve."));
-      } else {
-        console.log(`Unreserved ${bold(String(count))} resource(s).`);
       }
-      break;
+      // If some resources were unreserved, print a message and return the count
+      else {
+        deps.io.out(`Unreserved ${bold(String(count))} resource(s).`);
+      }
+
+      return { count };
     }
 
     default: {
-      deps.verboseLogger(`Unknown resource sub-command: ${subCommand}`);
+      deps.io.verbose(`Unknown resource sub-command: ${subCommand}`);
-      printResourceHelp();
+      printResourceHelp(deps.io);
-      return;
+      throw new CommandError(
+        "resource.subcommand.unknown",
+        `Unknown resource sub-command: ${subCommand}`,
+      );
     }
   }
 };

src/cli/commands/settings.ts

@@ -0,0 +1,131 @@
+import { SettingsService } from "../../services/settings.js";
+import { formatObject } from "../utils.js";
+import type { BaseCommandDependencies, CommandIO } from "./types.js";
+import { CommandError } from "./types.js";
+
+/**
+ * Prints help text for the settings command.
+ */
+export const printSettingsHelp = (io: CommandIO): void => {
+  io.out(`Settings Command Help:
+Commands:
+  settings show
+  settings get <currency|default-mnemonic>
+  settings set <currency|default-mnemonic> <value>
+
+Examples:
+  xo-cli settings show
+  xo-cli settings get currency
+  xo-cli settings set currency AUD
+  xo-cli settings set default-mnemonic mnemonic-main`);
+};
+
+/**
+ * Supported settings keys exposed on the CLI.
+ */
+type SettingsKey = "currency" | "default-mnemonic";
+
+/**
+ * Normalizes user input to one of the supported settings keys.
+ */
+function parseSettingsKey(input: string | undefined): SettingsKey | null {
+  if (!input) {
+    return null;
+  }
+
+  const normalized = input.trim().toLowerCase();
+  if (normalized === "currency") {
+    return "currency";
+  }
+  if (normalized === "default-mnemonic" || normalized === "defaultMnemonic") {
+    return "default-mnemonic";
+  }
+  return null;
+}
+
+/**
+ * Handles `xo-cli settings` commands.
+ *
+ * This command intentionally does not require wallet initialization so users can
+ * configure currency/default mnemonic without passing `-m`.
+ */
+export const handleSettingsCommand = async (
+  deps: BaseCommandDependencies,
+  args: string[],
+  options: Record<string, string>,
+): Promise<Record<string, unknown>> => {
+  const settings = new SettingsService(deps.paths.walletConfigPath);
+
+  // settings show (default if no subcommand)
+  const subCommand = args[0] ?? "show";
+  if (subCommand === "help" || options["help"] === "true") {
+    printSettingsHelp(deps.io);
+    return {};
+  }
+
+  switch (subCommand) {
+    case "show": {
+      const snapshot = settings.getSettings();
+      deps.io.out(formatObject(snapshot));
+      return snapshot;
+    }
+
+    case "get": {
+      const key = parseSettingsKey(args[1]);
+      if (!key) {
+        printSettingsHelp(deps.io);
+        throw new CommandError(
+          "settings.get.key_missing",
+          'Missing or invalid key. Expected "currency" or "default-mnemonic".',
+        );
+      }
+
+      const value =
+        key === "currency"
+          ? settings.getCurrency()
+          : settings.getDefaultMnemonic() ?? "";
+      deps.io.out(value);
+      return { key, value };
+    }
+
+    case "set": {
+      const key = parseSettingsKey(args[1]);
+      if (!key) {
+        printSettingsHelp(deps.io);
+        throw new CommandError(
+          "settings.set.key_missing",
+          'Missing or invalid key. Expected "currency" or "default-mnemonic".',
+        );
+      }
+
+      const rawValue = args.slice(2).join(" ").trim();
+      if (!rawValue) {
+        printSettingsHelp(deps.io);
+        throw new CommandError(
+          "settings.set.value_missing",
+          "Missing value for settings set command.",
+        );
+      }
+
+      if (key === "currency") {
+        settings.setCurrency(rawValue);
+        const currency = settings.getCurrency();
+        deps.io.out(`Updated currency: ${currency}`);
+        return { key, value: currency };
+      }
+
+      settings.setDefaultMnemonic(rawValue);
+      const defaultMnemonic = settings.getDefaultMnemonic() ?? "";
+      deps.io.out(`Updated default-mnemonic: ${defaultMnemonic}`);
+      return { key, value: defaultMnemonic };
+    }
+
+    default: {
+      printSettingsHelp(deps.io);
+      throw new CommandError(
+        "settings.subcommand.unknown",
+        `Unknown settings command: ${subCommand}`,
+      );
+    }
+  }
+};

src/cli/commands/template.ts

@@ -3,16 +3,18 @@ import path from "path";
 import { generateTemplateIdentifier } from "@xo-cash/engine";
 import type { XOTemplate } from "@xo-cash/types";
 
-import { bold, dim, formatObject, objectPrint } from "../cli-utils.js";
+import { bold, dim, formatObject } from "../utils.js";
 import { resolveTemplateReferences } from "../../utils/templates.js";
-import type { CommandDependencies } from "./types.js";
+import type { CommandDependencies, CommandIO } from "./types.js";
+import { CommandError } from "./types.js";
+import { resolveTemplate } from "../utils.js";
 
 /**
  * Prints the help message for the template command
  */
-export const printTemplateHelp = () => {
+export const printTemplateHelp = (io: CommandIO): void => {
-  console.log(
+  io.out(
-`
+    `
 ${bold("Usage:")} xo-cli template <sub-command>
 
 ${bold("Sub-commands:")}
@@ -21,91 +23,170 @@ ${bold("Sub-commands:")}
     - list <category> <identifier> ${dim("List all options of the field type in a template")}
     - inspect <category> <identifier> <field> ${dim("Inspect a field in a template")}
     - set-default <template-file> <output-identifier> <role-identifier> ${dim("Set the default template")}
-  `);
+  `,
+  );
 };
 
 /**
  * Handles the template list command.
+ * Throws CommandError on failure, returns result data on success.
  * @param deps - The command dependencies.
  * @param args - Positional args after the command name, e.g. ["list", "action"] or ["list", "action", "1234567890"].
  */
-export const handleTemplateListCommand = async (deps: CommandDependencies, args: string[]): Promise<void> => {
+export const handleTemplateListCommand = async (
+  deps: CommandDependencies,
+  args: string[],
+): Promise<{ count?: number }> => {
+  // Get the template category from the arguments - This could be "action", "transaction", "output", "lockingscript", or "variable"
   const templateCategory = args[0];
-  deps.verboseLogger(`Template list category: ${templateCategory}`);
+  deps.io.verbose(`Template list category: ${templateCategory}`);
 
-  // If no category was provided to list, we assume its listing out the templates
+  // If no template category is provided, list all the imported templates
   if (!templateCategory) {
+    // List all the imported templates
     const templates = await deps.app.engine.listImportedTemplates();
-    const formattedTemplates = templates.map((template: XOTemplate) => `${bold(generateTemplateIdentifier(template))} - ${dim(template.name)} ${dim(template.description)}`);
+
-    console.log(formattedTemplates.join('\n'));
+    // Format the templates into a list of strings that we can display to the user
-    return;
+    const formattedTemplates = templates.map(
+      (template: XOTemplate) =>
+        `${bold(generateTemplateIdentifier(template))} - ${dim(template.name)} ${dim(template.description)}`,
+    );
+
+    // Display the templates to the user
+    deps.io.out(formattedTemplates.join("\n"));
+
+    // Return the number of templates
+    return { count: templates.length };
   }
 
-  // Extract the template identifier from the positional args
+  // Get the template identifier from the arguments
   const templateIdentifier = args[1];
-  deps.verboseLogger(`Template identifier: ${templateIdentifier}`);
+  deps.io.verbose(`Template identifier: ${templateIdentifier}`);
 
+  // If no template identifier is provided, print a message and throw an error
   if (!templateIdentifier) {
-    console.error("No template identifier provided");
+    deps.io.err("No template identifier provided");
-    return;
+    throw new CommandError(
+      "template.list.identifier_missing",
+      "No template identifier provided",
+    );
   }
 
-  // Get the template from the engine
+  // Get the raw template from the engine
   const rawTemplate = await deps.app.engine.getTemplate(templateIdentifier);
+
+  // If the raw template is not found, print a message and throw an error
   if (!rawTemplate) {
-    console.error(`No template found: ${templateIdentifier}`);
+    deps.io.err(`No template found: ${templateIdentifier}`);
-    return;
+    throw new CommandError(
+      "template.list.not_found",
+      `No template found: ${templateIdentifier}`,
+    );
   }
 
-  // Resolve the template references
+  // Resolve the template deeply - Deeply nested objects instead of shallow objects referencing keys at the top level.
+  // Reduces the load of having to call multiple lookups just to get some resolved value like the outputIdentifer that comes from calling an action.
   const template = await resolveTemplateReferences(rawTemplate);
-  deps.verboseLogger(`Template: ${formatObject(template)}`);
+  deps.io.verbose(`Template: ${formatObject(template)}`);
 
-  // List the templates in the category
+  // Handle the template category
   switch (templateCategory) {
     case "action": {
+      // Get the actions from the template
       const actions = template.actions;
-      const formattedActions = Object.entries(actions).map(([actionIdentifier, action]) => `${bold(actionIdentifier)} ${dim(action.name)} ${dim(action.description)}`);
+
-      console.log(formattedActions.join('\n'));
+      // Format the actions into a list of strings that we can display to the user
-      break;
+      const formattedActions = Object.entries(actions).map(
+        ([actionIdentifier, action]) =>
+          `${bold(actionIdentifier)} ${dim(action.name)} ${dim(action.description)}`,
+      );
+
+      // Display the actions to the user
+      deps.io.out(formattedActions.join("\n"));
+
+      // Return the number of actions
+      return {};
     }
     case "transaction": {
+      // Get the transactions from the template
       const transactions = template.transactions;
-      const formattedTransactions = Object.entries(transactions).map(([transactionIdentifier, transaction]) => `${bold(transactionIdentifier)} ${dim(transaction.name)} ${dim(transaction.description)}`);
+
-      console.log(formattedTransactions.join('\n'));
+      // Format the transactions into a list of strings that we can display to the user
-      break;
+      const formattedTransactions = Object.entries(transactions).map(
+        ([transactionIdentifier, transaction]) =>
+          `${bold(transactionIdentifier)} ${dim(transaction.name)} ${dim(transaction.description)}`,
+      );
+
+      // Display the transactions to the user
+      deps.io.out(formattedTransactions.join("\n"));
+
+      // Return the number of transactions
+      return {};
     }
     case "output": {
+      // Get the outputs from the template
       const outputs = template.outputs;
-      const formattedOutputs = Object.entries(outputs).map(([outputIdentifier, output]) => `${bold(outputIdentifier)} ${dim(output.name)} ${dim(output.description)}`);
+
-      console.log(formattedOutputs.join('\n'));
+      // Format the outputs into a list of strings that we can display to the user
-      break;
+      const formattedOutputs = Object.entries(outputs).map(
+        ([outputIdentifier, output]) =>
+          `${bold(outputIdentifier)} ${dim(output.name)} ${dim(output.description)}`,
+      );
+
+      // Display the outputs to the user
+      deps.io.out(formattedOutputs.join("\n"));
+
+      // Return the number of outputs
+      return {};
     }
     case "lockingscript": {
+      // Get the lockingscripts from the template
       const lockingscripts = template.lockingScripts;
-      const formattedLockingscripts = Object.entries(lockingscripts).map(([lockingScriptIdentifier, lockingScript]) => `${bold(lockingScriptIdentifier)} ${dim(lockingScript.name)} ${dim(lockingScript.description)}`);
+
-      console.log(formattedLockingscripts.join('\n'));
+      // Format the lockingscripts into a list of strings that we can display to the user
-      break;
+      const formattedLockingscripts = Object.entries(lockingscripts).map(
+        ([lockingScriptIdentifier, lockingScript]) =>
+          `${bold(lockingScriptIdentifier)} ${dim(lockingScript.name)} ${dim(lockingScript.description)}`,
+      );
+
+      // Display the lockingscripts to the user
+      deps.io.out(formattedLockingscripts.join("\n"));
+
+      // Return the number of lockingscripts
+      return {};
     }
     case "variable": {
+      // Get the variables from the template
       const variables = template.variables || {};
-      const formattedVariables = Object.entries(variables).map(([variableIdentifier, variable]) => `${bold(variableIdentifier)} ${dim(variable.name)} ${dim(variable.description)}`);
+
-      console.log(formattedVariables.join('\n'));
+      // Format the variables into a list of strings that we can display to the user
-      break;
+      const formattedVariables = Object.entries(variables).map(
+        ([variableIdentifier, variable]) =>
+          `${bold(variableIdentifier)} ${dim(variable.name)} ${dim(variable.description)}`,
+      );
+
+      // Display the variables to the user
+      deps.io.out(formattedVariables.join("\n"));
+
+      // Return the number of variables
+      return {};
     }
     default: {
-      deps.verboseLogger(`Unknown template category: ${templateCategory}`);
+      deps.io.verbose(`Unknown template category: ${templateCategory}`);
-      return;
+      throw new CommandError(
+        "template.list.category_unknown",
+        `Unknown template category: ${templateCategory}`,
+      );
     }
   }
-}
+};
 
 /**
  * Prints the help message for the template inspect command
  */
-export const printTemplateInspectHelp = () => {
+export const printTemplateInspectHelp = (io: CommandIO): void => {
-  console.log(
+  io.out(
-`
+    `
 ${bold("Usage:")} xo-cli template inspect <category> <identifier> <field>
 
 ${bold("Arguments:")}
@@ -119,158 +200,260 @@ ${bold("Categories:")}
     - output <output-identifier> ${dim("Inspect an output")}
     - lockingscript <lockingscript-identifier> ${dim("Inspect a lockingscript")}
     - variable <variable-identifier> ${dim("Inspect a variable")}
-  `);
+  `,
+  );
 };
 
 /**
  * Handles the template inspect command.
+ * Throws CommandError on failure, returns empty object on success.
  * @param deps - The command dependencies.
  * @param args - Positional args after the command name, e.g. ["inspect", "transaction", "1234567890"].
  */
-export const handleTemplateInspectCommand = async (deps: CommandDependencies, args: string[]): Promise<void> => {
+export const handleTemplateInspectCommand = async (
+  deps: CommandDependencies,
+  args: string[],
+): Promise<Record<string, never>> => {
+  // Get the template category, identifier, and field from the arguments
   const templateCategory = args[0];
-  const templateIdentifier = args[1];
+  const templateQuery = args[1];
   const templateField = args[2];
 
-  deps.verboseLogger(`Template inspect args - category: ${templateCategory}, identifier: ${templateIdentifier}, field: ${templateField}`);
+  deps.io.verbose(
+    `Template inspect args - category: ${templateCategory}, identifier: ${templateQuery}, field: ${templateField}`,
+  );
 
-  if (!templateCategory || !templateIdentifier || !templateField) {
+  // If no template category, identifier, or field is provided, print a message and throw an error
-    console.log("No template category, identifier, or field provided");
+  if (!templateCategory || !templateQuery || !templateField) {
-    printTemplateInspectHelp();
+    deps.io.err("No template category, identifier, or field provided");
-    return;
+    printTemplateInspectHelp(deps.io);
+    throw new CommandError(
+      "template.inspect.arguments_missing",
+      "No template category, identifier, or field provided",
+    );
   }
 
-  // Get the template from the engine
+  // Resolve the template
-  const rawTemplate = await deps.app.engine.getTemplate(templateIdentifier);
+  const originalTemplate = await resolveTemplate(deps, templateQuery);
-  if (!rawTemplate) {
+  deps.io.verbose(`Original Template: ${formatObject(originalTemplate)}`);
-    console.error(`No template found: ${templateIdentifier}`);
-    return;
-  }
 
   // Resolve the template references
-  const template = await resolveTemplateReferences(rawTemplate);
+  const template = await resolveTemplateReferences(originalTemplate);
-  deps.verboseLogger(`Template: ${formatObject(template)}`);
+  deps.io.verbose(`Extended Template: ${formatObject(template)}`);
 
-  // Inspect the template in the category
+  // Handle the template category
   switch (templateCategory) {
     case "action": {
+      // Get the action from the template
       const action = template.actions[templateField];
+
+      // If the action is not found, print a message and throw an error
       if (!action) {
-        console.error(`No action found: ${templateField}`);
+        deps.io.err(`No action found: ${templateField}`);
-        return;
+        throw new CommandError(
+          "template.inspect.action_missing",
+          `No action found: ${templateField}`,
+        );
       }
-      objectPrint(action);
+
-      break;
+      // Display the action to the user
+      deps.io.out(formatObject(action));
+      return {};
     }
     case "transaction": {
-      const transaction = template.transactions[templateField];
+      // Get the transaction from the template
+      const transaction = template.transactions?.[templateField];
+
+      // If the transaction is not found, print a message and throw an error
       if (!transaction) {
-        console.error(`No transaction found: ${templateField}`);
+        deps.io.err(`No transaction found: ${templateField}`);
-        return;
+        throw new CommandError(
+          "template.inspect.transaction_missing",
+          `No transaction found: ${templateField}`,
+        );
       }
-      objectPrint(transaction);
+
-      break;
+      // Display the transaction to the user
+      deps.io.out(formatObject(transaction));
+      return {};
     }
     case "output": {
+      // Get the output from the template
       const output = template.outputs[templateField];
+
+      // If the output is not found, print a message and throw an error
       if (!output) {
-        console.error(`No output found: ${templateField}`);
+        deps.io.err(`No output found: ${templateField}`);
-        return;
+        throw new CommandError(
+          "template.inspect.output_missing",
+          `No output found: ${templateField}`,
+        );
       }
-      objectPrint(output);
+
-      break;
+      // Display the output to the user
+      deps.io.out(formatObject(output));
+      return {};
     }
     case "lockingscript": {
+      // Get the lockingscript from the template
       const lockingscript = template.lockingScripts[templateField];
+
+      // If the lockingscript is not found, print a message and throw an error
       if (!lockingscript) {
-        console.error(`No lockingscript found: ${templateField}`);
+        deps.io.err(`No lockingscript found: ${templateField}`);
-        return;
+        throw new CommandError(
+          "template.inspect.lockingscript_missing",
+          `No lockingscript found: ${templateField}`,
+        );
       }
-      objectPrint(lockingscript);
+
-      break;
+      // Display the lockingscript to the user
+      deps.io.out(formatObject(lockingscript));
+      return {};
     }
     case "variable": {
+      // Get the variable from the template
       const variable = template.variables?.[templateField];
+
+      // If the variable is not found, print a message and throw an error
       if (!variable) {
-        console.error(`No variable found: ${templateField}`);
+        deps.io.err(`No variable found: ${templateField}`);
-        return;
+        throw new CommandError(
+          "template.inspect.variable_missing",
+          `No variable found: ${templateField}`,
+        );
       }
-      objectPrint(variable);
+
-      break;
+      // Display the variable to the user
+      deps.io.out(formatObject(variable));
+      return {};
     }
     default: {
-      deps.verboseLogger(`Unknown template category: ${templateCategory}`);
+      deps.io.verbose(`Unknown template category: ${templateCategory}`);
-      return;
+      throw new CommandError(
+        "template.inspect.category_unknown",
+        `Unknown template category: ${templateCategory}`,
+      );
     }
   }
-}
+};
 
 /**
  * Handles the template command.
+ * Throws CommandError on failure, returns result data on success.
  * @param deps - The command dependencies.
  * @param args - Positional args after the command name, e.g. ["import", "template.json"] or ["set-default", "tpl", "out", "role"].
  * @param options - Parsed option flags.
  */
-export const handleTemplateCommand = async (deps: CommandDependencies, args: string[], options: Record<string, string>): Promise<void> => {
+export const handleTemplateCommand = async (
+  deps: CommandDependencies,
+  args: string[],
+  _options: Record<string, string>,
+): Promise<{ templateFile?: string; count?: number }> => {
+  // Get the sub-command from the arguments
   const subCommand = args[0];
 
+  // If no sub-command is provided, print a message and throw an error
   if (!subCommand) {
-    deps.verboseLogger("No sub-command provided");
+    deps.io.verbose("No sub-command provided");
-    printTemplateHelp();
+    printTemplateHelp(deps.io);
-    return;
+    throw new CommandError(
+      "template.subcommand.missing",
+      "No sub-command provided",
+    );
   }
 
+  // Handle the sub-command
   switch (subCommand) {
     case "import": {
+      // Get the template file from the arguments
       const templateFile = args[1];
-      deps.verboseLogger(`Template file: ${templateFile}`);
+
+      // If no template file is provided, print a message and throw an error
+      deps.io.verbose(`Template file: ${templateFile}`);
 
       if (!templateFile) {
-        deps.verboseLogger("No template file provided");
+        deps.io.verbose("No template file provided");
-        printTemplateHelp();
+        printTemplateHelp(deps.io);
-        return;
+        throw new CommandError(
+          "template.import.file_missing",
+          "No template file provided",
+        );
       }
 
+      // Resolve the template path
       const templatePath = path.resolve(`${process.cwd()}/${templateFile}`);
-      deps.verboseLogger(`Template path: ${templatePath}`);
+      deps.io.verbose(`Template path: ${templatePath}`);
 
+      // If the template file does not exist, print a message and throw an error
       if (!existsSync(templatePath)) {
-        console.error(`Template file does not exist: ${templatePath}`);
+        deps.io.err(`Template file does not exist: ${templatePath}`);
-        printTemplateHelp();
+        printTemplateHelp(deps.io);
-        return;
+        throw new CommandError(
+          "template.import.file_not_found",
+          `Template file does not exist: ${templatePath}`,
+        );
       }
 
+      // Read the template file
       const template = await readFileSync(templatePath, "utf8");
+      deps.io.verbose(`Importing template: ${templateFile}`);
 
-      deps.verboseLogger(`Importing template: ${templateFile}`);
+      // Import the template
       await deps.app.engine.importTemplate(template);
-      deps.verboseLogger(`Template imported: ${templateFile}`);
+      deps.io.verbose(`Template imported: ${templateFile}`);
-      break;
+
+      // Return the template file
+      return { templateFile };
     }
     case "list": {
-      await handleTemplateListCommand(deps, args.slice(1));
+      // Handle the template list command, We offload here as it has lots of arguments and is quite long
-      break;
+      return handleTemplateListCommand(deps, args.slice(1));
     }
     case "inspect": {
-      await handleTemplateInspectCommand(deps, args.slice(1));
+      // Handle the template inspect command, We offload here as it has lots of arguments and is quite long
-      break;
+      return handleTemplateInspectCommand(deps, args.slice(1));
     }
     case "set-default": {
+      // Get the template file, output identifier, and role identifier from the arguments
       const templateFile = args[1];
       const outputIdentifier = args[2];
       const roleIdentifier = args[3];
+
+      // If no template file, output identifier, or role identifier is provided, print a message and throw an error
       if (!templateFile || !outputIdentifier || !roleIdentifier) {
-        deps.verboseLogger("No template file, output identifier, or role identifier provided");
+        deps.io.verbose(
-        printTemplateHelp();
+          "No template file, output identifier, or role identifier provided",
-        return;
+        );
+        printTemplateHelp(deps.io);
+        throw new CommandError(
+          "template.default.arguments_missing",
+          "No template file, output identifier, or role identifier provided",
+        );
       }
-      deps.verboseLogger(`Template file: ${templateFile}, output identifier: ${outputIdentifier}, role identifier: ${roleIdentifier}`);
+
-      await deps.app.engine.setDefaultLockingParameters(templateFile, outputIdentifier, roleIdentifier);
+      // Set the default locking parameters
-      break;
+      deps.io.verbose(
+        `Template file: ${templateFile}, output identifier: ${outputIdentifier}, role identifier: ${roleIdentifier}`,
+      );
+
+      // Set the default locking parameters
+      await deps.app.engine.setDefaultLockingParameters(
+        templateFile,
+        outputIdentifier,
+        roleIdentifier,
+      );
+
+      // Return an empty object
+      return {};
     }
     default:
-      deps.verboseLogger(`Unknown template sub-command: ${subCommand}`);
+      // If the sub-command is not found, print a message and throw an error
-      printTemplateHelp();
+      deps.io.verbose(`Unknown template sub-command: ${subCommand}`);
-      return;
+      printTemplateHelp(deps.io);
+      throw new CommandError(
+        "template.subcommand.unknown",
+        `Unknown template sub-command: ${subCommand}`,
+      );
   }
 };

src/cli/commands/types.ts

@@ -1,6 +1,59 @@
 import type { AppService } from "../../services/app.js";
 
-export type CommandDependencies = {
+/**
-  verboseLogger: (message: string) => void;
+ * IO contract for CLI command handlers.
+ * Handlers write user-visible output through this abstraction so unit tests can
+ * assert behavior without spying on global console methods.
+ */
+export type CommandIO = {
+  out: (message: string) => void;
+  err: (message: string) => void;
+  verbose: (message: string) => void;
+};
+
+/**
+ * Paths configuration for CLI commands.
+ * Allows injection of custom paths for testing.
+ */
+export type CommandPaths = {
+  /** Directory for mnemonic wallet files */
+  mnemonicsDir: string;
+  /** Directory for engine DB and invitation storage files */
+  dataDir: string;
+  /** File storing the last-used mnemonic reference */
+  walletConfigPath: string;
+  /** Working directory for file output (invitation files, etc.) */
+  workingDir: string;
+};
+
+/**
+ * Base dependencies available to every command handler.
+ */
+export type BaseCommandDependencies = {
+  io: CommandIO;
+  paths: CommandPaths;
+};
+
+/**
+ * Dependencies for app-backed commands.
+ */
+export type CommandDependencies = BaseCommandDependencies & {
   app: AppService;
 };
+
+/**
+ * Custom error class for command failures.
+ * Thrown by command handlers when an operation fails.
+ * The `event` property can be used for telemetry/testing to identify failure types.
+ */
+export class CommandError extends Error {
+  public readonly event: string;
+  public readonly code: number;
+
+  constructor(event: string, message: string, code = 1) {
+    super(message);
+    this.name = "CommandError";
+    this.event = event;
+    this.code = code;
+  }
+}

src/cli/completions.ts

@@ -1,204 +0,0 @@
-/**
- * Shell completion script generation.
- * 
- * Defines the CLI command tree in one place and generates
- * bash/zsh/fish completion scripts from it. Users source the output
- * in their shell profile for tab-completion support.
- * 
- * Usage:
- *   eval "$(xo-cli completions bash)"
- *   eval "$(xo-cli completions zsh)"
- *   xo-cli completions fish | source
- */
-
-/**
- * Single source of truth for the CLI command tree.
- * Each top-level key is a command, and its value is an array of sub-commands.
- */
-export const COMMAND_TREE: Record<string, string[]> = {
-  mnemonic:   ["create", "import", "list"],
-  template:   ["import", "list", "set-default"],
-  invitation: ["create", "import", "list"],
-  receive:    [],
-  resource:   ["list"],
-  help:       [],
-  completions: ["bash", "zsh", "fish"],
-};
-
-/** Global option flags available on every command. */
-const GLOBAL_OPTIONS = ["-h", "--help", "-v", "--verbose", "-m", "--mnemonic-file", "-o", "--output"];
-
-/**
- * Generates a bash completion script.
- * @param binName - The name of the CLI binary (used in the `complete` registration).
- */
-export function generateBashCompletions(binName: string): string {
-  const commands = Object.keys(COMMAND_TREE).join(" ");
-  const options = GLOBAL_OPTIONS.join(" ");
-
-  // Build the case arms for each command's sub-commands
-  const caseArms = Object.entries(COMMAND_TREE)
-    .filter(([, subs]) => subs.length > 0)
-    .map(([cmd, subs]) => `      ${cmd})\n        COMPREPLY=($(compgen -W "${subs.join(" ")}" -- "\${cur}"))\n        return 0\n        ;;`)
-    .join("\n");
-
-  return `# bash completion for ${binName}
-# Add to ~/.bashrc:  eval "$(${binName} completions bash)"
-_${binName.replace(/-/g, "_")}_completions() {
-  local cur prev words cword
-  _init_completion || return
-
-  # If the current word starts with "-", offer option flags
-  if [[ "\${cur}" == -* ]]; then
-    COMPREPLY=($(compgen -W "${options}" -- "\${cur}"))
-    return 0
-  fi
-
-  # Find the command (first non-option positional arg after the binary)
-  local cmd=""
-  for ((i=1; i < cword; i++)); do
-    if [[ "\${words[i]}" != -* ]]; then
-      cmd="\${words[i]}"
-      break
-    fi
-  done
-
-  # No command yet — offer the top-level commands
-  if [[ -z "\${cmd}" ]]; then
-    COMPREPLY=($(compgen -W "${commands}" -- "\${cur}"))
-    return 0
-  fi
-
-  # Offer sub-commands for the matched command
-  case "\${cmd}" in
-${caseArms}
-  esac
-}
-
-complete -F _${binName.replace(/-/g, "_")}_completions ${binName}
-`;
-}
-
-/**
- * Generates a zsh completion script.
- * @param binName - The name of the CLI binary.
- */
-export function generateZshCompletions(binName: string): string {
-  const commands = Object.keys(COMMAND_TREE).join(" ");
-  const options = GLOBAL_OPTIONS.join(" ");
-
-  const caseArms = Object.entries(COMMAND_TREE)
-    .filter(([, subs]) => subs.length > 0)
-    .map(([cmd, subs]) => `      ${cmd})\n        compadd -- ${subs.join(" ")}\n        ;;`)
-    .join("\n");
-
-  return `# zsh completion for ${binName}
-# Add to ~/.zshrc:  eval "$(${binName} completions zsh)"
-_${binName.replace(/-/g, "_")}_completions() {
-  local -a commands
-  commands=(${commands})
-
-  # If typing an option flag, complete options
-  if [[ "\${words[\${CURRENT}]}" == -* ]]; then
-    compadd -- ${options}
-    return
-  fi
-
-  # Find the command (first non-option positional arg)
-  local cmd=""
-  for ((i=2; i < CURRENT; i++)); do
-    if [[ "\${words[i]}" != -* ]]; then
-      cmd="\${words[i]}"
-      break
-    fi
-  done
-
-  # No command yet — offer top-level commands
-  if [[ -z "\${cmd}" ]]; then
-    compadd -- \${commands[@]}
-    return
-  fi
-
-  # Offer sub-commands
-  case "\${cmd}" in
-${caseArms}
-  esac
-}
-
-compdef _${binName.replace(/-/g, "_")}_completions ${binName}
-`;
-}
-
-/**
- * Generates a fish completion script.
- * @param binName - The name of the CLI binary.
- */
-export function generateFishCompletions(binName: string): string {
-  const lines: string[] = [
-    `# fish completion for ${binName}`,
-    `# Add to fish config:  ${binName} completions fish | source`,
-    "",
-    `# Disable file completions by default`,
-    `complete -c ${binName} -f`,
-    "",
-  ];
-
-  // Global options
-  for (const opt of GLOBAL_OPTIONS) {
-    const isShort = !opt.startsWith("--");
-    const flag = opt.replace(/^-+/, "");
-    if (isShort) {
-      lines.push(`complete -c ${binName} -s ${flag} -d "Option flag"`);
-    } else {
-      lines.push(`complete -c ${binName} -l ${flag} -d "Option flag"`);
-    }
-  }
-  lines.push("");
-
-  // Top-level commands (only when no sub-command is given yet)
-  const commandNames = Object.keys(COMMAND_TREE);
-  for (const cmd of commandNames) {
-    lines.push(`complete -c ${binName} -n "__fish_use_subcommand" -a "${cmd}" -d "${cmd} command"`);
-  }
-  lines.push("");
-
-  // Sub-commands for each command
-  for (const [cmd, subs] of Object.entries(COMMAND_TREE)) {
-    for (const sub of subs) {
-      lines.push(`complete -c ${binName} -n "__fish_seen_subcommand_from ${cmd}" -a "${sub}" -d "${cmd} ${sub}"`);
-    }
-  }
-
-  return lines.join("\n") + "\n";
-}
-
-type ShellType = "bash" | "zsh" | "fish";
-
-const generators: Record<ShellType, (binName: string) => string> = {
-  bash: generateBashCompletions,
-  zsh: generateZshCompletions,
-  fish: generateFishCompletions,
-};
-
-/**
- * Handles the `completions` command.
- * Prints the generated completion script for the given shell to stdout.
- * @param args - Positional args after "completions", e.g. ["bash"].
- * @param binName - The CLI binary name to use in the completion script.
- */
-export function handleCompletionsCommand(args: string[], binName: string = "xo-cli"): void {
-  const shell = args[0] as ShellType | undefined;
-
-  if (!shell || !generators[shell]) {
-    const supported = Object.keys(generators).join(", ");
-    console.error(`Usage: ${binName} completions <${supported}>`);
-    console.error("");
-    console.error("Examples:");
-    console.error(`  eval "$(${binName} completions bash)"   # Add to ~/.bashrc`);
-    console.error(`  eval "$(${binName} completions zsh)"    # Add to ~/.zshrc`);
-    console.error(`  ${binName} completions fish | source    # Add to fish config`);
-    process.exit(1);
-  }
-
-  process.stdout.write(generators[shell](binName));
-}

src/cli/index.ts

@@ -1,22 +1,23 @@
+#!/usr/bin/env node
 /**
  * CLI entry point.
- * 
+ *
  * TODO: Decide the best way to handle CLI arguments. We have the option of:
  * - Handling it in the `bin` folder
  * - Switch / if statements in here
  * - Dedicated command parser
  * - Separate files?
- * 
+ *
  * What kind of commands do we want to support?
  * Worth noting that we shouldn't need to list invitations? Maybe we will though? If we do, then we will need to reuse the storage + xo-invitations.db file. I think this is fine to do though?
  * Nah, lets use the storage + xo-invitations.db file. Will allow us to persist invitations.
  * How do we want to import invitations though? Should we just take in the ID still? Probably makes more sense to allow for reading from a file though...
  * But thats an entirely different flow to what we have already. And how would we handle writing the invitation? Do we just overwrite the file? Probably... Just take in an -o option; default to overwrite?
- * 
+ *
  * Commands:
  * xo-cli mnemonic create [mnemonic seed]
  * xo-cli mnemonic list
- * 
+ *
  * xo-cli template import <template-file>
  * xo-cli template list
  * xo-cli template set-default <template-file> <output-identifier> <role-identifier>
@@ -26,46 +27,57 @@
  * xo-cli invitation import <invitation-file>
  * xo-cli invitation sign <invitation-file>
  * xo-cli invitation broadcast <invitation-file>
- * 
+ *
  * xo-cli resource list
- * 
+ *
  * universal Args:
  * -h --help
  * -m --mnemonic-file <mnemonic-file>
  */
 
-import { existsSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
 
 import { AppService } from "../services/app.js";
+import { SettingsService } from "../services/settings.js";
 import { convertArgsToObject } from "./arguments.js";
-import { bold, dim, formatObject } from "./cli-utils.js";
+import { bold, dim, formatObject } from "./utils.js";
-import { listMnemonicFiles, loadMnemonic } from "./mnemonic.js";
+import { listGlobalMnemonicFiles, loadMnemonic } from "./mnemonic.js";
+import {
+  getDataDir,
+  getMnemonicsDir,
+  getWalletConfigPath,
+} from "../utils/paths.js";
 
-/** File that remembers the last-used mnemonic so `-m` can be omitted. */
+import {
-const WALLET_CONFIG_FILE = ".xo-cli-wallet";
-
-import { 
   type CommandDependencies,
-  handleMnemonicCommand, 
+  type CommandIO,
-  handleTemplateCommand, 
+  type CommandPaths,
+  CommandError,
+  handleMnemonicCommand,
+  handleSettingsCommand,
+  handleTemplateCommand,
   handleInvitationCommand,
   handleReceiveCommand,
   handleResourceCommand,
 } from "./commands/index.js";
 
-import { handleCompletionsCommand } from "./completions.js";
+import { handleCompletionsCommand } from "./autocomplete/completions.js";
 
-const createConditionalLogger = (verbose: boolean) => {
+const createCommandIO = (verbose: boolean): CommandIO => ({
-  return (message: string) => {
+  out: (message: string) => {
-    if (verbose) {
+    console.log(message);
-      console.log(message);
+  },
-    }
+  err: (message: string) => {
-  };
+    console.error(message);
-};
+  },
+  verbose: (message: string) => {
+    if (verbose) console.log(message);
+  },
+});
 
 /**
  * Main entry point.
- * We will: 
+ * We will:
  * - Initialize the app service?
  * - Extract the command being called
  * - Extract CLI Args (Depends on the command being called. Eww. But we can probably use Zod to validate the args in a decent way?)
@@ -79,107 +91,183 @@ async function main(): Promise<void> {
   const { args, options } = convertArgsToObject(process.argv.slice(2));
 
   // Create a verbose logger if the user set the verbose flag
-  const verboseLogger = createConditionalLogger(options["verbose"] === "true");
+  const io = createCommandIO(options["verbose"] === "true");
 
   // Log the parsed app args
-  verboseLogger(`Parsed args: ${formatObject(args)}`);
+  io.verbose(`Parsed args: ${formatObject(args)}`);
-  verboseLogger(`Parsed options: ${formatObject(options)}`);
+  io.verbose(`Parsed options: ${formatObject(options)}`);
-  
+
   // Handle the command
   const command = args[0];
-  verboseLogger(`Command: ${command}`);
+  io.verbose(`Command: ${command}`);
   if (!command) {
     // TODO: Print help, probably...
-    console.error("No command provided");
+    io.err("No command provided");
     process.exit(1);
   }
 
   // Positional args after the command name (sub-command, files, etc.)
   const subArgs = args.slice(1);
 
-  // Early handling if we are calling the mnemonic command
+  // Build paths object from global path functions
-  // TODO: This is ugly. I would like to find a nicer way of doing this.
+  const paths: CommandPaths = {
+    mnemonicsDir: getMnemonicsDir(),
+    dataDir: getDataDir(),
+    walletConfigPath: getWalletConfigPath(),
+    workingDir: process.cwd(),
+  };
+  const settings = new SettingsService(paths.walletConfigPath);
+
+  // Early handling for completions command
   if (command === "completions") {
-    handleCompletionsCommand(subArgs);
+    handleCompletionsCommand(subArgs, options);
-    return;
+    process.exit(0);
   }
 
   if (command === "mnemonic") {
-    await handleMnemonicCommand({ verboseLogger }, subArgs, options);
+    try {
-    return;
+      await handleMnemonicCommand({ io, paths }, subArgs, options);
+      process.exit(0);
+    } catch (error) {
+      if (error instanceof CommandError) {
+        process.exit(error.code);
+      }
+      throw error;
+    }
   }
 
-  // Resolve mnemonic file: explicit flag > persisted config > error.
+  if (command === "settings") {
+    try {
+      await handleSettingsCommand({ io, paths }, subArgs, options);
+      process.exit(0);
+    } catch (error) {
+      if (error instanceof CommandError) {
+        process.exit(error.code);
+      }
+      throw error;
+    }
+  }
+
+  // Resolve mnemonic file: explicit flag > persisted settings > error.
   let mnemonicFile = options["mnemonicFile"];
-  if (!mnemonicFile && existsSync(WALLET_CONFIG_FILE)) {
+  let didUsePersistedMnemonic = false;
-    mnemonicFile = readFileSync(WALLET_CONFIG_FILE, "utf8").trim();
+  if (!mnemonicFile) {
-    verboseLogger(`Using persisted wallet: ${mnemonicFile}`);
+    mnemonicFile = settings.getDefaultMnemonic();
+    didUsePersistedMnemonic = Boolean(mnemonicFile);
+  }
+  if (didUsePersistedMnemonic && mnemonicFile) {
+    io.verbose(`Using persisted wallet: ${mnemonicFile}`);
   }
   if (!mnemonicFile) {
-    console.error("No mnemonic file provided");
+    io.err("No mnemonic file provided");
-    console.log(`You can create a mnemonic file with the following command: xo-cli mnemonic create <mnemonic-seed> or use one of the following files: \n${listMnemonicFiles().join("\n")}`);
+    io.out(
-    console.log(`\nTip: pass -m <file> once and it will be remembered in ${WALLET_CONFIG_FILE}`);
+      `You can create a mnemonic file with the following command: xo-cli mnemonic create <mnemonic-seed> or use one of the following files: \n${listGlobalMnemonicFiles().join("\n")}`,
+    );
+    io.out(
+      `\nTip: pass -m <file> once and it will be remembered in ${paths.walletConfigPath}`,
+    );
     process.exit(1);
   }
 
   // Persist the choice so subsequent commands can omit -m.
-  writeFileSync(WALLET_CONFIG_FILE, mnemonicFile);
+  settings.setDefaultMnemonic(mnemonicFile);
+  if (options["currency"]) {
+    settings.setCurrency(options["currency"]);
+    io.verbose(`Using configured currency: ${settings.getCurrency()}`);
+  }
+
+  const mnemonic = loadMnemonic(paths.mnemonicsDir, mnemonicFile);
+  io.verbose(`Loaded mnemonic from file: ${mnemonicFile} ${mnemonic}`);
 
-  const mnemonic = await loadMnemonic(mnemonicFile);
-  verboseLogger(`Loaded mnemonic from file: ${mnemonicFile} ${mnemonic}`);
-  
   // Create an App instance
-  verboseLogger("Creating app instance...");
+  io.verbose("Creating app instance...");
   const app = await AppService.create(mnemonic, {
     syncServerUrl: options["syncServerUrl"] ?? "http://localhost:3000",
     engineConfig: {
-      databasePath: options["databasePath"] ?? "./",
+      databasePath: options["databasePath"] ?? paths.dataDir,
-      databaseFilename: options["databaseFilename"] ?? 'xo-wallet.db',
+      databaseFilename: options["databaseFilename"] ?? "xo-wallet.db",
     },
-    invitationStoragePath: options["invitationStoragePath"] ?? "./xo-invitations.db",
+    invitationStoragePath:
-  });
+      options["invitationStoragePath"] ??
-  verboseLogger("App instance created");
+      join(paths.dataDir, "xo-invitations.db"),
+  }, settings);
+  io.verbose("App instance created");
 
   // Start the app
-  verboseLogger("Starting app...");
+  // TODO: Rethink this. Do we really want to start the app here? It just slows it down if we dont actually have to have it started for the command
+  io.verbose("Starting app...");
   await app.start();
-  verboseLogger("App started");
+  io.verbose("App started");
 
   const commandDependencies: CommandDependencies = {
-    verboseLogger,
+    io,
+    paths,
     app,
   };
 
   // Handle the command
-  switch (command) {
+  try {
-    case "template":
+    let result: unknown;
-      await handleTemplateCommand(commandDependencies, subArgs, options);
+    switch (command) {
-      break;
+      case "template":
-    case "invitation":
+        result = await handleTemplateCommand(
-      await handleInvitationCommand(commandDependencies, subArgs, options);
+          commandDependencies,
-      break;
+          subArgs,
-    case "receive":
+          options,
-      await handleReceiveCommand(commandDependencies, subArgs, options);
+        );
-      break;
+        break;
-    case "resource":
+      case "invitation":
-      await handleResourceCommand(commandDependencies, subArgs, options);
+        result = await handleInvitationCommand(
-      break;
+          commandDependencies,
-    case "help":
+          subArgs,
-      await handleHelpCommand(commandDependencies, subArgs, options);
+          options,
-      break;
+        );
-    default:
+        break;
-      console.error(`Unknown command: ${command}`);
+      case "receive":
-      process.exit(1);
+        result = await handleReceiveCommand(
-  }
+          commandDependencies,
+          subArgs,
+          options,
+        );
+        break;
+      case "resource":
+        result = await handleResourceCommand(
+          commandDependencies,
+          subArgs,
+          options,
+        );
+        break;
+      case "help":
+        result = await handleHelpCommand(commandDependencies, subArgs, options);
+        break;
+      default:
+        io.err(`Unknown command: ${command}`);
+        throw new CommandError(
+          "cli.command.unknown",
+          `Unknown command: ${command}`,
+        );
+    }
 
-  // Exit the process
+    // console.log(result);
-  process.exit(0);
+
+    // objectPrint(result);
+    process.exit(0);
+  } catch (error) {
+    if (error instanceof CommandError) {
+      io.err(error.message);
+      process.exit(error.code);
+    }
+    throw error;
+  }
 }
 
-const handleHelpCommand = async (deps: CommandDependencies, args: string[], options: Record<string, string>): Promise<void> => {
+const handleHelpCommand = async (
-  // Im sorry about the formatting here. I'm not sure how to handle this better.
+  deps: CommandDependencies,
-  console.log(
+  _args: string[],
-`${bold("XO-CLI Help:")}
+  _options: Record<string, string>,
+): Promise<Record<string, never>> => {
+  deps.io.out(
+    `${bold("XO-CLI Help:")}
 
 ${bold("Usage:")} xo-cli <command> [options]
 
@@ -189,13 +277,17 @@ Commands:
   invitation  ${dim("Manage invitations")}
   receive     ${dim("Generate a single-use receiving address")}
   resource    ${dim("Manage resources")}
+  settings    ${dim("Manage persisted wallet settings")}
   completions ${dim("Generate shell completion scripts (bash, zsh, fish)")}
+  help        ${dim("Show this help message")}
 
 Options:
   -h, --help    ${dim("Show this help message")}
   -m, --mnemonic-file <mnemonic-file>  ${dim("Use a specific mnemonic file")}
-  -v, --verbose   ${dim("Show verbose output")}`
+  --currency <currency-code>  ${dim("Set fiat display currency (e.g. USD, AUD)")}
+  -v, --verbose   ${dim("Show verbose output")}`,
   );
+  return {};
 };
 
 main().catch((error) => {

src/cli/mnemonic.ts

@@ -1,58 +1,110 @@
-import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
-import { BCHMnemonicURL,  } from "../utils/bch-mnemonic-url.js";
+import { basename, isAbsolute, join, resolve } from "node:path";
 import { encodeBip39Mnemonic, generateBip39Mnemonic } from "@bitauth/libauth";
 
+import { BCHMnemonicURL } from "../utils/bch-mnemonic-url.js";
+import { getMnemonicsDir as getGlobalMnemonicsDir } from "../utils/paths.js";
+
 /**
  * Create a new mnemonic seed phrase
  */
 export const createMnemonicSeed = (): string => {
-  // Generate a new mnemonic seed
+  return generateBip39Mnemonic();
-  const mnemonic = generateBip39Mnemonic();
-
-  // Return the mnemonic phrase
-  return mnemonic;
 };
 
 /**
  * Creates a mnemonic file from a mnemonic seed
+ * @param mnemonicsDir - Directory to store mnemonic files
  * @param mnemonic - The mnemonic seed
  * @param outputFilename - The filename to write the mnemonic to. If not provided, the first word from the mnemonic will be used as the filename
  * @returns The filename of the created mnemonic file
  */
-export const createMnemonicFile = (mnemonic: string, outputFilename?: string): string => {
+export const createMnemonicFile = (
-  // Convert the mnemonic seed to a BCH Mnemonic URL
+  mnemonicsDir: string,
+  mnemonic: string,
+  outputFilename?: string,
+): string => {
   const mnemonicUrl = BCHMnemonicURL.fromSeed(mnemonic);
 
-  // If no output filename is provided, use the first word from the mnemonic as the filename
   let fileName = outputFilename;
   if (!fileName) {
-    const firstWord = mnemonic.at(0)?.toLowerCase();
+    const firstWord = mnemonic.split(" ")[0]?.toLowerCase();
     if (!firstWord) {
-      throw new Error("Failed to create mnemonic file: Unable to extract first word from the mnemonic");
+      throw new Error(
+        "Failed to create mnemonic file: Unable to extract first word from the mnemonic",
+      );
     }
     fileName = `mnemonic-${firstWord}`;
   }
 
-  // Write the mnemonic URL to a file
+  const safeName = basename(fileName);
-  // TODO: May need PWD or something to ensure we are writing to the correct directory
+  const outPath = join(mnemonicsDir, safeName);
-  writeFileSync(fileName, mnemonicUrl.toURL());
+  writeFileSync(outPath, mnemonicUrl.toURL());
 
-  return fileName;
+  return safeName;
+};
+
+/**
+ * Resolves a mnemonic reference to an absolute path.
+ * Order: absolute path if it exists → path relative to cwd → mnemonicsDir/<basename>.
+ *
+ * @param mnemonicsDir - Directory containing mnemonic files
+ * @param mnemonicRef - Path or basename (e.g. `mnemonic-nuclear`)
+ * @returns Absolute path to the mnemonic file
+ * @throws If no matching file exists
+ */
+export const resolveMnemonicFilePath = (
+  mnemonicsDir: string,
+  mnemonicRef: string,
+): string => {
+  // Try to resolve the mnemonic file as an absolute path
+  if (isAbsolute(mnemonicRef) && existsSync(mnemonicRef)) {
+    return mnemonicRef;
+  }
+
+  // Try to resolve the mnemonic file relative to the current working directory
+  const relativeToCwd = resolve(process.cwd(), mnemonicRef);
+  if (existsSync(relativeToCwd)) {
+    return relativeToCwd;
+  }
+
+  // Try to resolve the mnemonic file in the mnemonics directory
+  const inMnemonics = join(mnemonicsDir, basename(mnemonicRef));
+  if (existsSync(inMnemonics)) {
+    return inMnemonics;
+  }
+
+  // If the mnemonic file is not found, throw an error
+  throw new Error(
+    `Mnemonic file not found: ${mnemonicRef}. Run "xo-cli mnemonic list" to see available files.`,
+  );
 };
 
 /**
  * Loads a mnemonic from a mnemonic file
+ * @param mnemonicsDir - Directory containing mnemonic files
  * @param mnemonicFile - The filename of the mnemonic file
  * @returns The mnemonic seed
  */
-export const loadMnemonic = (mnemonicFile: string): string => {
+export const loadMnemonic = (
-  const mnemonicUrl = BCHMnemonicURL.fromURL(readFileSync(mnemonicFile, "utf8"));
+  mnemonicsDir: string,
+  mnemonicFile: string,
+): string => {
+  // Resolve the mnemonic file path
+  const resolvedPath = resolveMnemonicFilePath(mnemonicsDir, mnemonicFile);
+
+  // Read the mnemonic file
+  const mnemonicUrl = BCHMnemonicURL.fromURL(
+    readFileSync(resolvedPath, "utf8"),
+  );
+
+  // Get the entropy from the mnemonic url
   const { entropy } = mnemonicUrl.toObject();
 
-  // Convert the entropy to a mnemonic seed
+  // Encode the entropy to a mnemonic
   const mnemonic = encodeBip39Mnemonic(entropy);
 
-  // If the conversion failed, throw an error
+  // If the mnemonic is not a string, throw an error
   if (typeof mnemonic === "string") {
     throw new Error(`Failed to convert entropy to mnemonic: ${mnemonic}`);
   }
@@ -62,11 +114,26 @@ export const loadMnemonic = (mnemonicFile: string): string => {
 };
 
 /**
- * Lists all mnemonic files in the current directory
+ * Lists mnemonic files in the given directory.
- * @returns An array of mnemonic file names
+ * @param mnemonicsDir - Directory containing mnemonic files
+ * @returns Basenames suitable for `-m <name>`
  */
-export const listMnemonicFiles = (): string[] => {
+export const listMnemonicFiles = (mnemonicsDir: string): string[] => {
-  const cwd = process.cwd();
+  // List the mnemonic files in the given directory
-  const filenames = readdirSync(cwd).filter((f: string) => f.startsWith('mnemonic-'));
+  const filenames = readdirSync(mnemonicsDir).filter((f: string) =>
+    f.startsWith("mnemonic-"),
+  );
+
+  // Return the mnemonic files
   return filenames;
 };
+
+/**
+ * Lists mnemonic files using the global mnemonics directory.
+ * Convenience function for use in the CLI entry point before paths are resolved.
+ * @returns Basenames suitable for `-m <name>`
+ */
+export const listGlobalMnemonicFiles = (): string[] => {
+  // List the mnemonic files in the global mnemonics directory
+  return listMnemonicFiles(getGlobalMnemonicsDir());
+};

src/cli/utils.ts

@@ -0,0 +1,114 @@
+import util from "node:util";
+
+import type { XOTemplate } from "@xo-cash/types";
+import { generateTemplateIdentifier } from "@xo-cash/engine";
+
+import type { CommandDependencies } from "./commands/types.js";
+import { CommandError } from "./commands/types.js";
+
+/**
+ * Iterate through the templates, trying to match the id or the name with the given input.
+ * Use multiple for-loops.
+ * First, check the id of every template
+ * Then, check the name of every template. If multiple names match, throw an error.
+ * If no match is found, throw an error.
+ *
+ * @param deps - The command dependencies.
+ * @param query - The id or name of the template to resolve.
+ * @returns The template object.
+ * @throws CommandError if no template is found.
+ * @throws CommandError if multiple templates are found.
+ */
+export const resolveTemplate = async (
+  deps: CommandDependencies,
+  query: string,
+): Promise<XOTemplate> => {
+  // Gather all of our imported templates
+  const templates = await deps.app.engine.listImportedTemplates();
+
+  // Create a set to store the matches
+  const matches = new Set<XOTemplate>();
+
+  // Iterate through the templates and check if the identifier matches the query
+  for (const template of templates) {
+    if (generateTemplateIdentifier(template) === query) {
+      // Return early if we got a match since identifiers are always unique by content
+      return template;
+    }
+  }
+
+  // Iterate through the templates and check if the name matches the query
+  for (const template of templates) {
+    if (template.name === query) {
+      matches.add(template);
+    }
+  }
+
+  // If there are multiple matches, throw an error
+  if (matches.size > 1) {
+    throw new CommandError(
+      "template.resolve.multiple_matches",
+      `Multiple templates found for "${query}": ${Array.from(matches)
+        .map(
+          (template) =>
+            `${template.name} (${generateTemplateIdentifier(template)})`,
+        )
+        .join(", ")}`,
+    );
+  }
+
+  // If there is one match, return the match
+  if (matches.size === 1) {
+    return matches.values().next().value!;
+  }
+
+  // If there are no matches, throw an error
+  throw new CommandError(
+    "template.resolve.not_found",
+    `Template not found: ${query}`,
+  );
+};
+
+/**
+ * Text formatting utilities for the CLI.
+ *
+ * Uses ANSI escape codes to format text.
+ *
+ * AI Generated links:
+ * @see https://en.wikipedia.org/wiki/ANSI_escape_code
+ * @see https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters
+ * @see https://en.wikipedia.org/wiki/ANSI_escape_code#Colors
+ * @see https://en.wikipedia.org/wiki/ANSI_escape_code#Formatting
+ * @see https://en.wikipedia.org/wiki/ANSI_escape_code#Cursor_movement
+ * @see https://en.wikipedia.org/wiki/ANSI_escape_code#Screen_manipulation
+ */
+
+const BOLD = "\x1b[1m";
+export const bold = (text: string) => `${BOLD}${text}${RESET}`;
+
+const DIM = "\x1b[2m";
+export const dim = (text: string) => `${DIM}${text}${RESET}`;
+
+const UNDERLINE = "\x1b[4m";
+export const underline = (text: string) => `${UNDERLINE}${text}${RESET}`;
+
+const INVERSE = "\x1b[7m";
+export const inverse = (text: string) => `${INVERSE}${text}${RESET}`;
+
+const HIDDEN = "\x1b[8m";
+export const hidden = (text: string) => `${HIDDEN}${text}${RESET}`;
+
+const STRIKETHROUGH = "\x1b[9m";
+export const strikethrough = (text: string) =>
+  `${STRIKETHROUGH}${text}${RESET}`;
+
+const RESET = "\x1b[0m";
+export const reset = (text: string) => `${RESET}${text}${RESET}`;
+
+export const formatObject = (obj: unknown) => {
+  return util.inspect(obj, {
+    depth: null,
+    colors: true,
+    compact: false,
+  });
+};

src/index.ts

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 /**
  * XO Wallet CLI - Terminal User Interface for XO crypto wallet.
  *
@@ -9,18 +10,25 @@
  * 5. Real-time updates via SSE
  */
 
+import { join } from "node:path";
+
 import { App } from "./app.js";
+import { getDataDir } from "./utils/paths.js";
 
 /**
  * Main entry point.
  */
 async function main(): Promise<void> {
   try {
+    const dataDir = getDataDir();
     // Create and start the application
     await App.create({
       syncServerUrl: process.env["SYNC_SERVER_URL"] ?? "http://localhost:3000",
-      databasePath: process.env["DB_PATH"] ?? "./",
+      databasePath: process.env["DB_PATH"] ?? dataDir,
       databaseFilename: process.env["DB_FILENAME"] ?? "xo-wallet.db",
+      invitationStoragePath:
+        process.env["INVITATION_STORAGE_PATH"] ??
+        join(dataDir, "xo-invitations.db"),
     });
   } catch (error) {
     console.error("Failed to start XO Wallet CLI:", error);

src/services/app.ts

@@ -7,10 +7,12 @@ import {
 import type { XOInvitation } from "@xo-cash/types";
 
 import { Invitation } from "./invitation.js";
-import { Storage } from "./storage.js";
+import { BaseStorage, Storage } from "./storage.js";
 import { SyncServer } from "../utils/sync-server.js";
 import { HistoryService } from "./history.js";
-import { ElectrumService } from "./electrum.js";
+import { type BlockchainService, ElectrumService } from "./electrum.js";
+import { RatesService } from "./rates.js";
+import { SettingsService } from "./settings.js";
 
 import { EventEmitter } from "../utils/event-emitter.js";
 
@@ -18,6 +20,7 @@ import { EventEmitter } from "../utils/event-emitter.js";
 import { createHash } from "crypto";
 import { p2pkhTemplate } from "@xo-cash/templates";
 import { hexToBin } from "@bitauth/libauth";
+import { parseTemplate } from "@xo-cash/engine";
 
 export type AppEventMap = {
   "invitation-added": Invitation;
@@ -42,10 +45,12 @@ export interface AppConfig {
 
 export class AppService extends EventEmitter<AppEventMap> {
   public engine: Engine;
-  public storage: Storage;
+  public storage: BaseStorage;
   public config: AppConfig;
   public history: HistoryService;
-  public electrum: ElectrumService;
+  public electrum: BlockchainService;
+  public rates: RatesService;
+  public settings: SettingsService;
 
   public invitations: Invitation[] = [];
   private invitationEventCleanup = new Map<
@@ -56,7 +61,11 @@ export class AppService extends EventEmitter<AppEventMap> {
     }
   >();
 
-  static async create(seed: string, config: AppConfig): Promise<AppService> {
+  static async create(
+    seed: string,
+    config: AppConfig,
+    settings: SettingsService = new SettingsService(),
+  ): Promise<AppService> {
     // Because of a bug that lets wallets read the unspents of other wallets, we are going to manually namespace the storage paths for the app.
     // We are going to do this by computing a hash of the seed and prefixing the storage paths with it.
     const seedHash = createHash("sha256").update(seed).digest("hex");
@@ -74,14 +83,39 @@ export class AppService extends EventEmitter<AppEventMap> {
     // Import the default P2PKH template
     const { templateIdentifier } = await engine.importTemplate(p2pkhTemplate);
 
-    engine.subscribeToLockingBytecodesForTemplate(templateIdentifier).catch(err => console.error(`Error subscribing to locking bytecodes for template ${templateIdentifier}: ${err}`));
+    // engine
-    engine.updateUnspentOutputsForTemplate(templateIdentifier).catch(err => console.error(`Error updating unspent outputs for template ${templateIdentifier}: ${err}`));
+    //   .subscribeToLockingBytecodesForTemplate(templateIdentifier)
+    //   .catch((err) =>
+    //     console.error(
+    //       `Error subscribing to locking bytecodes for template ${templateIdentifier}: ${err}`,
+    //     ),
+    //   );
+    // engine
+    //   .updateUnspentOutputsForTemplate(templateIdentifier)
+    //   .catch((err) =>
+    //     console.error(
+    //       `Error updating unspent outputs for template ${templateIdentifier}: ${err}`,
+    //     ),
+    //   );
+    
+    // Update all the unspents for every template, and subscribe to the locking bytecodes for changes
+    // TODO: Remove the above lines that do the same thing. Minimising changes for BLISS.
+    const updateTemplates = async () => {
+      const templates = await engine.listImportedTemplates();
+
+      templates.forEach(async (template) => {
+        // engine.updateUnspentOutputsForTemplate(generateTemplateIdentifier(template));
+        engine.subscribeToLockingBytecodesForTemplate(generateTemplateIdentifier(template));
+      });
+    };
+
+    updateTemplates();
 
     // Set default locking parameters for P2PKH
     // To my knowledge, this doesnt generate any lockscript, so discovery of funds will not work automatically.
     // TODO: Add discovery for funds in the first index? Or until we return 0 TXs?
     await engine.setDefaultLockingParameters(
-      generateTemplateIdentifier(p2pkhTemplate),
+      generateTemplateIdentifier(parseTemplate(p2pkhTemplate)),
       "receiveOutput",
       "receiver",
     );
@@ -95,15 +129,18 @@ export class AppService extends EventEmitter<AppEventMap> {
       host: config.electrumHost,
       applicationIdentifier: config.electrumApplicationIdentifier,
     });
+    const rates = await RatesService.create(settings);
 
-    return new AppService(engine, walletStorage, config, electrum);
+    return new AppService(engine, walletStorage, config, electrum, rates, settings);
   }
 
   constructor(
     engine: Engine,
-    storage: Storage,
+    storage: BaseStorage,
     config: AppConfig,
-    electrum: ElectrumService,
+    electrum: BlockchainService,
+    rates: RatesService,
+    settings: SettingsService,
   ) {
     super();
 
@@ -111,6 +148,8 @@ export class AppService extends EventEmitter<AppEventMap> {
     this.storage = storage;
     this.config = config;
     this.electrum = electrum;
+    this.rates = rates;
+    this.settings = settings;
     this.history = new HistoryService(engine, this.invitations);
   }
 
@@ -135,10 +174,10 @@ export class AppService extends EventEmitter<AppEventMap> {
 
     // Create the invitation
     const invitationInstance = await Invitation.create(invitation, deps);
-    
+
     // Add the invitation to the invitations array
     await this.addInvitation(invitationInstance);
-    
+
     return invitationInstance;
   }
 
@@ -209,10 +248,7 @@ export class AppService extends EventEmitter<AppEventMap> {
     if (!trackedInvitation || !cleanup) return;
 
     trackedInvitation.off("invitation-updated", cleanup.onUpdated);
-    trackedInvitation.off(
+    trackedInvitation.off("invitation-status-changed", cleanup.onStatusChanged);
-      "invitation-status-changed",
-      cleanup.onStatusChanged,
-    );
     this.invitationEventCleanup.delete(invitationIdentifier);
   }
 
@@ -224,14 +260,14 @@ export class AppService extends EventEmitter<AppEventMap> {
    */
   async unreserveAllResources(): Promise<number> {
     const allUnspentOutputs = await this.engine.listUnspentOutputsData();
-    const reserved = allUnspentOutputs.filter((o) => o.reserved);
+    const reserved = allUnspentOutputs.filter((o) => o.reservedBy);
 
     // Group by invitation identifier so the engine can clear them properly.
     const byInvitation = new Map<string, typeof reserved>();
     for (const output of reserved) {
-      const existing = byInvitation.get(output.invitationIdentifier) ?? [];
+      const existing = byInvitation.get(output.reservedBy!) ?? [];
       existing.push(output);
-      byInvitation.set(output.invitationIdentifier, existing);
+      byInvitation.set(output.reservedBy!, existing);
     }
 
     for (const [invitationIdentifier, outputs] of byInvitation) {
@@ -248,6 +284,11 @@ export class AppService extends EventEmitter<AppEventMap> {
   }
 
   async start(): Promise<void> {
+    // Start rates in the background so BCH -> fiat conversions become reactive in the TUI.
+    this.rates.start().catch((err) =>
+      console.error('Error starting rates service:', err),
+    );
+
     // Get the invitations db
     const invitationsDb = this.storage.child("invitations");
 
@@ -259,7 +300,9 @@ export class AppService extends EventEmitter<AppEventMap> {
 
     await Promise.all(
       invitations.map(async ({ key }) => {
-        await this.createInvitation(key).catch(err => console.error(`Error creating invitation ${key}: ${err}`));
+        await this.createInvitation(key).catch((err) =>
+          console.error(`Error creating invitation ${key}: ${err}`),
+        );
       }),
     );
   }

src/services/electrum.ts

@@ -8,6 +8,10 @@ export interface ElectrumServiceConfig {
   applicationIdentifier?: string;
 }
 
+export abstract class BlockchainService {
+  abstract hasSeenTransaction(transactionHash: string): Promise<boolean>;
+}
+
 /**
  * Small Electrum adapter used by CLI services.
  * Keeps connection logic in one place and exposes a tiny API.

src/services/invitation.ts

@@ -2,9 +2,9 @@ import type {
   AcceptInvitationParameters,
   AppendInvitationParameters,
   Engine,
-  FindSuitableResourcesParameters,
+  GetSpendableResourcesParameters,
 } from "@xo-cash/engine";
-import { hasInvitationExpired, mergeInvitationCommits } from "@xo-cash/engine";
+import { generateTemplateIdentifier, hasInvitationExpired, mergeInvitationCommits } from "@xo-cash/engine";
 import type {
   XOInvitation,
   XOInvitationCommit,
@@ -24,8 +24,8 @@ import {
 
 import type { SSEvent } from "../utils/sse-client.js";
 import type { SyncServer } from "../utils/sync-server.js";
-import type { Storage } from "./storage.js";
+import type { BaseStorage } from "./storage.js";
-import type { ElectrumService } from "./electrum.js";
+import type { BlockchainService } from "./electrum.js";
 
 import { EventEmitter } from "../utils/event-emitter.js";
 import { decodeExtendedJsonObject } from "../utils/ext-json.js";
@@ -34,14 +34,14 @@ import { compileCashAssemblyString } from "@xo-cash/engine";
 export type InvitationEventMap = {
   "invitation-updated": XOInvitation;
   "invitation-status-changed": string;
-  "error": Error;
+  error: Error;
 };
 
 export type InvitationDependencies = {
   syncServer: SyncServer;
-  storage: Storage;
+  storage: BaseStorage;
   engine: Engine;
-  electrum: ElectrumService;
+  electrum: BlockchainService;
 };
 
 export class Invitation extends EventEmitter<InvitationEventMap> {
@@ -85,8 +85,11 @@ export class Invitation extends EventEmitter<InvitationEventMap> {
       throw new Error(`Template not found: ${invitation.templateIdentifier}`);
     }
 
+    // engine invitation (I have no idea if this is required)
+    const engineInvitation = await dependencies.engine.acceptInvitation(invitation);
+
     // Create the invitation
-    const invitationInstance = new Invitation(invitation, dependencies);
+    const invitationInstance = new Invitation(engineInvitation, dependencies);
 
     // Start the invitation and its tracking
     await invitationInstance.start();
@@ -119,8 +122,8 @@ export class Invitation extends EventEmitter<InvitationEventMap> {
    * The storage instance.
    * TODO: This should be a composite with the sync server (probably. We currently double handle this work, which is stupid)
    */
-  private storage: Storage;
+  private storage: BaseStorage;
-  private electrum: ElectrumService;
+  private electrum: BlockchainService;
 
   /**
    * The status of the invitation (last emitted word: pending, actionable, signed, ready, complete, expired, unknown).
@@ -153,25 +156,25 @@ export class Invitation extends EventEmitter<InvitationEventMap> {
         this.syncServer.connect(),
         this.syncServer.getInvitation(this.data.invitationIdentifier),
       ]);
-  
+
       // There is a chance we get SSE messages before the invitation is returned, so we want to combine any commits
       const sseCommits = this.data.commits;
-  
+
       // Merge the commits
       const combinedCommits = this.mergeCommits(
         sseCommits,
         invitation?.commits ?? [],
       );
-  
+
       // Set the invitation data with the combined commits
       this.data = { ...this.data, ...invitation, commits: combinedCommits };
-  
+
       // Store the invitation in the storage
       await this.storage.set(this.data.invitationIdentifier, this.data);
-  
+
       // Publish the invitation to the sync server
       this.publishInvitation(this.data);
-  
+
       // Compute and emit initial status
       await this.updateStatus();
     } catch (err) {
@@ -215,7 +218,9 @@ export class Invitation extends EventEmitter<InvitationEventMap> {
   /**
    * Publish the invitation to the sync server
    */
-  private async publishInvitation(invitation: XOInvitation = this.data): Promise<void> {
+  private async publishInvitation(
+    invitation: XOInvitation = this.data,
+  ): Promise<void> {
     try {
       await this.syncServer.publishInvitation(invitation);
     } catch (err) {
@@ -481,13 +486,50 @@ export class Invitation extends EventEmitter<InvitationEventMap> {
   }
 
   async findSuitableResources(
-    options: Partial<FindSuitableResourcesParameters> = {},
+    options: Partial<GetSpendableResourcesParameters> = {},
   ): Promise<UnspentOutputData[]> {
-    // Find the suitable resources
+    const templateIdentifier =
-    const { unspentOutputs } = await this.engine.findSuitableResources(
+      options.templateIdentifier ?? this.data.templateIdentifier;
-      this.data,
+    const template = await this.engine.getTemplate(templateIdentifier);
-      options,
+    const fallbackOutputIdentifier = Object.keys(template?.outputs ?? {})[0];
-    );
+    if (!fallbackOutputIdentifier && !options.outputIdentifier) {
+      throw new Error(
+        `No output identifiers found for template: ${templateIdentifier}`,
+      );
+    }
+
+    // const resolvedOptions: GetSpendableResourcesParameters = {
+    //   templateIdentifier,
+    //   outputIdentifier: options.outputIdentifier ?? fallbackOutputIdentifier ?? "",
+    // };
+
+    // There are disagreements around whether all spendables should be returned from getSpendableResources.
+    // I had a fix merged in, but it got overwritten. So, im just going to get all of them manually and go around
+    // The engine's expectations.
+    // To do this, we are going to grab all out templates
+    const templates = await this.engine.listImportedTemplates();
+
+    // For each template, we need to create a 2d array of all the outputs
+    const outputs = templates.flatMap(template => {
+      return Object.keys(template.outputs).map(output => {
+        const templateIdentifier = generateTemplateIdentifier(template);
+
+        return {
+          templateIdentifier,
+          outputIdentifier: output,
+        };
+      });
+    });
+
+    // then, for each output, we need to get the spendable resources
+    const spendableResources = await Promise.all(outputs.map(output => {
+      return this.engine.getSpendableResources(this.data, {
+        templateIdentifier: output.templateIdentifier,
+        outputIdentifier: output.outputIdentifier,
+      });
+    }));
+
+    const unspentOutputs = spendableResources.flatMap(resource => resource.unspentOutputs);
 
     // Update the status of the invitation
     await this.updateStatus();

src/services/rates.ts

@@ -0,0 +1,217 @@
+import { EventEmitter } from '../utils/event-emitter.js';
+import {
+  type RatesEventMap,
+} from '../utils/rates/base-rates.js';
+import { RatesOracle } from '../utils/rates/rates-oracles.js';
+import { SettingsService } from './settings.js';
+
+/**
+ * Event map emitted by {@link RatesService}.
+ */
+export type RatesServiceEventMap = {
+  'rate-updated': {
+    numeratorUnitCode: string;
+    denominatorUnitCode: string;
+    price: number;
+    pair: string;
+    updatedAt: number;
+  };
+};
+
+/**
+ * In-memory representation of a market rate.
+ */
+type CachedRate = {
+  price: number;
+  updatedAt: number;
+};
+
+/**
+ * Minimal adapter contract that RatesService depends on.
+ *
+ * Using a small interface keeps the service decoupled and avoids inheriting
+ * implementation-specific type constraints from concrete adapters.
+ */
+export interface RatesAdapter {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  listPairs(): Promise<Set<string>>;
+  formatCurrency(amount: number, targetCurrency: string): string;
+  on(
+    type: 'rateUpdated',
+    listener: (detail: RatesEventMap['rateUpdated']) => void,
+  ): () => void;
+}
+
+/**
+ * Orchestrates the rates adapter lifecycle and provides BCH -> fiat helpers
+ * for the TUI.
+ *
+ * This service keeps a small in-memory snapshot of the latest prices and emits
+ * a normalized event whenever a pair changes. React components can subscribe
+ * through `useSyncExternalStore` for clean and predictable reactivity.
+ */
+export class RatesService extends EventEmitter<RatesServiceEventMap> {
+  private readonly adapter: RatesAdapter;
+  private readonly settings: SettingsService;
+  private readonly ratesByPair = new Map<string, CachedRate>();
+  private unsubscribeFromAdapter: (() => void) | null = null;
+  private started = false;
+
+  constructor(adapter: RatesAdapter, settings: SettingsService) {
+    super();
+    this.adapter = adapter;
+    this.settings = settings;
+  }
+
+  /**
+   * Creates a rates service.
+   *
+   * If no adapter is passed, this defaults to the Oracle-backed adapter.
+   */
+  public static async create(
+    settings: SettingsService,
+    adapter?: RatesAdapter,
+  ): Promise<RatesService> {
+    const resolvedAdapter = adapter ?? (await RatesOracle.from(undefined, settings));
+    return new RatesService(resolvedAdapter, settings);
+  }
+
+  /**
+   * Starts the underlying adapter and begins collecting live updates.
+   */
+  public async start(): Promise<void> {
+    if (this.started) {
+      return;
+    }
+    this.started = true;
+
+    this.unsubscribeFromAdapter = this.adapter.on('rateUpdated', (event) => {
+      this.handleRateUpdated(event);
+    });
+
+    try {
+      await this.adapter.start();
+    } catch (error) {
+      this.unsubscribeFromAdapter?.();
+      this.unsubscribeFromAdapter = null;
+      this.started = false;
+      throw error;
+    }
+  }
+
+  /**
+   * Stops live rate collection.
+   */
+  public async stop(): Promise<void> {
+    if (!this.started) {
+      return;
+    }
+    this.started = false;
+
+    this.unsubscribeFromAdapter?.();
+    this.unsubscribeFromAdapter = null;
+
+    await this.adapter.stop();
+  }
+
+  /**
+   * Returns the latest price for a pair in NUMERATOR/DENOMINATOR form.
+   *
+   * Example: `getRate("USD", "BCH")`.
+   */
+  public getRate(
+    numeratorUnitCode: string,
+    denominatorUnitCode: string,
+  ): number | null {
+    const pair = this.getPairKey(numeratorUnitCode, denominatorUnitCode);
+    return this.ratesByPair.get(pair)?.price ?? null;
+  }
+
+  /**
+   * Converts satoshis to fiat using the latest BCH/fiat rate.
+   *
+   * Example: `convertBchToFiat(1234n, "USD")`.
+   */
+  public convertBchToFiat(
+    satoshis: bigint,
+    targetCurrency: string = 'USD',
+  ): number | null {
+    const rate = this.getRate(targetCurrency, 'BCH');
+    if (rate === null) {
+      return null;
+    }
+
+    const amountInBch = Number(satoshis) / 100_000_000;
+    return amountInBch * rate;
+  }
+
+  /**
+   * Formats a BCH -> fiat converted amount using the adapter formatter.
+   */
+  public formatBchToFiat(
+    satoshis: bigint,
+    targetCurrency: string = 'USD',
+  ): string | null {
+    const normalizedCurrency = targetCurrency.toUpperCase();
+    const amount = this.convertBchToFiat(satoshis, normalizedCurrency);
+    if (amount === null) {
+      return null;
+    }
+    return this.adapter.formatCurrency(amount, normalizedCurrency);
+  }
+
+  /**
+   * Formats an arbitrary fiat amount in a currency-aware way.
+   */
+  public formatCurrency(amount: number, currencyCode: string): string {
+    return this.adapter.formatCurrency(amount, currencyCode.toUpperCase());
+  }
+
+  /**
+   * Lists available market pairs in NUMERATOR/DENOMINATOR format.
+   */
+  public async listPairs(): Promise<Set<string>> {
+    return this.adapter.listPairs();
+  }
+
+  /**
+   * Returns the fiat currency currently configured in settings.
+   */
+  public getConfiguredCurrency(): string {
+    return this.settings.getCurrency();
+  }
+
+  /**
+   * Handles normalized updates from the underlying adapter.
+   */
+  private handleRateUpdated(event: RatesEventMap['rateUpdated']): void {
+    const numeratorUnitCode = event.numeratorUnitCode.toUpperCase();
+    const denominatorUnitCode = event.denominatorUnitCode.toUpperCase();
+    const pair = this.getPairKey(numeratorUnitCode, denominatorUnitCode);
+    const updatedAt = Date.now();
+
+    this.ratesByPair.set(pair, {
+      price: event.price,
+      updatedAt,
+    });
+
+    this.emit('rate-updated', {
+      numeratorUnitCode,
+      denominatorUnitCode,
+      price: event.price,
+      pair,
+      updatedAt,
+    });
+  }
+
+  /**
+   * Creates a stable key for pair lookups.
+   */
+  private getPairKey(
+    numeratorUnitCode: string,
+    denominatorUnitCode: string,
+  ): string {
+    return `${numeratorUnitCode.toUpperCase()}/${denominatorUnitCode.toUpperCase()}`;
+  }
+}

src/services/settings.ts

@@ -0,0 +1,194 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+
+import { EventEmitter } from "../utils/event-emitter.js";
+import { getSettingsPath } from "../utils/paths.js";
+
+/**
+ * Supported persisted settings keys.
+ */
+export type SettingsData = {
+  "default-mnemonic"?: string;
+  currency: string;
+};
+
+/**
+ * Event payloads emitted by {@link SettingsService}.
+ */
+export type SettingsServiceEventMap = {
+  "settings-updated": {
+    key: keyof SettingsData;
+    value: string | undefined;
+    settings: SettingsData;
+  };
+};
+
+/**
+ * Runtime defaults for settings that should always exist in memory.
+ */
+const DEFAULT_SETTINGS: SettingsData = {
+  currency: "USD",
+};
+
+/**
+ * Handles loading, migrating, and persisting wallet settings.
+ *
+ * The backing file is `~/.config/xo-cli/.wallet`. Historically it stored a raw
+ * mnemonic reference string. This service migrates that legacy format to JSON:
+ * `{ "default-mnemonic": "<value>", "currency": "USD" }`.
+ */
+export class SettingsService extends EventEmitter<SettingsServiceEventMap> {
+  private readonly settingsPath: string;
+  private settings: SettingsData;
+
+  /**
+   * Creates a new settings service instance.
+   *
+   * @param settingsPath - Optional custom settings file path (useful for tests)
+   */
+  constructor(settingsPath: string = getSettingsPath()) {
+    super();
+    this.settingsPath = settingsPath;
+    this.settings = this.loadSettings();
+  }
+
+  /**
+   * Returns the current settings snapshot.
+   */
+  public getSettings(): SettingsData {
+    return { ...this.settings };
+  }
+
+  /**
+   * Returns the currently selected default mnemonic reference.
+   */
+  public getDefaultMnemonic(): string | undefined {
+    return this.settings["default-mnemonic"];
+  }
+
+  /**
+   * Updates the default mnemonic reference and persists it to disk.
+   */
+  public setDefaultMnemonic(mnemonicRef: string): void {
+    const normalizedMnemonicRef = mnemonicRef.trim();
+    if (normalizedMnemonicRef.length === 0) {
+      throw new Error("default-mnemonic cannot be empty");
+    }
+
+    this.settings["default-mnemonic"] = normalizedMnemonicRef;
+    this.persistSettings();
+
+    this.emit("settings-updated", {
+      key: "default-mnemonic",
+      value: normalizedMnemonicRef,
+      settings: this.getSettings(),
+    });
+  }
+
+  /**
+   * Returns the selected fiat currency code (ISO-like uppercase).
+   */
+  public getCurrency(): string {
+    return this.settings.currency;
+  }
+
+  /**
+   * Updates the selected fiat currency and persists it to disk.
+   */
+  public setCurrency(currencyCode: string): void {
+    const normalizedCurrency = this.normalizeCurrency(currencyCode);
+    if (this.settings.currency === normalizedCurrency) {
+      return;
+    }
+
+    this.settings.currency = normalizedCurrency;
+    this.persistSettings();
+
+    this.emit("settings-updated", {
+      key: "currency",
+      value: normalizedCurrency,
+      settings: this.getSettings(),
+    });
+  }
+
+  /**
+   * Reads and normalizes the settings file from disk.
+   *
+   * If the file contains the old legacy format (raw mnemonic string), the
+   * migrated JSON shape is written back immediately.
+   */
+  private loadSettings(): SettingsData {
+    if (!existsSync(this.settingsPath)) {
+      return { ...DEFAULT_SETTINGS };
+    }
+
+    const rawContents = readFileSync(this.settingsPath, "utf8").trim();
+    if (rawContents.length === 0) {
+      return { ...DEFAULT_SETTINGS };
+    }
+
+    try {
+      const parsed = JSON.parse(rawContents);
+      const normalized = this.normalizeSettings(parsed);
+      return normalized;
+    } catch {
+      const migrated = this.normalizeSettings({
+        "default-mnemonic": rawContents,
+      });
+      this.persistSettings(migrated);
+      return migrated;
+    }
+  }
+
+  /**
+   * Writes the given settings object to disk as pretty JSON.
+   *
+   * @param nextSettings - Optional explicit value, defaults to in-memory state
+   */
+  private persistSettings(nextSettings?: SettingsData): void {
+    if (nextSettings) {
+      this.settings = nextSettings;
+    }
+
+    writeFileSync(
+      this.settingsPath,
+      `${JSON.stringify(this.settings, null, 2)}\n`,
+      "utf8",
+    );
+  }
+
+  /**
+   * Coerces unknown input into a safe settings object.
+   */
+  private normalizeSettings(input: unknown): SettingsData {
+    const normalized: SettingsData = {
+      ...DEFAULT_SETTINGS,
+    };
+
+    if (!input || typeof input !== "object") {
+      return normalized;
+    }
+
+    const maybeMnemonic = (input as Record<string, unknown>)["default-mnemonic"];
+    if (typeof maybeMnemonic === "string" && maybeMnemonic.trim().length > 0) {
+      normalized["default-mnemonic"] = maybeMnemonic.trim();
+    }
+
+    const maybeCurrency = (input as Record<string, unknown>).currency;
+    if (typeof maybeCurrency === "string" && maybeCurrency.trim().length > 0) {
+      normalized.currency = this.normalizeCurrency(maybeCurrency);
+    }
+
+    return normalized;
+  }
+
+  /**
+   * Ensures currency values stay uppercase and non-empty.
+   */
+  private normalizeCurrency(currencyCode: string): string {
+    const normalizedCurrency = currencyCode.trim().toUpperCase();
+    if (normalizedCurrency.length === 0) {
+      throw new Error("currency cannot be empty");
+    }
+    return normalizedCurrency;
+  }
+}

src/services/storage.ts

@@ -1,7 +1,24 @@
 import Database from "better-sqlite3";
 import { decodeExtendedJson, encodeExtendedJson } from "../utils/ext-json.js";
 
-export class Storage {
+/**
+ * This is not an actual storage adapter that we want to make use of. This storage adapter is a stop-gap while the engine is under development.
+ * At the time of writing the storage adapter, the engine provided no way to read data about your currenty invitations, so that is where this is coming in.
+ * Its providing a Developer facing way to store/read the invitation data and then we can just import them into the engine whenever we want to interact with an invitation.
+ */
+export abstract class BaseStorage {
+  abstract all(): Promise<{ key: string; value: any }[]>;
+  abstract set(key: string, value: any): Promise<void>;
+  abstract get(key: string): Promise<any>;
+  abstract remove(key: string): Promise<void>;
+  abstract clear(): Promise<void>;
+  abstract child(key: string): BaseStorage;
+}
+
+/**
+ * SQLite Database Storage Adapter.
+ */
+export class Storage extends BaseStorage {
   static async create(dbPath: string): Promise<Storage> {
     // Create the database
     const database = new Database(dbPath);
@@ -19,7 +36,9 @@ export class Storage {
   constructor(
     private readonly database: Database.Database,
     private readonly basePath: string,
-  ) {}
+  ) {
+    super();
+  }
 
   /**
    * Get the full key with basePath prefix
@@ -117,3 +136,107 @@ export class Storage {
     return new Storage(this.database, this.getFullKey(key));
   }
 }
+
+/**
+ * In-memory storage adapter with the same namespaced API as {@link Storage}.
+ *
+ * This adapter is useful for tests and short-lived sessions where persisted
+ * SQLite state is not needed.
+ * 
+ * TODO: Move this somewhere else. There is no reason for this to be in the main codebase. We should put this stricly in the tests beacuse that were its actually being used.
+ *       Ideally, we would provide these kind of generic fills as part of our packages somewhere, but these interfaces dont fit our current design.
+ */
+export class InMemoryStorage extends BaseStorage {
+  static async create(): Promise<InMemoryStorage> {
+    return new InMemoryStorage(new Map<string, string>(), "");
+  }
+
+  constructor(
+    private readonly store: Map<string, string>,
+    private readonly basePath: string,
+  ) {
+    super();
+  }
+
+  /**
+   * Get the full key with basePath prefix.
+   */
+  private getFullKey(key: string): string {
+    return this.basePath ? `${this.basePath}.${key}` : key;
+  }
+
+  /**
+   * Strip the basePath prefix from a key.
+   */
+  private stripBasePath(fullKey: string): string {
+    if (!this.basePath) return fullKey;
+    const prefix = `${this.basePath}.`;
+    return fullKey.startsWith(prefix) ? fullKey.slice(prefix.length) : fullKey;
+  }
+
+  async set(key: string, value: any): Promise<void> {
+    const fullKey = this.getFullKey(key);
+    const encodedValue = encodeExtendedJson(value);
+    this.store.set(fullKey, encodedValue);
+  }
+
+  /**
+   * Get all key-value pairs from this storage namespace (shallow only).
+   */
+  async all(): Promise<{ key: string; value: any }[]> {
+    const rows: Array<{ key: string; value: string }> = [];
+    const prefix = this.basePath ? `${this.basePath}.` : "";
+
+    for (const [key, value] of this.store.entries()) {
+      if (this.basePath && !key.startsWith(prefix)) continue;
+      rows.push({ key, value });
+    }
+
+    const filteredRows = rows.filter((row) => {
+      const strippedKey = this.stripBasePath(row.key);
+      return !strippedKey.includes(".");
+    });
+
+    return filteredRows.map((row) => ({
+      key: this.stripBasePath(row.key),
+      value: decodeExtendedJson(row.value),
+    }));
+  }
+
+  async get(key: string): Promise<any> {
+    const fullKey = this.getFullKey(key);
+    const encodedValue = this.store.get(fullKey);
+    if (encodedValue === undefined) return null;
+
+    return decodeExtendedJson(encodedValue);
+  }
+
+  async remove(key: string): Promise<void> {
+    const fullKey = this.getFullKey(key);
+    this.store.delete(fullKey);
+  }
+
+  async clear(): Promise<void> {
+    if (!this.basePath) {
+      this.store.clear();
+      return;
+    }
+
+    const prefix = `${this.basePath}.`;
+    const keysToDelete: string[] = [];
+
+    for (const key of this.store.keys()) {
+      if (key.startsWith(prefix)) {
+        keysToDelete.push(key);
+      }
+    }
+
+    for (const key of keysToDelete) {
+      this.store.delete(key);
+    }
+  }
+
+  child(key: string): InMemoryStorage {
+    return new InMemoryStorage(this.store, this.getFullKey(key));
+  }
+}

src/tui/components/CurrencySelectionDialog.tsx

@@ -0,0 +1,188 @@
+import React, { useEffect, useId, useMemo, useState } from "react";
+import { Box, Text } from "ink";
+
+import { ScrollableList, type ListItemData } from "./List.js";
+import TextInput from "./TextInput.js";
+import { DialogWrapper } from "./Dialog.js";
+import { useInputLayer, useLayeredInput } from "../hooks/useInputLayer.js";
+import { colors } from "../theme.js";
+
+/**
+ * Props for the currency selection dialog.
+ */
+interface CurrencySelectionDialogProps {
+  /** Current wallet currency from persisted settings. */
+  currentCurrency: string;
+  /** Available fiat numerator symbols that can be paired with BCH. */
+  currencies: string[];
+  /** True while the dialog is loading available pairs. */
+  isLoading: boolean;
+  /** Optional loading/error message for pair discovery. */
+  errorMessage: string | null;
+  /** Called when the user chooses a currency and confirms. */
+  onSelectCurrency: (currencyCode: string) => void;
+  /** Called when the dialog should close without applying changes. */
+  onCancel: () => void;
+}
+
+/**
+ * Currency picker dialog.
+ *
+ * UX requirements:
+ * - Arrow keys move the highlighted item.
+ * - Typing immediately filters results.
+ * - Enter applies current selection.
+ * - Escape closes without saving.
+ */
+export function CurrencySelectionDialog({
+  currentCurrency,
+  currencies,
+  isLoading,
+  errorMessage,
+  onSelectCurrency,
+  onCancel,
+}: CurrencySelectionDialogProps): React.ReactElement {
+  const layerId = useId();
+  const [filterText, setFilterText] = useState("");
+  const [selectedIndex, setSelectedIndex] = useState(0);
+
+  // Mount this as a capturing input layer so background screens stop handling keys.
+  useInputLayer(layerId);
+
+  /**
+   * Applies the currently selected filtered result.
+   */
+  const applySelection = (): void => {
+    const selectedCurrency = filteredCurrencies[selectedIndex];
+    if (!selectedCurrency) {
+      return;
+    }
+    onSelectCurrency(selectedCurrency);
+  };
+
+  useLayeredInput(layerId, (_input, key) => {
+    if (key.escape) {
+      onCancel();
+      return;
+    }
+
+    if (key.upArrow) {
+      setSelectedIndex((prev) =>
+        prev <= 0 ? Math.max(filteredCurrencies.length - 1, 0) : prev - 1,
+      );
+      return;
+    }
+
+    if (key.downArrow) {
+      setSelectedIndex((prev) =>
+        filteredCurrencies.length === 0
+          ? 0
+          : prev >= filteredCurrencies.length - 1
+            ? 0
+            : prev + 1,
+      );
+      return;
+    }
+
+  });
+
+  /**
+   * Filter currencies as the user types.
+   */
+  const filteredCurrencies = useMemo(() => {
+    const normalizedFilter = filterText.trim().toUpperCase();
+    if (!normalizedFilter) {
+      return currencies;
+    }
+    return currencies.filter((currencyCode) =>
+      currencyCode.toUpperCase().includes(normalizedFilter),
+    );
+  }, [currencies, filterText]);
+
+  /**
+   * Keep selected index valid whenever filtering shrinks the result set.
+   */
+  useEffect(() => {
+    if (filteredCurrencies.length === 0) {
+      setSelectedIndex(0);
+      return;
+    }
+
+    if (selectedIndex >= filteredCurrencies.length) {
+      setSelectedIndex(filteredCurrencies.length - 1);
+    }
+  }, [filteredCurrencies, selectedIndex]);
+
+  /**
+   * When the dialog opens or the list updates, default to current currency.
+   */
+  useEffect(() => {
+    if (filterText.trim().length > 0) {
+      return;
+    }
+
+    const currentIndex = filteredCurrencies.findIndex(
+      (currencyCode) => currencyCode.toUpperCase() === currentCurrency.toUpperCase(),
+    );
+    if (currentIndex >= 0) {
+      setSelectedIndex(currentIndex);
+    }
+  }, [filteredCurrencies, currentCurrency, filterText]);
+
+  const listItems: ListItemData<string>[] = filteredCurrencies.map(
+    (currencyCode) => ({
+      key: currencyCode,
+      label: currencyCode,
+      description:
+        currencyCode.toUpperCase() === currentCurrency.toUpperCase()
+          ? "(current)"
+          : undefined,
+      value: currencyCode,
+    }),
+  );
+
+  return (
+    <DialogWrapper title="Select Fiat Currency" borderColor={colors.info} width={64}>
+      <Text color={colors.textMuted}>
+        Available BCH quote pairs are loaded from the live rates adapter.
+      </Text>
+
+      <Box marginTop={1}>
+        <Text color={colors.primary}>Filter:</Text>
+      </Box>
+      <Box borderStyle="single" borderColor={colors.focus} paddingX={1}>
+        <TextInput
+          value={filterText}
+          onChange={setFilterText}
+          onSubmit={() => applySelection()}
+          placeholder="Type currency code (e.g. USD, AUD)..."
+          focus
+        />
+      </Box>
+
+      <Box marginTop={1} flexDirection="column">
+        {isLoading ? (
+          <Text color={colors.textMuted}>Loading available pairs...</Text>
+        ) : errorMessage ? (
+          <Text color={colors.error}>{errorMessage}</Text>
+        ) : (
+          <ScrollableList
+            items={listItems}
+            selectedIndex={selectedIndex}
+            onSelect={setSelectedIndex}
+            onActivate={() => applySelection()}
+            focus={false}
+            maxVisible={8}
+            emptyMessage="No BCH quote pairs match this filter."
+          />
+        )}
+      </Box>
+
+      <Box marginTop={1}>
+        <Text color={colors.textMuted}>
+          Type to filter • ↑↓ navigate • Enter apply • Esc cancel
+        </Text>
+      </Box>
+    </DialogWrapper>
+  );
+}

src/tui/components/QRCode.tsx

@@ -47,6 +47,8 @@ interface QRCodeProps {
   dialogTitle?: string;
   /** Whether to display the raw encoded value as copyable text above the QR code. */
   showValue?: boolean;
+  /** Optional subtitle to display below the QR code. */
+  subtitle?: React.ReactNode;
 }
 
 /**
@@ -155,6 +157,7 @@ export function QRCode({
   dialog = false,
   dialogTitle = 'QR Code',
   showValue = false,
+  subtitle = null,
 }: QRCodeProps): React.ReactElement {
   const { rows, moduleCount } = useMemo(() => {
     const matrix = generateMatrix(value);
@@ -190,6 +193,7 @@ export function QRCode({
     return (
       <DialogWrapper title={dialogTitle} borderColor={colors.primary} width={dialogWidth}>
         {qrContent}
+        {subtitle}
       </DialogWrapper>
     );
   }

src/tui/components/VariableInputField.tsx

@@ -1,6 +1,7 @@
-import React from "react";
+import React, { useMemo } from "react";
 import { Box, Text } from "ink";
 import TextInput from "./TextInput.js";
+import { useSatoshisConversion } from "../hooks/useSatoshisConversion.js";
 
 interface VariableInputFieldProps {
   variable: {
@@ -18,6 +19,45 @@ interface VariableInputFieldProps {
   focusColor: string;
 }
 
+const SATOSHIS_PER_BCH = 100_000_000n;
+
+/**
+ * Returns true when the variable is an integer satoshis field.
+ */
+function isSatoshisVariable(variable: VariableInputFieldProps["variable"]): boolean {
+  return (
+    variable.type === "integer" &&
+    variable.hint?.toLowerCase().includes("satoshi") === true
+  );
+}
+
+/**
+ * Parse a strict integer string into bigint.
+ */
+function parseSatoshis(value: string): bigint | null {
+  const trimmed = value.trim();
+  if (!/^[-]?\d+$/.test(trimmed)) {
+    return null;
+  }
+
+  try {
+    return BigInt(trimmed);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format satoshis as BCH with fixed 8 decimals, preserving bigint precision.
+ */
+function formatBchFromSatoshis(satoshis: bigint): string {
+  const sign = satoshis < 0n ? "-" : "";
+  const absolute = satoshis < 0n ? satoshis * -1n : satoshis;
+  const whole = absolute / SATOSHIS_PER_BCH;
+  const fractional = absolute % SATOSHIS_PER_BCH;
+  return `${sign}${whole.toString()}.${fractional.toString().padStart(8, "0")} BCH`;
+}
+
 export function VariableInputField({
   variable,
   index,
@@ -27,6 +67,26 @@ export function VariableInputField({
   borderColor,
   focusColor,
 }: VariableInputFieldProps): React.ReactElement {
+  const { currencyCode, formattedFiatPerBchRate, formatSatoshisToFiat } =
+    useSatoshisConversion();
+  const satoshisValue = useMemo(
+    () => parseSatoshis(variable.value),
+    [variable.value],
+  );
+  const formattedBch = useMemo(() => {
+    if (satoshisValue === null) {
+      return null;
+    }
+    return formatBchFromSatoshis(satoshisValue);
+  }, [satoshisValue]);
+  const formattedFiat = useMemo(() => {
+    if (satoshisValue === null) {
+      return null;
+    }
+    return formatSatoshisToFiat(satoshisValue);
+  }, [satoshisValue, formatSatoshisToFiat]);
+  const shouldShowSatoshisConversion = isSatoshisVariable(variable);
+
   return (
     <Box flexDirection="column" marginBottom={1}>
       <Text color={focusColor}>{variable.name}</Text>
@@ -54,12 +114,29 @@ export function VariableInputField({
         <Text color={borderColor} dimColor>{variable.hint}</Text>
         
       </Box>
-      {variable.type === 'integer' && variable.hint === 'satoshis' && (
+      {shouldShowSatoshisConversion && (
-        <Box>
+        <Box flexDirection="column">
-          <Text color={borderColor} dimColor>
+          {formattedBch ? (
-            {/* Convert from sats to bch. NOTE: we can't use the formatSatoshis function because it is too verbose and returns too many values in the string*/}
+            <>
-            {(Number(variable.value) / 100_000_000).toFixed(8)} BCH
+              <Text color={borderColor} dimColor>
-          </Text>
+                {formattedBch}
+              </Text>
+              <Text color={borderColor} dimColor>
+                {formattedFiat
+                  ? `Approx. ${currencyCode}: ${formattedFiat}`
+                  : `Approx. ${currencyCode}: waiting for live rate...`}
+              </Text>
+              {formattedFiatPerBchRate && (
+                <Text color={borderColor} dimColor>
+                  1 BCH = {formattedFiatPerBchRate}
+                </Text>
+              )}
+            </>
+          ) : (
+            <Text color={borderColor} dimColor>
+              Enter a whole satoshi amount to preview BCH/{currencyCode} conversion.
+            </Text>
+          )}
         </Box>
       )}
     </Box>

src/tui/hooks/index.ts

@@ -23,3 +23,5 @@ export {
   useBlockableInput,
   useIsInputCaptured,
 } from "./useInputLayer.js";
+export { useRate, useBchToFiatRate } from "./useRates.js";
+export { useSatoshisConversion } from "./useSatoshisConversion.js";

src/tui/hooks/useRates.tsx

@@ -0,0 +1,68 @@
+import { useCallback, useMemo, useSyncExternalStore } from 'react';
+import type { RatesServiceEventMap } from '../../services/rates.js';
+import { useAppContext } from './useAppContext.js';
+
+/**
+ * Reactive hook for a single market pair.
+ *
+ * Pair format is NUMERATOR / DENOMINATOR, e.g. USD / BCH.
+ */
+export function useRate(
+  numeratorUnitCode: string,
+  denominatorUnitCode: string,
+): number | null {
+  const { appService } = useAppContext();
+
+  const normalizedNumerator = useMemo(
+    () => numeratorUnitCode.toUpperCase(),
+    [numeratorUnitCode],
+  );
+  
+  const normalizedDenominator = useMemo(
+    () => denominatorUnitCode.toUpperCase(),
+    [denominatorUnitCode],
+  );
+
+  const subscribe = useCallback(
+    (callback: () => void) => {
+      if (!appService) {
+        return () => {};
+      }
+
+      const onRateUpdated = (event: RatesServiceEventMap['rate-updated']) => {
+        if (
+          event.numeratorUnitCode === normalizedNumerator &&
+          event.denominatorUnitCode === normalizedDenominator
+        ) {
+          callback();
+        }
+      };
+
+      const unsubscribe = appService.rates.on('rate-updated', onRateUpdated);
+
+      return () => {
+        unsubscribe();
+      };
+    },
+    [appService, normalizedNumerator, normalizedDenominator],
+  );
+
+  const getSnapshot = useCallback(() => {
+    if (!appService) {
+      return null;
+    }
+
+    return appService.rates.getRate(normalizedNumerator, normalizedDenominator);
+  }, [appService, normalizedNumerator, normalizedDenominator]);
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+
+/**
+ * Convenience hook for BCH -> fiat market rates.
+ */
+export function useBchToFiatRate(
+  targetCurrency: string = 'USD',
+): number | null {
+  return useRate(targetCurrency, 'BCH');
+}

src/tui/hooks/useSatoshisConversion.tsx

@@ -0,0 +1,73 @@
+import { useCallback, useMemo, useSyncExternalStore } from 'react';
+import { useAppContext } from './useAppContext.js';
+import { useBchToFiatRate } from './useRates.js';
+
+/**
+ * Reactive BCH satoshis -> fiat conversion helpers for TUI screens.
+ *
+ * This hook subscribes to rate updates through `useBchToFiatRate`, so any
+ * component using it will re-render automatically when the selected pair
+ * receives a new quote.
+ */
+export function useSatoshisConversion(targetCurrency?: string) {
+  const { appService } = useAppContext();
+  const subscribeToCurrency = useCallback(
+    (callback: () => void) => {
+      if (!appService || targetCurrency) {
+        return () => {};
+      }
+
+      return appService.settings.on('settings-updated', (event) => {
+        if (event.key === 'currency') {
+          callback();
+        }
+      });
+    },
+    [appService, targetCurrency],
+  );
+
+  const getCurrencySnapshot = useCallback(() => {
+    if (targetCurrency) {
+      return targetCurrency.toUpperCase();
+    }
+
+    if (!appService) {
+      return 'USD';
+    }
+
+    return appService.settings.getCurrency();
+  }, [appService, targetCurrency]);
+
+  const currencyCode = useSyncExternalStore(
+    subscribeToCurrency,
+    getCurrencySnapshot,
+    getCurrencySnapshot,
+  );
+  const fiatPerBchRate = useBchToFiatRate(currencyCode);
+
+  const formattedFiatPerBchRate = useMemo(() => {
+    if (!appService || fiatPerBchRate === null) {
+      return null;
+    }
+
+    return appService.rates.formatCurrency(fiatPerBchRate, currencyCode);
+  }, [appService, fiatPerBchRate, currencyCode]);
+
+  const formatSatoshisToFiat = useCallback(
+    (satoshis: bigint): string | null => {
+      if (!appService || fiatPerBchRate === null) {
+        return null;
+      }
+
+      return appService.rates.formatBchToFiat(satoshis, currencyCode);
+    },
+    [appService, fiatPerBchRate, currencyCode],
+  );
+
+  return {
+    currencyCode,
+    fiatPerBchRate,
+    formattedFiatPerBchRate,
+    formatSatoshisToFiat,
+  } as const;
+}

src/tui/screens/SeedInput.tsx

@@ -16,8 +16,10 @@ import { colors, logo } from '../theme.js';
 
 import fs from 'fs';
 import path from 'path';
+import { createMnemonicFile } from '../../cli/mnemonic.js';
+import { getMnemonicsDir } from '../../utils/paths.js';
 import { BCHMnemonicURL } from '../../utils/bch-mnemonic-url.js';
-import { encodeBip39Mnemonic } from '@bitauth/libauth';
+import { encodeBip39Mnemonic, generateBip39Mnemonic } from '@bitauth/libauth';
 
 /**
  * Status message type.
@@ -39,33 +41,41 @@ interface MnemonicFileEntry {
  * Focus sections the user can tab between.
  * When saved wallets exist the file list is shown first.
  */
-type FocusSection = 'files' | 'input' | 'button';
+type FocusSection = 'files' | 'input' | 'saveCheckbox' | 'generateRandomSeed' | 'button';
 
 /**
- * Reads mnemonic-* files from cwd, parses each as a BCHMnemonicURL,
+ * Reads mnemonic-* files from ~/.config/xo-cli/mnemonics/ (same as xo-cli),
- * and converts the entropy back to a BIP39 English mnemonic phrase.
+ * then from cwd for legacy installs. Parses each as a BCHMnemonicURL.
  */
 function loadMnemonicFiles(): MnemonicFileEntry[] {
-  const cwd = process.cwd();
+  const dirs = [getMnemonicsDir(), process.cwd()];
-  const filenames = fs.readdirSync(cwd).filter((f) => f.startsWith('mnemonic-'));
+  const seenBasenames = new Set<string>();
   const entries: MnemonicFileEntry[] = [];
 
-  for (const filename of filenames) {
+  for (const dir of dirs) {
-    try {
+    if (!fs.existsSync(dir)) continue;
-      const content = fs.readFileSync(path.join(cwd, filename), 'utf-8').trim();
+    const filenames = fs
-      const parsed = BCHMnemonicURL.fromURL(content);
+      .readdirSync(dir)
-      const raw = parsed.toObject();
+      .filter((f) => f.startsWith('mnemonic-'));
+    for (const filename of filenames) {
+      if (seenBasenames.has(filename)) continue;
+      try {
+        const content = fs.readFileSync(path.join(dir, filename), 'utf-8').trim();
+        const parsed = BCHMnemonicURL.fromURL(content);
+        const raw = parsed.toObject();
 
-      const mnemonicResult = encodeBip39Mnemonic(raw.entropy);
+        const mnemonicResult = encodeBip39Mnemonic(raw.entropy);
-      if (typeof mnemonicResult === 'string') continue;
+        if (typeof mnemonicResult === 'string') continue;
 
-      /** Use the URL comment as the label, falling back to a cleaned-up filename. */
+        /** Use the URL comment as the label, falling back to a cleaned-up filename. */
-      const label = raw.comment
+        const label = raw.comment
-        ?? filename.replace(/^mnemonic-/, '').replace(/\.[^.]+$/, '');
+          ?? filename.replace(/^mnemonic-/, '').replace(/\.[^.]+$/, '');
 
-      entries.push({ filename, label, mnemonic: mnemonicResult.phrase });
+        entries.push({ filename, label, mnemonic: mnemonicResult.phrase });
-    } catch {
+        seenBasenames.add(filename);
-      // Skip files that can't be parsed
+      } catch {
+        // Skip files that can't be parsed
+      }
     }
   }
   return entries;
@@ -91,6 +101,9 @@ export function SeedInputScreen(): React.ReactElement {
   const [mnemonicFiles, setMnemonicFiles] = useState<MnemonicFileEntry[]>([]);
   const [selectedFileIndex, setSelectedFileIndex] = useState(0);
 
+  /** When set, manual seed is written to ~/.config/xo-cli/mnemonics/ after a successful unlock. */
+  const [saveMnemonicChecked, setSaveMnemonicChecked] = useState(false);
+
   // Focus: when saved wallets exist default to the file list, otherwise the input.
   const [focusedSection, setFocusedSection] = useState<FocusSection>('input');
 
@@ -104,8 +117,8 @@ export function SeedInputScreen(): React.ReactElement {
    * The ordered list of focusable sections (files section only when entries exist).
    */
   const focusSections: FocusSection[] = mnemonicFiles.length > 0
-    ? ['files', 'input', 'button']
+    ? ['files', 'input', 'generateRandomSeed', 'saveCheckbox', 'button']
-    : ['input', 'button'];
+    : ['input', 'generateRandomSeed', 'saveCheckbox', 'button'];
 
   /**
    * Shows a status message with the given type.
@@ -118,28 +131,46 @@ export function SeedInputScreen(): React.ReactElement {
   /**
    * Shared wallet initialization handler used by both manual entry and file selection.
    */
-  const doInitialize = useCallback(async (seed: string) => {
+  const doInitialize = useCallback(
-    showStatus('Initializing wallet...', 'loading');
+    async (seed: string, options?: { saveMnemonic?: boolean }) => {
-    setStatus('Initializing wallet...');
+      showStatus('Initializing wallet...', 'loading');
-    setIsSubmitting(true);
+      setStatus('Initializing wallet...');
+      setIsSubmitting(true);
 
-    try {
+      try {
-      await initializeWallet(seed);
+        await initializeWallet(seed);
 
-      showStatus('Wallet initialized successfully!', 'success');
+        let statusText = 'Wallet initialized successfully!';
-      setStatus('Wallet ready');
+        if (options?.saveMnemonic) {
-      setSeedPhrase('');
+          try {
+            const savedAs = createMnemonicFile(getMnemonicsDir(), seed);
+            setMnemonicFiles(loadMnemonicFiles());
+            statusText = `Wallet initialized! Mnemonic saved as ${savedAs}`;
+          } catch (saveErr) {
+            const saveMsg =
+              saveErr instanceof Error ? saveErr.message : String(saveErr);
+            statusText = `Wallet initialized, but could not save mnemonic: ${saveMsg}`;
+          }
+        }
 
-      setTimeout(() => {
+        showStatus(statusText, 'success');
-        navigate('wallet');
+        setStatus('Wallet ready');
-      }, 500);
+        setSeedPhrase('');
-    } catch (error) {
+        setSaveMnemonicChecked(false);
-      const message = error instanceof Error ? error.message : 'Failed to initialize wallet';
+
-      showStatus(message, 'error');
+        setTimeout(() => {
-      setStatus('Initialization failed');
+          navigate('wallet');
-      setIsSubmitting(false);
+        }, 500);
-    }
+      } catch (error) {
-  }, [initializeWallet, navigate, showStatus, setStatus]);
+        const message =
+          error instanceof Error ? error.message : 'Failed to initialize wallet';
+        showStatus(message, 'error');
+        setStatus('Initialization failed');
+        setIsSubmitting(false);
+      }
+    },
+    [initializeWallet, navigate, showStatus, setStatus],
+  );
 
   /**
    * Handles manual seed phrase submission with validation.
@@ -158,8 +189,8 @@ export function SeedInputScreen(): React.ReactElement {
       return;
     }
 
-    await doInitialize(seed);
+    await doInitialize(seed, { saveMnemonic: saveMnemonicChecked });
-  }, [seedPhrase, doInitialize, showStatus]);
+  }, [seedPhrase, saveMnemonicChecked, doInitialize, showStatus]);
 
   /**
    * Handles selecting a mnemonic file from the list.
@@ -171,7 +202,7 @@ export function SeedInputScreen(): React.ReactElement {
   }, [mnemonicFiles, doInitialize]);
 
   // Keyboard navigation
-  useBlockableInput((_input, key) => {
+  useBlockableInput((input, key) => {
     if (isSubmitting) return;
 
     // Tab / Shift-Tab to cycle focus sections
@@ -186,6 +217,14 @@ export function SeedInputScreen(): React.ReactElement {
       return;
     }
 
+    // Space or Enter toggles "save mnemonic" when that row is focused
+    if (focusedSection === 'saveCheckbox') {
+      if (input === ' ' || key.return) {
+        setSaveMnemonicChecked((v) => !v);
+        return;
+      }
+    }
+
     // Arrow keys inside the file list
     if (focusedSection === 'files' && mnemonicFiles.length > 0) {
       if (key.upArrow) {
@@ -202,6 +241,18 @@ export function SeedInputScreen(): React.ReactElement {
       }
     }
 
+    // Ctrl-R generates a random seed phrase and fills it in the input
+    if (key.ctrl && input === 'r') {
+      setSeedPhrase(generateBip39Mnemonic());
+      return;
+    }
+
+    // If pressing enter while the generate random seed section is focused, generate a random seed and fill it in the input
+    if (key.return && focusedSection === 'generateRandomSeed') {
+      setSeedPhrase(generateBip39Mnemonic());
+      return;
+    }
+
     // Enter on button submits manual seed
     if (key.return && focusedSection === 'button') {
       handleSubmit();
@@ -319,6 +370,45 @@ export function SeedInputScreen(): React.ReactElement {
           />
         </Box>
 
+        {/* Generate random seed phrase and fill in the input */}
+        <Box marginTop={1}>
+          <Box
+            paddingX={1}
+            paddingY={0}
+            backgroundColor={focusedSection === 'generateRandomSeed' ? colors.focus : colors.bgSelected}
+          >
+            <Text color={focusedSection === 'generateRandomSeed' ? colors.bg : colors.text} bold>Generate Random Seed</Text>
+          </Box>
+
+          <Text color={colors.textMuted}> (Ctrl-R)</Text>
+        </Box>
+
+        {/* Save mnemonic checkbox (manual entry only; applies on Continue) */}
+        <Box
+          marginTop={1}
+          paddingX={1}
+          borderStyle='single'
+          borderColor={
+            focusedSection === 'saveCheckbox' ? colors.focus : colors.borderMuted
+          }
+        >
+          <Text
+            color={focusedSection === 'saveCheckbox' ? colors.focus : colors.text}
+            bold={focusedSection === 'saveCheckbox'}
+          >
+            {saveMnemonicChecked ? '[x] ' : '[ ] '}
+          </Text>
+          <Text color={colors.text}>Save this mnemonic</Text>
+          <Text color={colors.textMuted}> (~/.config/xo-cli/mnemonics/)</Text>
+        </Box>
+        {focusedSection === 'saveCheckbox' && (
+          <Box marginTop={0} paddingX={1}>
+            <Text color={colors.textMuted} dimColor>
+              Space / Enter: toggle
+            </Text>
+          </Box>
+        )}
+
         {/* Status message */}
         <Box marginTop={1} height={1}>
           {statusMessage && (
@@ -345,7 +435,7 @@ export function SeedInputScreen(): React.ReactElement {
       {/* Help text */}
       <Box marginTop={2}>
         <Text color={colors.textMuted} dimColor>
-          Tab: navigate sections • Enter: submit • Esc: back
+          Tab: navigate • Enter: submit, load wallet, or toggle save • Space: toggle save • Esc: back
         </Text>
       </Box>
     </Box>

src/tui/screens/TemplateList.tsx

@@ -100,8 +100,8 @@ export function TemplateListScreen(): React.ReactElement {
           for (const startingAction of rawStartingActions) {
             const existing = actionMap.get(startingAction.action);
             if (existing) {
-              if (!existing.roles.includes(startingAction.role)) {
+              if (!existing.roles.includes(startingAction.role ?? '')) {
-                existing.roles.push(startingAction.role);
+                existing.roles.push(startingAction.role ?? '');
               }
               continue;
             }
@@ -111,7 +111,7 @@ export function TemplateListScreen(): React.ReactElement {
               actionIdentifier: startingAction.action,
               name: actionDef?.name || startingAction.action,
               description: actionDef?.description,
-              roles: [startingAction.role],
+              roles: [startingAction.role ?? ''],
               source: 'starting',
             });
           }
@@ -119,9 +119,9 @@ export function TemplateListScreen(): React.ReactElement {
           const ownedOutputIdentifiers = ownedOutputsByTemplate.get(templateIdentifier) ?? new Set<string>();
           for (const outputIdentifier of ownedOutputIdentifiers) {
             const outputDef = template.outputs?.[outputIdentifier];
-            if (!outputDef || typeof outputDef.lockscript !== 'string') continue;
+            if (!outputDef || typeof outputDef.lockingScript !== 'string') continue;
 
-            const lockingScriptDefinition = (template.lockingScripts as Record<string, unknown> | undefined)?.[outputDef.lockscript] as
+            const lockingScriptDefinition = (template.lockingScripts as Record<string, unknown> | undefined)?.[outputDef.lockingScript] as
               | { roles?: Record<string, { actions?: Array<{ action?: string; role?: string } | string> }> }
               | undefined;
             if (!lockingScriptDefinition?.roles) continue;
@@ -217,14 +217,10 @@ export function TemplateListScreen(): React.ReactElement {
         action.roles.length,
         index
       );
-      const sourceSuffix = action.source === 'next'
+
-        ? ' [next]'
-        : action.source === 'starting+next'
-          ? ' [start+next]'
-          : '';
       return {
         key: action.actionIdentifier,
-        label: `${formatted.label}${sourceSuffix}`,
+        label: `${formatted.label}`,
         description: formatted.description,
         value: action,
         hidden: !formatted.isValid,

src/tui/screens/WalletState.tsx

@@ -11,8 +11,10 @@ import React, { useState, useEffect, useCallback, useMemo } from 'react';
 import { Box, Text } from 'ink';
 import { ScrollableList, type ListItemData } from '../components/List.js';
 import { QRCode } from '../components/QRCode.js';
+import { CurrencySelectionDialog } from '../components/CurrencySelectionDialog.js';
 import { useNavigation } from '../hooks/useNavigation.js';
 import { useAppContext, useStatus } from '../hooks/useAppContext.js';
+import { useSatoshisConversion } from '../hooks/useSatoshisConversion.js';
 import { useInputLayer, useLayeredInput, useBlockableInput, useIsInputCaptured } from '../hooks/useInputLayer.js';
 import { colors, formatSatoshis, formatHex, logoSmall } from '../theme.js';
 import type { HistoryItem } from '../../services/history.js';
@@ -28,6 +30,7 @@ import {
   type HistoryDisplayRow,
   type HistoryColorName,
 } from '../../utils/history-utils.js';
+import { copyToClipboard } from '../utils/clipboard.js';
 
 /**
  * Map history color name to theme color.
@@ -58,6 +61,7 @@ const menuItems: ListItemData<string>[] = [
   { key: 'import', label: 'Import Invitation', value: 'import' },
   { key: 'invitations', label: 'View Invitations', value: 'invitations' },
   { key: 'new-address', label: 'Generate New Address', value: 'new-address' },
+  { key: 'set-currency', label: 'Set Fiat Currency', value: 'set-currency' },
   { key: 'unreserve-all', label: 'Unreserve All Resources', value: 'unreserve-all' },
   { key: 'refresh', label: 'Refresh', value: 'refresh' },
 ];
@@ -74,7 +78,10 @@ type HistoryListItem = ListItemData<HistoryDisplayRow>;
 function QRDialogOverlay({ address, onClose }: { address: string; onClose: () => void }): React.ReactElement {
   useInputLayer('qr-dialog');
 
-  useLayeredInput('qr-dialog', (_input, key) => {
+  useLayeredInput('qr-dialog', (input, key) => {
+    if (input === 'c' || input === 'C') {
+      copyToClipboard(address);
+    }
     if (key.escape || key.return) {
       onClose();
     }
@@ -92,10 +99,13 @@ function QRDialogOverlay({ address, onClose }: { address: string; onClose: () =>
         dialog
         dialogTitle="Receive Address"
         showValue
+        subtitle={
+          <Box flexDirection="column" justifyContent="center" marginTop={1}>
+            <Text color={colors.textMuted}>Press C to copy to clipboard</Text>
+            <Text color={colors.textMuted}>Press Enter or Esc to close</Text>
+          </Box>
+        }
       />
-      <Box justifyContent="center" marginTop={1}>
-        <Text color={colors.textMuted}>Press Enter or Esc to close</Text>
-      </Box>
     </Box>
   );
 }
@@ -108,6 +118,12 @@ export function WalletStateScreen(): React.ReactElement {
   const { navigate } = useNavigation();
   const { appService, showError, showInfo } = useAppContext();
   const { setStatus } = useStatus();
+  const {
+    currencyCode,
+    fiatPerBchRate,
+    formattedFiatPerBchRate,
+    formatSatoshisToFiat,
+  } = useSatoshisConversion();
 
   // State
   const [balance, setBalance] = useState<{ totalSatoshis: bigint; utxoCount: number } | null>(null);
@@ -119,6 +135,14 @@ export function WalletStateScreen(): React.ReactElement {
 
   /** Cash address to display in the QR code dialog (null when dialog is hidden). */
   const [qrAddress, setQrAddress] = useState<string | null>(null);
+  /** Whether the fiat currency selection dialog is open. */
+  const [isCurrencyDialogOpen, setCurrencyDialogOpen] = useState(false);
+  /** Loading state for rates pair discovery. */
+  const [isLoadingCurrencyPairs, setLoadingCurrencyPairs] = useState(false);
+  /** Optional error message shown in the currency dialog. */
+  const [currencyPairsError, setCurrencyPairsError] = useState<string | null>(null);
+  /** Available fiat currencies derived from rates pairs in X/BCH format. */
+  const [availableCurrencies, setAvailableCurrencies] = useState<string[]>([]);
 
   /**
    * Refreshes wallet state.
@@ -246,6 +270,89 @@ export function WalletStateScreen(): React.ReactElement {
     }
   }, [appService, setStatus, showError, showInfo, refresh]);
 
+  /**
+   * Loads all available rates pairs, then extracts fiat numerator symbols from
+   * pairs shaped like X/BCH.
+   *
+   * We retry briefly because rates startup is asynchronous and metadata can take
+   * a moment to hydrate right after wallet initialization.
+   */
+  const loadAvailableCurrencies = useCallback(async (): Promise<void> => {
+    if (!appService) {
+      setCurrencyPairsError("AppService not initialized");
+      return;
+    }
+
+    setLoadingCurrencyPairs(true);
+    setCurrencyPairsError(null);
+
+    try {
+      let pairs = new Set<string>();
+
+      // Retry a few times so we can catch late metadata initialization.
+      for (let attempt = 0; attempt < 4; attempt += 1) {
+        pairs = await appService.rates.listPairs();
+        if (pairs.size > 0) {
+          break;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 200));
+      }
+
+      const currencies = Array.from(pairs)
+        .map((pair) => pair.toUpperCase())
+        .filter((pair) => pair.endsWith("/BCH"))
+        .map((pair) => pair.split("/")[0] ?? "")
+        .filter((currency) => currency.length > 0)
+        .sort((a, b) => a.localeCompare(b));
+
+      const uniqueCurrencies = Array.from(new Set(currencies));
+      setAvailableCurrencies(uniqueCurrencies);
+
+      if (uniqueCurrencies.length === 0) {
+        setCurrencyPairsError(
+          "No X/BCH rates are currently available. Try again in a moment.",
+        );
+      }
+    } catch (error) {
+      setCurrencyPairsError(
+        `Failed to load currency pairs: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    } finally {
+      setLoadingCurrencyPairs(false);
+    }
+  }, [appService]);
+
+  /**
+   * Opens the fiat currency dialog and triggers pair discovery.
+   */
+  const openCurrencyDialog = useCallback(() => {
+    setCurrencyDialogOpen(true);
+    void loadAvailableCurrencies();
+  }, [loadAvailableCurrencies]);
+
+  /**
+   * Applies the selected fiat currency to persisted settings.
+   */
+  const applyCurrencySelection = useCallback(
+    (currencyCode: string) => {
+      if (!appService) {
+        showError("AppService not initialized");
+        return;
+      }
+
+      try {
+        appService.settings.setCurrency(currencyCode);
+        setStatus(`Fiat currency updated to ${currencyCode}`);
+        setCurrencyDialogOpen(false);
+      } catch (error) {
+        showError(
+          `Failed to update currency: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    },
+    [appService, setStatus, showError],
+  );
+
   /**
    * Handles menu action.
    */
@@ -263,6 +370,9 @@ export function WalletStateScreen(): React.ReactElement {
       case 'new-address':
         generateNewAddress();
         break;
+      case 'set-currency':
+        openCurrencyDialog();
+        break;
       case 'unreserve-all':
         unreserveAll();
         break;
@@ -270,7 +380,7 @@ export function WalletStateScreen(): React.ReactElement {
         refresh();
         break;
     }
-  }, [navigate, generateNewAddress, unreserveAll, refresh]);
+  }, [navigate, generateNewAddress, openCurrencyDialog, unreserveAll, refresh]);
 
   /**
    * Handle menu item activation.
@@ -297,6 +407,26 @@ export function WalletStateScreen(): React.ReactElement {
     });
   }, [history]);
 
+  /**
+   * Fiat values are memoized so we only recompute when balance or rate changes.
+   */
+  const formattedUsdPerBchRate = useMemo(() => {
+    return formattedFiatPerBchRate;
+  }, [formattedFiatPerBchRate]);
+
+  const formattedUsdBalance = useMemo(() => {
+    if (!balance || fiatPerBchRate === null) {
+      return null;
+    }
+
+    return formatSatoshisToFiat(balance.totalSatoshis);
+  }, [balance, fiatPerBchRate, formatSatoshisToFiat]);
+
+  const getFiatSuffix = useCallback((satoshis: bigint): string => {
+    const fiatValue = formatSatoshisToFiat(satoshis);
+    return fiatValue ? ` (~${fiatValue})` : '';
+  }, [formatSatoshisToFiat]);
+
   // Screen input — automatically blocked when any dialog/overlay is capturing.
   const isCaptured = useIsInputCaptured();
 
@@ -323,24 +453,32 @@ export function WalletStateScreen(): React.ReactElement {
     const indicator = isFocused ? '▸ ' : '  ';
     const groupingPrefix = row.isNested ? '  -> ' : '';
 
-    if (row.type === 'invitation') {
+    if (row.type === 'history_item') {
+      const sats = row.valueSatoshis ?? 0n;
+      const fiatSuffix = getFiatSuffix(sats);
       return (
         <Box flexDirection="row" justifyContent="space-between">
-          <Text color={itemColor}>
+          <Box flexDirection="row">
-            {indicator}[Invitation] {row.label}
+            <Text color={itemColor}>
-          </Text>
+              {indicator}{formatSatoshis(sats)}{fiatSuffix}
+            </Text>
+            <Text color={colors.textMuted}> {row.label}</Text>
+          </Box>
           {dateStr && <Text color={colors.textMuted}>{dateStr}</Text>}
         </Box>
       );
     }
 
-    if (row.type === 'invitation_input') {
+    if (row.type === 'history_input') {
+      const sats = row.valueSatoshis ?? 0n;
       return (
         <Box flexDirection="row" justifyContent="space-between">
           <Box>
             <Text color={itemColor}>
-              {indicator}{groupingPrefix}[Input] {row.label}
+              {indicator}{groupingPrefix}[Input] {formatSatoshis(sats)}
+              {getFiatSuffix(sats)}
             </Text>
+            <Text color={colors.textMuted}> {row.label}</Text>
             {row.description && <Text color={colors.textMuted}> {row.description}</Text>}
           </Box>
           {dateStr && <Text color={colors.textMuted}>{dateStr}</Text>}
@@ -348,14 +486,17 @@ export function WalletStateScreen(): React.ReactElement {
       );
     }
 
-    if (row.type === 'invitation_output') {
+    if (row.type === 'history_output') {
-      const sats = row.utxo?.valueSatoshis ?? 0n;
+      const sats = row.valueSatoshis ?? 0n;
+      const reservedTag = row.reserved ? ' [Reserved]' : '';
       return (
         <Box flexDirection="row" justifyContent="space-between">
           <Box flexDirection="row">
             <Text color={itemColor}>
               {indicator}{groupingPrefix}[Output] {formatSatoshis(sats)}
+              {getFiatSuffix(sats)}
             </Text>
+            <Text color={colors.textMuted}> {row.label}{reservedTag}</Text>
             {row.description && <Text color={colors.textMuted}> {row.description}</Text>}
           </Box>
           {dateStr && <Text color={colors.textMuted}>{dateStr}</Text>}
@@ -363,20 +504,6 @@ export function WalletStateScreen(): React.ReactElement {
       );
     }
 
-    if (row.type === 'utxo') {
-      const sats = row.utxo?.valueSatoshis ?? 0n;
-      const reservedTag = row.utxo?.reserved ? ' [Reserved]' : '';
-      return (
-        <Box flexDirection="row" justifyContent="space-between">
-          <Box flexDirection="row">
-            <Text color={itemColor}>{indicator}{formatSatoshis(sats)}</Text>
-            {row.description && <Text color={colors.textMuted}> {row.description}{reservedTag}</Text>}
-          </Box>
-          {dateStr && <Text color={colors.textMuted}>{dateStr}</Text>}
-        </Box>
-      );
-    }
-
     // Fallback for other types
     return (
       <Box flexDirection="row" justifyContent="space-between">
@@ -386,7 +513,7 @@ export function WalletStateScreen(): React.ReactElement {
         {dateStr && <Text color={colors.textMuted}>{dateStr}</Text>}
       </Box>
     );
-  }, []);
+  }, [getFiatSuffix]);
 
   return (
     <Box flexDirection="column" flexGrow={1}>
@@ -418,6 +545,20 @@ export function WalletStateScreen(): React.ReactElement {
                   <Text color={colors.success} bold>
                     {formatSatoshis(balance.totalSatoshis)}
                   </Text>
+                  {formattedUsdBalance ? (
+                    <Text color={colors.info}>
+                      Approx. Fiat ({currencyCode}): {formattedUsdBalance}
+                    </Text>
+                  ) : (
+                    <Text color={colors.textMuted}>
+                      Approx. Fiat ({currencyCode}): Waiting for BCH/{currencyCode} rate...
+                    </Text>
+                  )}
+                  {formattedUsdPerBchRate && (
+                    <Text color={colors.textMuted}>
+                      1 BCH = {formattedUsdPerBchRate}
+                    </Text>
+                  )}
                   <Text color={colors.textMuted}>
                     UTXOs: {balance.utxoCount}
                   </Text>
@@ -465,7 +606,7 @@ export function WalletStateScreen(): React.ReactElement {
           height={14}
           overflow="hidden"
         >
-          <Text color={colors.primary} bold> Wallet History {history.length > 0 ? `(${selectedHistoryIndex + 1}/${history.length})` : ''}</Text>
+          <Text color={colors.primary} bold> Wallet History {historyListItems.length > 0 ? `(${selectedHistoryIndex + 1}/${historyListItems.length})` : ''}</Text>
           {isLoading ? (
             <Box marginTop={1}>
               <Text color={colors.textMuted}>Loading...</Text>
@@ -498,6 +639,27 @@ export function WalletStateScreen(): React.ReactElement {
           onClose={() => setQrAddress(null)}
         />
       )}
+
+      {/* Fiat currency selection dialog overlay */}
+      {isCurrencyDialogOpen && (
+        <Box
+          position="absolute"
+          flexDirection="column"
+          alignItems="center"
+          justifyContent="center"
+          width="100%"
+          height="100%"
+        >
+          <CurrencySelectionDialog
+            currentCurrency={currencyCode}
+            currencies={availableCurrencies}
+            isLoading={isLoadingCurrencyPairs}
+            errorMessage={currencyPairsError}
+            onSelectCurrency={applyCurrencySelection}
+            onCancel={() => setCurrencyDialogOpen(false)}
+          />
+        </Box>
+      )}
     </Box>
   );
 }

src/tui/screens/action-wizard/flows/index.ts

@@ -15,7 +15,7 @@ export { DataWizardFlow } from "./DataWizardFlow.js";
  */
 export function createWizardFlow(action: XOTemplateAction): WizardFlow {
   if (action.data?.length && !action.transaction) {
-    return new DataWizardFlow(action.data);
+    return new DataWizardFlow([action.data]);
   }
   return new TransactionWizardFlow();
 }

src/tui/screens/action-wizard/steps/InputsStep.tsx

@@ -1,6 +1,7 @@
 import React from 'react';
 import { Box, Text } from 'ink';
 import { colors, formatSatoshis, formatHex } from '../../../theme.js';
+import { useSatoshisConversion } from '../../../hooks/useSatoshisConversion.js';
 import type { SelectableUTXO, FocusArea } from '../types.js';
 
 interface Props {
@@ -22,6 +23,13 @@ export function InputsStep({
   changeAmount,
   focusArea,
 }: Props): React.ReactElement {
+  const { formatSatoshisToFiat } = useSatoshisConversion();
+
+  const getFiatSuffix = (satoshis: bigint): string => {
+    const fiatValue = formatSatoshisToFiat(satoshis);
+    return fiatValue ? ` (~${fiatValue})` : '';
+  };
+
   return (
     <Box flexDirection='column'>
       <Text color={colors.text} bold>
@@ -32,6 +40,7 @@ export function InputsStep({
         <Text color={colors.textMuted}>
           Required: {formatSatoshis(requiredAmount)} +{' '}
           {formatSatoshis(fee)} fee
+          {getFiatSuffix(requiredAmount + fee)}
         </Text>
         <Text
           color={
@@ -41,10 +50,12 @@ export function InputsStep({
           }
         >
           Selected: {formatSatoshis(selectedAmount)}
+          {getFiatSuffix(selectedAmount)}
         </Text>
         {selectedAmount > requiredAmount + fee && (
           <Text color={colors.info}>
             Change: {formatSatoshis(changeAmount)}
+            {getFiatSuffix(changeAmount)}
           </Text>
         )}
       </Box>
@@ -65,6 +76,7 @@ export function InputsStep({
             return (
               <Box
                 key={`${utxo.outpointTransactionHash}:${utxo.outpointIndex}`}
+                flexDirection='column'
               >
                 <Text
                   color={isCursor ? colors.focus : colors.text}
@@ -75,6 +87,15 @@ export function InputsStep({
                   {formatHex(utxo.outpointTransactionHash, 12)}:
                   {utxo.outpointIndex}
                 </Text>
+                {(() => {
+                  const fiatValue = formatSatoshisToFiat(utxo.valueSatoshis);
+                  if (!fiatValue) return null;
+                  return (
+                    <Text color={colors.textMuted}>
+                      {'   '}≈ {fiatValue}
+                    </Text>
+                  );
+                })()}
               </Box>
             );
           })

src/tui/screens/action-wizard/steps/ReviewStep.tsx

@@ -1,6 +1,7 @@
 import React from 'react';
 import { Box, Text } from 'ink';
 import { colors, formatSatoshis } from '../../../theme.js';
+import { useSatoshisConversion } from '../../../hooks/useSatoshisConversion.js';
 import type { VariableInput, SelectableUTXO } from '../types.js';
 import type { XOTemplate } from '@xo-cash/types';
 
@@ -22,6 +23,32 @@ export function ReviewStep({
   changeAmount,
 }: ReviewStepProps): React.ReactElement {
   const selectedUtxos = availableUtxos.filter((u) => u.selected);
+  const { formatSatoshisToFiat } = useSatoshisConversion();
+
+  const getFiatSuffix = (satoshis: bigint): string => {
+    const fiatValue = formatSatoshisToFiat(satoshis);
+    return fiatValue ? ` (~${fiatValue})` : '';
+  };
+
+  const getVariableFiatSuffix = (variable: VariableInput): string => {
+    if (variable.type !== 'integer') {
+      return '';
+    }
+
+    if (variable.hint?.toLowerCase().includes('satoshi') !== true) {
+      return '';
+    }
+
+    if (!/^[-]?\d+$/.test(variable.value.trim())) {
+      return '';
+    }
+
+    try {
+      return getFiatSuffix(BigInt(variable.value));
+    } catch {
+      return '';
+    }
+  };
 
   return (
     <Box flexDirection='column'>
@@ -44,6 +71,7 @@ export function ReviewStep({
             <Text key={v.id} color={colors.textMuted}>
               {'  '}
               {v.name}: {v.value || '(empty)'}
+              {v.value ? getVariableFiatSuffix(v) : ''}
             </Text>
           ))}
         </Box>
@@ -62,6 +90,7 @@ export function ReviewStep({
             >
               {'  '}
               {formatSatoshis(u.valueSatoshis)}
+              {getFiatSuffix(u.valueSatoshis)}
             </Text>
           ))}
           {selectedUtxos.length > 3 && (
@@ -78,6 +107,7 @@ export function ReviewStep({
           <Text color={colors.text}>Outputs:</Text>
           <Text color={colors.textMuted}>
             {'  '}Change: {formatSatoshis(changeAmount)}
+            {getFiatSuffix(changeAmount)}
           </Text>
         </Box>
       )}

src/tui/screens/action-wizard/steps/RoleSelectStep.tsx

@@ -61,13 +61,16 @@ export function RoleSelectStep({
         {availableRoles.length === 0 ? (
           <Text color={colors.textMuted}>No roles available</Text>
         ) : (
-          availableRoles.map((roleId, index) => {
+          availableRoles.map((roleId: string, index: number) => {
             const isCursor =
               selectedRoleIndex === index && focusArea === 'content';
             const roleDef = template.roles?.[roleId];
             const actionRole = action?.roles?.[roleId];
             const requirements = actionRole?.requirements;
 
+            const actionRequirements = action?.requirements;
+            const actionRoleRequirements = actionRole && actionRequirements && actionRequirements.participants?.find((participant) => participant.role === roleId);
+
             return (
               <Box key={roleId} flexDirection="column" marginY={0}>
                 <Text
@@ -96,10 +99,10 @@ export function RoleSelectStep({
                         {'  '}
                       </Text>
                     )}
-                    {requirements.slots && requirements.slots.min > 0 && (
+                    {actionRoleRequirements && actionRoleRequirements.slots && actionRoleRequirements.slots.min > 0 && (
                       <Text color={colors.textMuted} dimColor>
-                        {requirements.slots.min} input slot
+                        {actionRoleRequirements.slots.min} input slot
-                        {requirements.slots.min !== 1 ? 's' : ''}
+                        {actionRoleRequirements.slots.min !== 1 ? 's' : ''}
                       </Text>
                     )}
                   </Box>

src/tui/screens/invitations/InvitationScreen.tsx

@@ -17,10 +17,11 @@ import { useNavigation } from '../../hooks/useNavigation.js';
 import { useAppContext, useStatus } from '../../hooks/useAppContext.js';
 import { useBlockableInput, useIsInputCaptured } from '../../hooks/useInputLayer.js';
 import { useInvitations } from '../../hooks/useInvitations.js';
+import { useSatoshisConversion } from '../../hooks/useSatoshisConversion.js';
 import { colors, logoSmall, formatSatoshis } from '../../theme.js';
 import { copyToClipboard } from '../../utils/clipboard.js';
 import type { Invitation } from '../../../services/invitation.js';
-import type { XOTemplate } from '@xo-cash/types';
+import type { XOInvitationCommit, XOInvitationVariableValue, XOTemplate } from '@xo-cash/types';
 
 import {
   getInvitationState,
@@ -28,12 +29,12 @@ import {
   getInvitationInputs,
   getInvitationOutputs,
   getInvitationVariables,
-  getUserRole,
   formatInvitationListItem,
   formatInvitationId,
 } from '../../../utils/invitation-utils.js';
 
 import { InvitationImportFlow } from './invitation-import/InvitationImportFlow.js';
+import { compileCashAssemblyString } from '@xo-cash/engine';
 
 /**
  * Map state color name to theme color.
@@ -79,6 +80,29 @@ const invitationListGroups: ListGroup[] = [
   { id: 'invitations', separator: true },
 ];
 
+type OwnInvitationContext = {
+  entityIdentifier: string | null;
+  roleIdentifier: string | null;
+};
+
+function getRoleIdentifierFromCommits(commits: XOInvitationCommit[]): string | null {
+  for (const commit of commits) {
+    for (const input of commit.data.inputs ?? []) {
+      if (input.roleIdentifier) return input.roleIdentifier;
+    }
+
+    for (const output of commit.data.outputs ?? []) {
+      if (output.roleIdentifier) return output.roleIdentifier;
+    }
+
+    for (const variable of commit.data.variables ?? []) {
+      if (variable.roleIdentifier) return variable.roleIdentifier;
+    }
+  }
+
+  return null;
+}
+
 /**
  * Invitation Screen Component.
  */
@@ -88,6 +112,8 @@ export function InvitationScreen(): React.ReactElement {
   const { setStatus } = useStatus();
 
   const invitations = useInvitations();
+  const { currencyCode, formattedFiatPerBchRate, formatSatoshisToFiat } =
+    useSatoshisConversion();
 
   // ── UI state ─────────────────────────────────────────────────────────────
   const [selectedIndex, setSelectedIndex] = useState(0);
@@ -99,10 +125,15 @@ export function InvitationScreen(): React.ReactElement {
   // Two phases: first the ID input dialog, then the multi-step import flow.
   const [showIdDialog, setShowIdDialog] = useState(false);
   const [importingId, setImportingId] = useState<string | null>(null);
+  const [pendingImportedInvitationId, setPendingImportedInvitationId] = useState<string | null>(null);
 
   // ── Template cache ───────────────────────────────────────────────────────
   const [templateCache, setTemplateCache] = useState<Map<string, XOTemplate>>(new Map());
   const [selectedTemplate, setSelectedTemplate] = useState<XOTemplate | null>(null);
+  const [ownInvitationContext, setOwnInvitationContext] = useState<OwnInvitationContext>({
+    entityIdentifier: null,
+    roleIdentifier: null,
+  });
 
   // Check if we should open import dialog on mount
   const initialMode = navData.mode as string | undefined;
@@ -158,7 +189,7 @@ export function InvitationScreen(): React.ReactElement {
     });
 
     return [importItem, ...invitationItems];
-  }, [invitations, templateCache]);
+  }, [invitations.length, templateCache]);
 
   const selectedItem = listItems[selectedIndex];
   const selectedInvitation = selectedItem?.value ?? null;
@@ -176,6 +207,43 @@ export function InvitationScreen(): React.ReactElement {
       .then(template => setSelectedTemplate(template ?? null));
   }, [selectedInvitation, appService]);
 
+  /**
+   * Load the current engine entity's commits for the selected invitation.
+   */
+  useEffect(() => {
+    if (!selectedInvitation || !appService) {
+      setOwnInvitationContext({
+        entityIdentifier: null,
+        roleIdentifier: null,
+      });
+      return;
+    }
+
+    let isCurrent = true;
+
+    appService.engine.getOwnCommits(selectedInvitation.data)
+      .then((ownCommits) => {
+        if (!isCurrent) return;
+
+        setOwnInvitationContext({
+          entityIdentifier: ownCommits[0]?.entityIdentifier ?? null,
+          roleIdentifier: getRoleIdentifierFromCommits(ownCommits),
+        });
+      })
+      .catch(() => {
+        if (!isCurrent) return;
+
+        setOwnInvitationContext({
+          entityIdentifier: null,
+          roleIdentifier: null,
+        });
+      });
+
+    return () => {
+      isCurrent = false;
+    };
+  }, [selectedInvitation, appService]);
+
   // ── Import flow callbacks ──────────────────────────────────────────────
 
   /**
@@ -193,10 +261,30 @@ export function InvitationScreen(): React.ReactElement {
   /**
    * Import flow closed (completed or cancelled).
    */
-  const handleImportFlowClose = useCallback(() => {
+  const handleImportFlowClose = useCallback((importedInvitationId?: string) => {
+    if (importedInvitationId) {
+      setPendingImportedInvitationId(importedInvitationId);
+    }
     setImportingId(null);
   }, []);
 
+  /**
+   * Once imported invitation is visible in the list, select and focus it.
+   */
+  useEffect(() => {
+    if (!pendingImportedInvitationId) return;
+
+    const importedIndex = listItems.findIndex((item) => {
+      return item.value?.data.invitationIdentifier === pendingImportedInvitationId;
+    });
+
+    if (importedIndex >= 0) {
+      setSelectedIndex(importedIndex);
+      setFocusedPanel('list');
+      setPendingImportedInvitationId(null);
+    }
+  }, [pendingImportedInvitationId, listItems]);
+
   // ── Action handlers ────────────────────────────────────────────────────
 
   const acceptInvitation = useCallback(async () => {
@@ -327,10 +415,10 @@ export function InvitationScreen(): React.ReactElement {
       const seenLockingBytecodes = new Set<string>();
 
       for (const utxo of utxos) {
-        const lockingBytecodeHex = utxo.lockingBytecode
+        const lockingBytecodeHex = utxo.scriptHash
-          ? typeof utxo.lockingBytecode === 'string'
+          ? typeof utxo.scriptHash === 'string'
-            ? utxo.lockingBytecode
+            ? utxo.scriptHash
-            : Buffer.from(utxo.lockingBytecode).toString('hex')
+            : Buffer.from(utxo.scriptHash).toString('hex')
           : undefined;
 
         if (lockingBytecodeHex && seenLockingBytecodes.has(lockingBytecodeHex)) continue;
@@ -488,12 +576,49 @@ export function InvitationScreen(): React.ReactElement {
     const inputs = getInvitationInputs(selectedInvitation);
     const outputs = getInvitationOutputs(selectedInvitation);
     const variables = getInvitationVariables(selectedInvitation);
-
+    const userEntityId = ownInvitationContext.entityIdentifier;
-    const userEntityId = selectedInvitation.data.commits?.[0]?.entityIdentifier ?? null;
+    const userRole = ownInvitationContext.roleIdentifier;
-    const userRole = getUserRole(selectedInvitation, userEntityId);
     const roleInfoRaw = userRole && selectedTemplate?.roles?.[userRole];
     const roleInfo = roleInfoRaw && typeof roleInfoRaw === 'object' ? roleInfoRaw : null;
 
+    const getFiatSuffix = (satoshis: bigint): string => {
+      const fiatValue = formatSatoshisToFiat(satoshis);
+      return fiatValue ? ` (~${fiatValue})` : '';
+    };
+
+    const parseNumberishToBigInt = (value: unknown): bigint | null => {
+      if (typeof value === 'bigint') {
+        return value;
+      }
+
+      const asString = String(value).trim();
+      if (!/^[-]?\d+$/.test(asString)) {
+        return null;
+      }
+
+      try {
+        return BigInt(asString);
+      } catch {
+        return null;
+      }
+    };
+
+    const isSatoshisVariable = (variableIdentifier: string): boolean => {
+      const templateVariable = selectedTemplate?.variables?.[variableIdentifier];
+      const templateType = templateVariable?.type?.toLowerCase();
+      const templateHint = templateVariable?.hint?.toLowerCase();
+      const identifier = variableIdentifier.toLowerCase();
+
+      if (templateHint?.includes('satoshi')) {
+        return true;
+      }
+
+      return (
+        templateType === 'integer' &&
+        (identifier.includes('satoshi') || identifier.includes('amount'))
+      );
+    };
+
     return (
       <Box flexDirection="column">
         {/* Type & Status */}
@@ -514,6 +639,11 @@ export function InvitationScreen(): React.ReactElement {
               <Text color={colors.textMuted}>
                 Action: {action?.name ?? selectedInvitation.data.actionIdentifier}
               </Text>
+              {formattedFiatPerBchRate && (
+                <Text color={colors.textMuted}>
+                  1 BCH = {formattedFiatPerBchRate}
+                </Text>
+              )}
               {action?.description && (
                 <Text color={colors.textMuted} dimColor>{action.description}</Text>
               )}
@@ -542,14 +672,28 @@ export function InvitationScreen(): React.ReactElement {
               inputs.map((input, idx) => {
                 const isUserInput = input.entityIdentifier === userEntityId;
                 const inputTemplate = selectedTemplate?.inputs?.[input.inputIdentifier ?? ''];
+                const inputSatoshis = (
+                  'valueSatoshis' in input && input.valueSatoshis !== undefined
+                )
+                  ? parseNumberishToBigInt(input.valueSatoshis)
+                  : null;
                 return (
                   <Text
                     key={`input-${idx}`}
                     color={isUserInput ? colors.success : colors.text}
                   >
+                    {/* Indicator for whether this is the user's input */}
                     {'  '}{isUserInput ? '• ' : '○ '}
+                    
+                    {/* TODO: Why doesnt this stuff work? It just cant resolve inputs? */}
+                    {/* Input name */}
                     {inputTemplate?.name ?? input.inputIdentifier ?? `Input ${idx}`}
+                    
+                    {/* Input role */}
                     {input.roleIdentifier && ` (${input.roleIdentifier})`}
+                    
+                    {/* Input value */}
+                    {inputSatoshis !== null && ` ${formatSatoshis(inputSatoshis)}${getFiatSuffix(inputSatoshis)}`}
                   </Text>
                 );
               })
@@ -564,14 +708,28 @@ export function InvitationScreen(): React.ReactElement {
               outputs.map((output, idx) => {
                 const isUserOutput = output.entityIdentifier === userEntityId;
                 const outputTemplate = selectedTemplate?.outputs?.[output.outputIdentifier ?? ''];
+                const outputSatoshis = output.valueSatoshis !== undefined
+                  ? parseNumberishToBigInt(output.valueSatoshis)
+                  : null;
                 return (
                   <Text
                     key={`output-${idx}`}
                     color={isUserOutput ? colors.success : colors.text}
                   >
+                    {/* Indicator for whether this is the user's output */}
                     {'  '}{isUserOutput ? '• ' : '○ '}
+
+                    {/* Output name */}
                     {outputTemplate?.name ?? output.outputIdentifier ?? `Output ${idx}`}
-                    {output.valueSatoshis !== undefined && ` (${formatSatoshis(output.valueSatoshis)})`}
+                    
+                    {/* Output description */}
+                    {outputTemplate?.description && ' - ' + compileCashAssemblyString(outputTemplate?.description ?? '', variables.reduce((acc, variable) => {
+                      acc[variable.variableIdentifier] = variable.value as XOInvitationVariableValue;
+                      return acc;
+                    }, {} as Record<string, XOInvitationVariableValue>))}
+                    
+                    {/* Output value */}
+                    {outputSatoshis !== null && ` (${formatSatoshis(outputSatoshis)}${getFiatSuffix(outputSatoshis)})`}
                   </Text>
                 );
               })
@@ -591,6 +749,9 @@ export function InvitationScreen(): React.ReactElement {
               const displayValue = typeof variable.value === 'bigint'
                 ? variable.value.toString()
                 : String(variable.value);
+              const parsedVariableSatoshis = isSatoshisVariable(variable.variableIdentifier)
+                ? parseNumberishToBigInt(variable.value)
+                : null;
               return (
                 <Text
                   key={`var-${idx}`}
@@ -598,6 +759,8 @@ export function InvitationScreen(): React.ReactElement {
                 >
                   {'  '}{isUserVariable ? '• ' : '○ '}
                   {varTemplate?.name ?? variable.variableIdentifier}: {displayValue}
+                  {parsedVariableSatoshis !== null &&
+                    ` (${formatSatoshis(parsedVariableSatoshis)}${getFiatSuffix(parsedVariableSatoshis)})`}
                   {varTemplate?.description && (
                     <Text color={colors.textMuted} dimColor> - {varTemplate.description}</Text>
                   )}

src/tui/screens/invitations/invitation-import/InvitationImportFlow.tsx

@@ -17,15 +17,15 @@ import { StepIndicator, type Step } from '../../../components/ProgressBar.js';
 import { FetchInvitationStep } from './steps/FetchInvitationStep.js';
 import { PreviewInvitationStep } from './steps/PreviewInvitationStep.js';
 import { RoleSelectStep } from './steps/RoleSelectStep.js';
+import { VariablesStep } from './steps/VariablesStep.js';
 import { InputsSelectStep } from './steps/InputsSelectStep.js';
 import { ReviewStep } from './steps/ReviewStep.js';
 
-import { IMPORT_STEPS, type ImportFlowProps, type SelectableUTXO } from './types.js';
+import { IMPORT_STEPS, type ImportFlowProps, type ImportStepType, type ImportVariableInput, type SelectableUTXO } from './types.js';
 import type { Invitation } from '../../../../services/invitation.js';
 import type { XOTemplate } from '@xo-cash/types';
 import { DialogWrapper } from '../../../components/Dialog.js';
 import { useInputLayer, useLayeredInput } from '../../../hooks/useInputLayer.js';
-import { InvitationBuilder } from '@xo-cash/engine';
 import { hexToBin } from '@bitauth/libauth';
 
 /** Default fee estimate in satoshis. */
@@ -34,6 +34,24 @@ const DEFAULT_FEE = 500n;
 /** Dust threshold — outputs below this are unspendable. */
 const DUST_THRESHOLD = 546n;
 
+/**
+ * Resolve the fixed index of a flow step from `IMPORT_STEPS`.
+ * We centralize this so step transitions do not rely on magic numbers.
+ */
+function getStepIndex(type: ImportStepType): number {
+  const index = IMPORT_STEPS.findIndex((step) => step.type === type);
+  if (index === -1) {
+    throw new Error(`Import step not found: ${type}`);
+  }
+  return index;
+}
+
+const PREVIEW_STEP_INDEX = getStepIndex('preview');
+const ROLE_SELECT_STEP_INDEX = getStepIndex('role-select');
+const VARIABLES_STEP_INDEX = getStepIndex('variables');
+const INPUTS_SELECT_STEP_INDEX = getStepIndex('inputs-select');
+const REVIEW_STEP_INDEX = getStepIndex('review');
+
 export function InvitationImportFlow({
   invitationId,
   mode,
@@ -46,10 +64,10 @@ export function InvitationImportFlow({
   // ── Accumulated state ────────────────────────────────────────────────────
   const [currentStep, setCurrentStep] = useState(0);
   const [invitation, setInvitation] = useState<Invitation | null>(null);
-  const [buildableInvitation, setBuildableInvitation] = useState<InvitationBuilder | null>(null);
   const [template, setTemplate] = useState<XOTemplate | null>(null);
   const [availableRoles, setAvailableRoles] = useState<string[]>([]);
   const [selectedRole, setSelectedRole] = useState<string | null>(null);
+  const [variableInputs, setVariableInputs] = useState<ImportVariableInput[]>([]);
   const [selectedInputs, setSelectedInputs] = useState<SelectableUTXO[]>([]);
   const [changeAmount, setChangeAmount] = useState(0n);
   const [requiredAmount, setRequiredAmount] = useState(0n);
@@ -79,9 +97,6 @@ export function InvitationImportFlow({
     setInvitation(inv);
     setTemplate(tmpl);
 
-    const builder = InvitationBuilder.fromInvitation(inv.data);
-    setBuildableInvitation(builder);
-
     try {
       const roles = await inv.getAvailableRoles();
       setAvailableRoles(roles);
@@ -89,20 +104,98 @@ export function InvitationImportFlow({
       showError(`Failed to get roles: ${err instanceof Error ? err.message : String(err)}`);
     }
 
-    setCurrentStep(1); // → Preview
+    setCurrentStep(PREVIEW_STEP_INDEX); // → Preview
   }, [showError]);
 
   /** PreviewStep completed — user reviewed the invitation state and wants to proceed. */
   const handlePreviewComplete = useCallback(() => {
-    setCurrentStep(2); // → Role Select
+    setCurrentStep(ROLE_SELECT_STEP_INDEX); // → Role Select
   }, []);
 
   /** RoleSelectStep completed — user picked a role. */
   const handleRoleComplete = useCallback((role: string) => {
     setSelectedRole(role);
-    setCurrentStep(3); // → Inputs Select
+
+    const action = template?.actions?.[invitation?.data.actionIdentifier ?? ""];
+    const roleRequirements = action?.roles?.[role]?.requirements?.variables ?? [];
+    const hasRequiredVariables = roleRequirements.length > 0;
+
+    if (!hasRequiredVariables) {
+      setVariableInputs([]);
+      setCurrentStep(INPUTS_SELECT_STEP_INDEX); // → Inputs Select
+      return;
+    }
+
+    const initializedVariables: ImportVariableInput[] = roleRequirements.map((variableId) => {
+      const variableDefinition = template?.variables?.[variableId];
+      return {
+        id: variableId,
+        name: variableDefinition?.name ?? variableId,
+        type: variableDefinition?.type ?? 'string',
+        hint: variableDefinition?.hint,
+        value: '',
+      };
+    });
+
+    setVariableInputs(initializedVariables);
+    setCurrentStep(VARIABLES_STEP_INDEX); // → Variables
+  }, [template, invitation]);
+
+  /** VariablesStep edited a field value. */
+  const handleVariableUpdate = useCallback((index: number, value: string) => {
+    setVariableInputs((previous) => {
+      const updated = [...previous];
+      const current = updated[index];
+      if (current) {
+        updated[index] = { ...current, value };
+      }
+      return updated;
+    });
   }, []);
 
+  /**
+   * Convert variable input value to its invitation payload representation.
+   * Numeric variables are persisted as bigint so they match action wizard behavior.
+   */
+  const parseVariableValue = useCallback((variable: ImportVariableInput) => {
+    const variableHint = variable.hint?.toLowerCase();
+    const isNumeric =
+      ['integer', 'number', 'satoshis'].includes(variable.type) ||
+      (variableHint !== undefined && ['satoshis', 'amount'].includes(variableHint));
+
+    if (!isNumeric) {
+      return variable.value;
+    }
+
+    return BigInt(variable.value || '0');
+  }, []);
+
+  /** VariablesStep completed — persist variables then continue to input selection. */
+  const handleVariablesComplete = useCallback(async () => {
+    if (!invitation || !selectedRole) return;
+
+    const emptyVariables = variableInputs.filter((variable) => variable.value.trim() === '');
+    if (emptyVariables.length > 0) {
+      showError(`Please enter values for: ${emptyVariables.map((variable) => variable.name).join(', ')}`);
+      return;
+    }
+
+    try {
+      await invitation.addVariables(
+        variableInputs.map((variable) => ({
+          variableIdentifier: variable.id,
+          roleIdentifier: selectedRole,
+          value: parseVariableValue(variable),
+        })),
+      );
+      setCurrentStep(INPUTS_SELECT_STEP_INDEX); // → Inputs Select
+    } catch (error) {
+      showError(
+        `Failed to add variables: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }, [invitation, selectedRole, variableInputs, parseVariableValue, showError]);
+
   /** InputsSelectStep completed — user selected UTXOs. */
   const handleInputsComplete = useCallback(async (inputs: SelectableUTXO[]) => {
     setSelectedInputs(inputs);
@@ -130,8 +223,8 @@ export function InvitationImportFlow({
       }]);
     }
 
-    setCurrentStep(4); // → Review
+    setCurrentStep(REVIEW_STEP_INDEX); // → Review
-  }, [invitation, buildableInvitation, selectedInputs]);
+  }, [invitation]);
 
   /** ReviewStep completed — invitation import is done. */
   const handleReviewComplete = useCallback(() => {
@@ -148,7 +241,7 @@ export function InvitationImportFlow({
       `Action: ${invitation?.data.actionIdentifier ?? 'Unknown'}`
     );
     setStatus('Ready');
-    onClose();
+    onClose(invitation?.data.invitationIdentifier);
   }, [selectedRole, template, invitation, showInfo, setStatus, onClose]);
 
   // ── Keyboard handling ────────────────────────────────────────────────────
@@ -205,6 +298,17 @@ export function InvitationImportFlow({
           />
         );
 
+      case 'variables':
+        return (
+          <VariablesStep
+            variables={variableInputs}
+            onUpdateVariable={handleVariableUpdate}
+            onComplete={handleVariablesComplete}
+            onCancel={handleCancel}
+            isActive={true}
+          />
+        );
+
       case 'inputs-select':
         if (!invitation || !selectedRole) return null;
         return (

src/tui/screens/invitations/invitation-import/steps/InputsSelectStep.tsx

@@ -9,6 +9,7 @@
 import React, { useState, useEffect, useCallback, useRef } from 'react';
 import { Box, Text } from 'ink';
 import { colors, formatSatoshis } from '../../../../theme.js';
+import { useSatoshisConversion } from '../../../../hooks/useSatoshisConversion.js';
 import { useLayeredInput } from '../../../../hooks/useInputLayer.js';
 import type { InputsSelectStepProps, SelectableUTXO } from '../types.js';
 import { autoSelectGreedyUtxos, mapUnspentOutputsToSelectable } from '../../../../../utils/invitation-flow.js';
@@ -32,6 +33,7 @@ export function InputsSelectStep({
   const [requiredAmount, setRequiredAmount] = useState(0n);
   const [isLoading, setIsLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
+  const { formatSatoshisToFiat } = useSatoshisConversion();
 
   const fee = DEFAULT_FEE;
 
@@ -42,6 +44,11 @@ export function InputsSelectStep({
   const changeAmount = selectedAmount - requiredAmount - fee;
   const hasEnough = selectedAmount >= requiredAmount + fee;
 
+  const getFiatSuffix = (satoshis: bigint): string => {
+    const fiatValue = formatSatoshisToFiat(satoshis);
+    return fiatValue ? ` (~${fiatValue})` : '';
+  };
+
   /**
    * Determine the required satoshi amount from the invitation's variables.
    */
@@ -94,10 +101,7 @@ export function InputsSelectStep({
       // Create a map of the utxoID to suitable resource
       const utxoIdToSuitableResource = new Map<string, UnspentOutputData>();
       for (const outputIdentifier of outputIdentifiers) {
-        const suitableResources = await invitation.findSuitableResources({
+        const suitableResources = await invitation.findSuitableResources();
-
-          outputIdentifier,
-        });
         for (const suitableResource of suitableResources) {
           utxoIdToSuitableResource.set(suitableResource.outpointTransactionHash + ':' + suitableResource.outpointIndex, suitableResource);
         }
@@ -196,18 +200,32 @@ export function InputsSelectStep({
       {/* Summary bar */}
       <Box flexDirection="row" marginBottom={1}>
         <Text color={colors.primary} bold>Required: </Text>
-        <Text color={colors.text}>{formatSatoshis(requiredAmount + fee)}</Text>
+        <Text color={colors.text}>
+          {formatSatoshis(requiredAmount + fee)}
+          {getFiatSuffix(requiredAmount + fee)}
+        </Text>
         <Text color={colors.textMuted}> (amount {formatSatoshis(requiredAmount)} + fee {formatSatoshis(fee)})</Text>
       </Box>
 
       <Box flexDirection="row" marginBottom={1}>
         <Text color={colors.primary} bold>Selected: </Text>
-        <Text color={hasEnough ? colors.success : colors.error}>{formatSatoshis(selectedAmount)}</Text>
+        <Text color={hasEnough ? colors.success : colors.error}>
+          {formatSatoshis(selectedAmount)}
+          {getFiatSuffix(selectedAmount)}
+        </Text>
         {hasEnough && changeAmount >= DUST_THRESHOLD && (
-          <Text color={colors.textMuted}> (change: {formatSatoshis(changeAmount)})</Text>
+          <Text color={colors.textMuted}>
+            {' '}
+            (change: {formatSatoshis(changeAmount)}
+            {getFiatSuffix(changeAmount)})
+          </Text>
         )}
         {!hasEnough && (
-          <Text color={colors.error}> — need {formatSatoshis(requiredAmount + fee - selectedAmount)} more</Text>
+          <Text color={colors.error}>
+            {' '}
+            — need {formatSatoshis(requiredAmount + fee - selectedAmount)}
+            {getFiatSuffix(requiredAmount + fee - selectedAmount)} more
+          </Text>
         )}
       </Box>
 
@@ -219,13 +237,22 @@ export function InputsSelectStep({
         const txShort = utxo.outpointTransactionHash.slice(0, 8);
 
         return (
-          <Text
+          <Box
             key={`${utxo.outpointTransactionHash}:${utxo.outpointIndex}`}
-            color={isFocused ? colors.focus : utxo.selected ? colors.success : colors.text}
+            flexDirection="column"
-            bold={isFocused}
           >
-            {isFocused ? '▸ ' : '  '}{checkMark} {formatSatoshis(utxo.valueSatoshis)} ({txShort}…:{utxo.outpointIndex})
+            <Text
-          </Text>
+              color={isFocused ? colors.focus : utxo.selected ? colors.success : colors.text}
+              bold={isFocused}
+            >
+              {isFocused ? '▸ ' : '  '}{checkMark} {formatSatoshis(utxo.valueSatoshis)} ({txShort}…:{utxo.outpointIndex})
+            </Text>
+            {formatSatoshisToFiat(utxo.valueSatoshis) && (
+              <Text color={colors.textMuted}>
+                {'   '}≈ {formatSatoshisToFiat(utxo.valueSatoshis)}
+              </Text>
+            )}
+          </Box>
         );
       })}
 

src/tui/screens/invitations/invitation-import/steps/PreviewInvitationStep.tsx

@@ -9,6 +9,7 @@
 import React from 'react';
 import { Box, Text } from 'ink';
 import { colors, formatSatoshis } from '../../../../theme.js';
+import { useSatoshisConversion } from '../../../../hooks/useSatoshisConversion.js';
 import { useLayeredInput } from '../../../../hooks/useInputLayer.js';
 import {
   getInvitationState,
@@ -41,6 +42,8 @@ export function PreviewInvitationStep({
   onCancel,
   isActive,
 }: PreviewStepProps): React.ReactElement {
+  const { formatSatoshisToFiat } = useSatoshisConversion();
+
   useLayeredInput('import-flow', (_input, key) => {
     if (key.return) onComplete();
     if (key.escape) onCancel();
@@ -168,11 +171,15 @@ export function PreviewInvitationStep({
           ) : (
             outputs.map((output, idx) => {
               const outputTemplate = template?.outputs?.[output.outputIdentifier ?? ''];
+              const fiatValue = output.valueSatoshis !== undefined
+                ? formatSatoshisToFiat(output.valueSatoshis)
+                : null;
               return (
                 <Box key={`output-${idx}`}>
                   <Text color={colors.text}>
                     {'  '}• {outputTemplate?.name ?? output.outputIdentifier ?? `Output ${idx}`}
                     {output.valueSatoshis !== undefined && ` (${formatSatoshis(output.valueSatoshis)})`}
+                    {fiatValue && ` (~${fiatValue})`}
                   </Text>
                 </Box>
               );

src/tui/screens/invitations/invitation-import/steps/ReviewStep.tsx

@@ -10,6 +10,7 @@
 import React, { useState, useCallback } from 'react';
 import { Box, Text } from 'ink';
 import { colors, formatSatoshis } from '../../../../theme.js';
+import { useSatoshisConversion } from '../../../../hooks/useSatoshisConversion.js';
 import { useLayeredInput } from '../../../../hooks/useInputLayer.js';
 import type { ReviewStepProps, SelectableUTXO } from '../types.js';
 
@@ -32,6 +33,7 @@ export function ReviewStep({
 }: ReviewStepProps): React.ReactElement {
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const { formatSatoshisToFiat } = useSatoshisConversion();
 
   const fee = DEFAULT_FEE;
   const action = template?.actions?.[invitation.data.actionIdentifier];
@@ -39,6 +41,11 @@ export function ReviewStep({
   // Compute totals from selected inputs
   const totalSelected = selectedInputs.reduce((sum, u) => sum + u.valueSatoshis, 0n);
 
+  const getFiatSuffix = (satoshis: bigint): string => {
+    const fiatValue = formatSatoshisToFiat(satoshis);
+    return fiatValue ? ` (~${fiatValue})` : '';
+  };
+
   /**
    * Execute the import: add inputs (with role) and optional change output.
    */
@@ -85,14 +92,34 @@ export function ReviewStep({
       <Box marginTop={1} flexDirection="column">
         <Text color={colors.primary} bold>Funding:</Text>
         <Text color={colors.text}>  • UTXOs: {selectedInputs.length}</Text>
-        <Text color={colors.text}>  • Total: {formatSatoshis(totalSelected)}</Text>
+        <Text color={colors.text}>  • Total: {formatSatoshis(totalSelected)}{getFiatSuffix(totalSelected)}</Text>
-        <Text color={colors.text}>  • Required: {formatSatoshis(requiredAmount)}</Text>
+        <Text color={colors.text}>  • Required: {formatSatoshis(requiredAmount)}{getFiatSuffix(requiredAmount)}</Text>
-        <Text color={colors.text}>  • Fee: {formatSatoshis(fee)}</Text>
+        <Text color={colors.text}>  • Fee: {formatSatoshis(fee)}{getFiatSuffix(fee)}</Text>
         {changeAmount >= DUST_THRESHOLD && (
-          <Text color={colors.text}>  • Change: {formatSatoshis(changeAmount)}</Text>
+          <Text color={colors.text}>  • Change: {formatSatoshis(changeAmount)}{getFiatSuffix(changeAmount)}</Text>
         )}
       </Box>
 
+      {selectedInputs.length > 0 && (
+        <Box marginTop={1} flexDirection="column">
+          <Text color={colors.primary} bold>Selected UTXOs:</Text>
+          {selectedInputs.slice(0, 3).map((utxo) => (
+            <Text
+              key={`${utxo.outpointTransactionHash}:${utxo.outpointIndex}`}
+              color={colors.textMuted}
+            >
+              {'  '}• {formatSatoshis(utxo.valueSatoshis)}
+              {getFiatSuffix(utxo.valueSatoshis)}
+            </Text>
+          ))}
+          {selectedInputs.length > 3 && (
+            <Text color={colors.textMuted}>
+              {'  '}...and {selectedInputs.length - 3} more
+            </Text>
+          )}
+        </Box>
+      )}
+
       {/* Error display */}
       {error && (
         <Box marginTop={1}>

src/tui/screens/invitations/invitation-import/steps/VariablesStep.tsx

@@ -0,0 +1,113 @@
+/**
+ * VariablesStep — collects all required variable values for invitation import.
+ *
+ * This runs after role selection and before input selection so cashasm
+ * expressions can resolve required variables during `getSatsOut()`.
+ */
+
+import React, { useMemo, useState, useCallback } from "react";
+import { Box, Text } from "ink";
+import { colors } from "../../../../theme.js";
+import { useLayeredInput } from "../../../../hooks/useInputLayer.js";
+import { VariableInputField } from "../../../../components/VariableInputField.js";
+import type { VariablesStepProps } from "../types.js";
+
+/**
+ * Build a user-facing validation error for empty required fields.
+ */
+function validateVariables(
+  variables: VariablesStepProps["variables"],
+): string | null {
+  const empty = variables.filter((v) => v.value.trim() === "");
+  if (empty.length === 0) return null;
+  return `Please enter values for: ${empty.map((v) => v.name).join(", ")}`;
+}
+
+export function VariablesStep({
+  variables,
+  onUpdateVariable,
+  onComplete,
+  onCancel,
+  isActive,
+}: VariablesStepProps): React.ReactElement {
+  const [focusedInput, setFocusedInput] = useState(0);
+  const [validationError, setValidationError] = useState<string | null>(null);
+
+  const helpText = useMemo(() => {
+    if (variables.length === 0) {
+      return "No variables required for this role.";
+    }
+    return "Enter a value for each variable, then press Enter on the last field to continue.";
+  }, [variables.length]);
+
+  /**
+   * Move focus to next input, or finish the step if this is the last one.
+   */
+  const handleInputSubmit = useCallback(() => {
+    if (variables.length === 0) {
+      onComplete();
+      return;
+    }
+
+    if (focusedInput < variables.length - 1) {
+      setFocusedInput((prev) => prev + 1);
+      return;
+    }
+
+    const validation = validateVariables(variables);
+    setValidationError(validation);
+    if (!validation) {
+      onComplete();
+    }
+  }, [variables, focusedInput, onComplete]);
+
+  // Keyboard navigation for non-text actions.
+  useLayeredInput(
+    "import-flow",
+    (input, key) => {
+      if (key.upArrow || input === "k") {
+        setFocusedInput((prev) => Math.max(0, prev - 1));
+      } else if (key.downArrow || input === "j") {
+        setFocusedInput((prev) => Math.min(variables.length - 1, prev + 1));
+      } else if (key.escape) {
+        onCancel();
+      }
+    },
+    { isActive },
+  );
+
+  return (
+    <Box flexDirection="column">
+      <Text color={colors.primary} bold>
+        Required Variables
+      </Text>
+
+      <Box marginTop={1} flexDirection="column">
+        {variables.map((variable, index) => (
+          <VariableInputField
+            key={variable.id}
+            variable={variable}
+            index={index}
+            isFocused={focusedInput === index}
+            onChange={onUpdateVariable}
+            onSubmit={handleInputSubmit}
+            borderColor={colors.border as string}
+            focusColor={colors.primary as string}
+          />
+        ))}
+      </Box>
+
+      {validationError && (
+        <Box marginTop={1}>
+          <Text color={colors.error}>{validationError}</Text>
+        </Box>
+      )}
+
+      <Box marginTop={1}>
+        <Text color={colors.textMuted}>
+          {helpText} ↑↓: Change field • Esc: Cancel
+        </Text>
+      </Box>
+    </Box>
+  );
+}

src/tui/screens/invitations/invitation-import/types.ts

@@ -16,6 +16,7 @@ export type ImportStepType =
   | "fetch"
   | "preview"
   | "role-select"
+  | "variables"
   | "inputs-select"
   | "review";
 
@@ -30,6 +31,7 @@ export const IMPORT_STEPS: ImportStep[] = [
   { name: "Fetch", type: "fetch" },
   { name: "Preview", type: "preview" },
   { name: "Select Role", type: "role-select" },
+  { name: "Variables", type: "variables" },
   { name: "Select Inputs", type: "inputs-select" },
   { name: "Review", type: "review" },
 ];
@@ -81,6 +83,24 @@ export interface RoleSelectStepProps {
   isActive: boolean;
 }
 
+/** A single variable input required by the selected action role. */
+export interface ImportVariableInput {
+  id: string;
+  name: string;
+  type: string;
+  hint?: string;
+  value: string;
+}
+
+/** Props for VariablesStep — collects required role/action variable values. */
+export interface VariablesStepProps {
+  variables: ImportVariableInput[];
+  onUpdateVariable: (index: number, value: string) => void;
+  onComplete: () => void;
+  onCancel: () => void;
+  isActive: boolean;
+}
+
 /** Props for InputsSelectStep — lets user pick UTXOs to fund the invitation. */
 export interface InputsSelectStepProps {
   invitation: Invitation;
@@ -116,8 +136,12 @@ export interface ImportFlowProps {
   mode: ImportFlowMode;
   /** The application service — injected, not pulled from context. */
   appService: AppService;
-  /** Called when the flow completes or is cancelled. */
+  /**
-  onClose: () => void;
+   * Called when the flow completes or is cancelled.
+   * When import succeeds, the invitation identifier is provided so callers can
+   * select/focus the imported invitation in their UI.
+   */
+  onClose: (importedInvitationId?: string) => void;
   /** Display an error message to the user. */
   showError: (message: string) => void;
   /** Display an info message to the user. */

src/tui/utils/clipboard.ts

@@ -8,6 +8,36 @@ import { promisify } from "util";
 
 const execAsync = promisify(exec);
 
+// Define a list of clipboard methods with their platform and command.
+// The platform is a function that returns true if the method is available on the current platform.
+// The command is a function that returns a promise that resolves to the result of the command.
+const clipboardMethods = {
+  pbCopy: {
+    platform: (platform: string) => platform === 'darwin',
+    command: async (text: string) => execAsync(`printf '%s' '${text}' | pbcopy`),
+  },
+  xclip: {
+    platform: (platform: string) => platform === 'linux',
+    command: async (text: string) => execAsync(`printf '%s' '${text}' | xclip -selection clipboard`),
+  },
+  xsel: {
+    platform: (platform: string) => platform === 'linux',
+    command: async (text: string) => execAsync(`printf '%s' '${text}' | xsel --clipboard --input`),
+  },
+  ssh: {
+    platform: (platform: string) => platform === 'linux',
+    command: async (text: string) => process.stdout.write(`\x1b]52;c;${Buffer.from(text, 'utf-8').toString('base64')}\x07`),
+  },
+  clip: {
+    platform: (platform: string) => platform === 'windows',
+    command: async (text: string) => execAsync(`echo|set /p="${text}" | clip`),
+  },
+  clipboardy: {
+    platform: (platform: string) => platform === 'windows',
+    command: async (text: string) => clipboardy.writeSync(text),
+  },
+}
+
 /**
  * Attempts to copy text to clipboard using multiple methods.
  * Tries native commands first (most reliable), then clipboardy as fallback.
@@ -21,46 +51,25 @@ export async function copyToClipboard(text: string): Promise<void> {
   // Escape the text for shell commands
   const escapedText = text.replace(/'/g, "'\\''");
 
-  // Try native commands first - they're more reliable
+  const availableMethods = Object.values(clipboardMethods).filter(method => method.platform(platform));
-  try {
-    if (platform === "darwin") {
-      // macOS - use pbcopy directly
-      await execAsync(`printf '%s' '${escapedText}' | pbcopy`);
-      return;
-    } else if (platform === "linux") {
-      // Linux - try xclip, then xsel
-      try {
-        await execAsync(
-          `printf '%s' '${escapedText}' | xclip -selection clipboard`,
-        );
-        return;
-      } catch {
-        try {
-          await execAsync(
-            `printf '%s' '${escapedText}' | xsel --clipboard --input`,
-          );
-          return;
-        } catch {
-          // Fall through to clipboardy
-        }
-      }
-    } else if (platform === "win32") {
-      // Windows - use clip.exe
-      await execAsync(`echo|set /p="${text}" | clip`);
-      return;
-    }
-  } catch {
-    // Native command failed, try clipboardy
-  }
 
-  // Fallback to clipboardy
+  const errors: Error[] = [];
-  try {
+
-    clipboardy.writeSync(text);
+  for (const method of availableMethods) {
-    return;
+    try {
-  } catch {
+      if (method.platform(platform)) {
-    // clipboardy also failed
+        await method.command(escapedText);
+      } else {
+        continue;
+      }
+      return;
+    } catch(error) {
+      if (error instanceof Error) {
+        errors.push(error);
+      }
+    }
   }
 
   // All methods failed
-  throw new Error(`Clipboard not available. Install xclip or xsel on Linux.`);
+  throw new Error(`Clipboard not available. ${errors.map(error => error.message).join('\n')}`);
 }

src/utils/bch-mnemonic-url.ts

@@ -90,7 +90,7 @@ export class BCHMnemonicURL {
   static fromSeed(seed: string): BCHMnemonicURL {
     // Encode the seed to a Uint8Array
     const entropy = decodeBip39Mnemonic(seed);
- 
+
     // If the decode failed, throw an error
     if (typeof entropy === "string") {
       throw new Error(`Invalid seed: ${entropy}`);

src/utils/history-utils.ts

@@ -1,7 +1,8 @@
 import type {
   HistoryItem,
-  HistoryInvitationItem,
+  WalletHistoryInput,
-  HistoryUtxoItem,
+  WalletHistoryItem,
+  WalletHistoryOutput,
 } from "../services/history.js";
 
 export type HistoryColorName =
@@ -13,10 +14,9 @@ export type HistoryColorName =
   | "text";
 
 export type HistoryRowType =
-  | "invitation"
+  | "history_item"
-  | "invitation_input"
+  | "history_input"
-  | "invitation_output"
+  | "history_output";
-  | "utxo";
 
 export interface HistoryDisplayRow {
   id: string;
@@ -25,8 +25,11 @@ export interface HistoryDisplayRow {
   description?: string;
   timestamp?: number;
   isNested: boolean;
-  utxo?: HistoryUtxoItem;
+  valueSatoshis?: bigint;
-  invitation?: HistoryInvitationItem;
+  reserved?: boolean;
+  input?: WalletHistoryInput;
+  output?: WalletHistoryOutput;
+  item?: WalletHistoryItem;
 }
 
 export function formatHistoryDate(timestamp?: number): string | undefined {
@@ -40,61 +43,68 @@ export function buildHistoryDisplayRows(
   const rows: HistoryDisplayRow[] = [];
 
   for (const item of items) {
-    if (item.kind === "invitation") {
+    const roles = item.roles.length > 0 ? item.roles.join(", ") : "unknown";
-      rows.push({
+    if (item.source === "utxo") {
-        id: item.id,
-        type: "invitation",
-        label: item.description,
-        timestamp: item.createdAtTimestamp,
-        isNested: false,
-        invitation: item,
-      });
-
-      for (const input of item.inputs) {
-        const satsPrefix =
-          input.valueSatoshis !== undefined
-            ? `${input.valueSatoshis.toLocaleString()} sats `
-            : "";
-        rows.push({
-          id: `${item.id}-input-${input.id}`,
-          type: "invitation_input",
-          label: `${satsPrefix}${input.outpoint.txid}:${input.outpoint.index}`,
-          description: input.description,
-          isNested: true,
-          utxo: input,
-          invitation: item,
-        });
-      }
-
       for (const output of item.outputs) {
         rows.push({
           id: `${item.id}-output-${output.id}`,
-          type: "invitation_output",
+          type: "history_output",
-          label:
+          label: output.outpoint
-            output.valueSatoshis !== undefined
+            ? `${output.outpoint.txid}:${output.outpoint.index}`
-              ? `${output.valueSatoshis.toLocaleString()} sats`
+            : output.outputIdentifier ?? "Output",
-              : "Output",
+          description: `${item.template} | ${roles} | ${output.description}`,
-          description: output.description,
+          timestamp: item.createdAtTimestamp,
-          isNested: true,
+          isNested: false,
-          utxo: output,
+          valueSatoshis: output.valueSatoshis,
-          invitation: item,
+          reserved: output.reserved,
+          output,
+          item,
         });
       }
-
       continue;
     }
 
     rows.push({
       id: item.id,
-      type: "utxo",
+      type: "history_item",
-      label:
+      label: `${item.template} | ${roles} | ${item.description}`,
-        item.valueSatoshis !== undefined
+      description: item.action,
-          ? `${item.valueSatoshis.toLocaleString()} sats`
+      timestamp: item.createdAtTimestamp,
-          : "UTXO",
-      description: item.description,
       isNested: false,
-      utxo: item,
+      valueSatoshis: item.valueSatoshis,
+      item,
     });
+
+    if (item.source !== "invitation") continue;
+
+    for (const input of item.inputs) {
+      rows.push({
+        id: `${item.id}-input-${input.id}`,
+        type: "history_input",
+        label: `${input.outpoint.txid}:${input.outpoint.index}`,
+        description: input.description,
+        isNested: true,
+        valueSatoshis: input.valueSatoshis,
+        input,
+        item,
+      });
+    }
+
+    for (const output of item.outputs) {
+      rows.push({
+        id: `${item.id}-output-${output.id}`,
+        type: "history_output",
+        label: output.outpoint
+          ? `${output.outpoint.txid}:${output.outpoint.index}`
+          : output.outputIdentifier ?? "Output",
+        description: output.description,
+        isNested: true,
+        valueSatoshis: output.valueSatoshis,
+        reserved: output.reserved,
+        output,
+        item,
+      });
+    }
   }
 
   return rows;
@@ -106,14 +116,14 @@ export function getHistoryItemColorName(
 ): HistoryColorName {
   if (isSelected) return "info";
   switch (row.type) {
-    case "invitation":
+    case "history_input":
-      return "text";
-    case "invitation_input":
       return "error";
-    case "invitation_output":
+    case "history_output":
-      return "success";
+      return row.reserved ? "warning" : "success";
-    case "utxo":
+    case "history_item":
-      return row.utxo?.reserved ? "warning" : "success";
+      if ((row.valueSatoshis ?? 0n) < 0n) return "error";
+      if ((row.valueSatoshis ?? 0n) > 0n) return "success";
+      return "text";
     default:
       return "text";
   }

src/utils/invitation-flow.ts

@@ -10,6 +10,7 @@ export interface SelectableUtxoLike {
   selected: boolean;
 }
 
+// TODO: Move to engine
 export const hasMissingRequirements = (missingRequirements: {
   variables?: string[];
   inputs?: string[];
@@ -32,6 +33,7 @@ export const isInvitationRequirementsComplete = async (
   return !hasMissingRequirements(missingRequirements);
 };
 
+// TODO: Move to engine in templates.ts
 export const resolveActionRoles = (
   template: XOTemplate | undefined,
   actionIdentifier: string | undefined,
@@ -45,11 +47,13 @@ export const resolveActionRoles = (
   const starts = template.start ?? [];
   const roleIds = starts
     .filter((entry) => entry.action === actionIdentifier)
-    .map((entry) => entry.role);
+    .map((entry) => entry.role)
+    .filter((roleId) => roleId !== undefined);
 
   return [...new Set(roleIds)];
 };
 
+// TODO: Move to engine
 export const roleRequiresInputs = (
   template: XOTemplate | undefined,
   actionIdentifier: string | undefined,
@@ -60,17 +64,11 @@ export const roleRequiresInputs = (
   if (!action) return false;
 
   const actionRole = action.roles?.[roleIdentifier];
-  const roleSlotsMin = actionRole?.requirements?.slots?.min ?? 0;
+  const actionRequirements = action.requirements;
+  const actionRoleRequirements = actionRole && actionRequirements && actionRequirements.participants?.find((participant) => participant.role === roleIdentifier);
+  const roleSlotsMin = actionRoleRequirements && actionRoleRequirements.slots && actionRoleRequirements.slots.min > 0 ? actionRoleRequirements.slots.min : 0;
   if (roleSlotsMin > 0) return true;
 
-  // Some templates specify slot/input requirements at action.requirements.roles
-  // instead of role.requirements. Respect those as well.
-  const roleRequirement = action.requirements?.roles?.find(
-    (requirement) => requirement.role === roleIdentifier,
-  );
-  const actionLevelSlotsMin = roleRequirement?.slots?.min ?? 0;
-  if (actionLevelSlotsMin > 0) return true;
-
   const transactionIdentifier = action.transaction;
   const transaction = transactionIdentifier
     ? template.transactions?.[transactionIdentifier]
@@ -80,6 +78,7 @@ export const roleRequiresInputs = (
   return (roleInputs?.length ?? 0) > 0;
 };
 
+
 export const getTransactionOutputIdentifier = (
   output: XOTemplateTransactionOutput,
 ): string | undefined => {
@@ -126,19 +125,19 @@ export const tryCashAddressToLockingBytecodeHex = (
   return binToHex(result.bytecode);
 };
 
+// Replace with libauth compiler in the engine
 export const resolveProvidedLockingBytecodeHex = (
   template: XOTemplate,
   outputIdentifier: string,
   variableValues: Record<string, string>,
 ): string | undefined => {
   const outputDefinition = template.outputs?.[outputIdentifier];
-  if (!outputDefinition || typeof outputDefinition.lockscript !== "string")
+  if (!outputDefinition || typeof outputDefinition.lockingScript !== "string") {
     return undefined;
+  }
 
-  const lockingScriptDefinition = (
+  const lockingScriptDefinition = template.lockingScripts?.[outputDefinition.lockingScript];
-    template.lockingScripts as Record<string, unknown> | undefined
+  const scriptIdentifier = lockingScriptDefinition?.lockingBytecode;
-  )?.[outputDefinition.lockscript] as { lockingScript?: string } | undefined;
-  const scriptIdentifier = lockingScriptDefinition?.lockingScript;
   if (!scriptIdentifier) return undefined;
 
   const scriptExpression = (

src/utils/invitation-utils.ts

@@ -7,7 +7,7 @@
  */
 
 import type { Invitation } from "../services/invitation.js";
-import type { XOTemplate } from "@xo-cash/types";
+import type { XOInvitationCommit, XOTemplate } from "@xo-cash/types";
 
 /**
  * Color names for invitation states.
@@ -249,9 +249,9 @@ export function formatInvitationId(id: string, maxLength: number = 16): string {
  * @param invitation - The invitation to check
  * @returns Array of unique entity identifiers
  */
-export function getInvitationParticipants(invitation: Invitation): string[] {
+export function getInvitationParticipants(commits: Array<XOInvitationCommit>): string[] {
   const participants = new Set<string>();
-  for (const commit of invitation.data.commits || []) {
+  for (const commit of commits) {
     if (commit.entityIdentifier) {
       participants.add(commit.entityIdentifier);
     }
@@ -267,9 +267,14 @@ export function getInvitationParticipants(invitation: Invitation): string[] {
  * @returns True if the user has made at least one commit
  */
 export function isUserParticipant(
-  invitation: Invitation,
+  invitation: Invitation | Array<XOInvitationCommit>,
   userEntityId: string | null,
 ): boolean {
   if (!userEntityId) return false;
-  return getInvitationParticipants(invitation).includes(userEntityId);
+
+  if (Array.isArray(invitation)) {
+    return invitation.some(commit => commit.entityIdentifier === userEntityId);
+  }
+
+  return getInvitationParticipants(invitation.data.commits).includes(userEntityId);
 }

src/utils/logger.ts

@@ -1,50 +0,0 @@
-export class Logger {
-  constructor(
-    private readonly endpoint: string,
-    private readonly token: string,
-    private readonly path: string,
-  ) {}
-
-  send(
-    level: "log" | "error" | "warn" | "info",
-    message: string,
-    ...metadata: unknown[]
-  ) {
-    const data = {
-      level,
-      message: `${this.path}: ${message}`,
-      metadata,
-    };
-
-    fetch(`${this.endpoint}`, {
-      method: "POST",
-      body: JSON.stringify(data),
-      headers: {
-        "Content-Type": "application/json",
-        "x-api-key": this.token,
-      },
-    }).catch((error) => {
-      console.error("Failed to send log to logger:", error);
-    });
-  }
-
-  log(message: string, ...metadata: unknown[]) {
-    this.send("log", message, ...metadata);
-  }
-
-  error(message: string, ...metadata: unknown[]) {
-    this.send("error", message, ...metadata);
-  }
-
-  warn(message: string, ...metadata: unknown[]) {
-    this.send("warn", message, ...metadata);
-  }
-
-  info(message: string, ...metadata: unknown[]) {
-    this.send("info", message, ...metadata);
-  }
-
-  child(path: string): Logger {
-    return new Logger(this.endpoint, this.token, `${this.path}.${path}`);
-  }
-}

src/utils/paths.ts

@@ -0,0 +1,77 @@
+/**
+ * Global XO CLI config layout (XDG-style: ~/.config/xo-cli/).
+ * User-provided paths (templates, invitation JSON) stay relative to cwd.
+ */
+
+import { existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, isAbsolute, join, resolve } from "node:path";
+
+/**
+ * Base config directory. Created on first access.
+ */
+export function getConfigDir(): string {
+  const dir = join(homedir(), ".config", "xo-cli");
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * Directory for mnemonic wallet files (mnemonic-*).
+ */
+export function getMnemonicsDir(): string {
+  const dir = join(getConfigDir(), "mnemonics");
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * Directory for engine DB and invitation storage SQLite files.
+ */
+export function getDataDir(): string {
+  const dir = join(getConfigDir(), "data");
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * File storing CLI settings (JSON), including the last-used mnemonic reference.
+ */
+export function getSettingsPath(): string {
+  return join(getConfigDir(), ".wallet");
+}
+
+/**
+ * @deprecated Prefer {@link getSettingsPath}.
+ */
+export function getWalletConfigPath(): string {
+  return getSettingsPath();
+}
+
+/**
+ * Resolves a mnemonic reference to an absolute path.
+ * Order: absolute path if it exists → path relative to cwd → ~/.config/xo-cli/mnemonics/<basename>.
+ *
+ * @param mnemonicRef - Path or basename (e.g. `mnemonic-nuclear`)
+ * @returns Absolute path to the mnemonic file
+ * @throws If no matching file exists
+ */
+export function resolveMnemonicFilePath(mnemonicRef: string): string {
+  if (isAbsolute(mnemonicRef) && existsSync(mnemonicRef)) {
+    return mnemonicRef;
+  }
+
+  const relativeToCwd = resolve(process.cwd(), mnemonicRef);
+  if (existsSync(relativeToCwd)) {
+    return relativeToCwd;
+  }
+
+  const inMnemonics = join(getMnemonicsDir(), basename(mnemonicRef));
+  if (existsSync(inMnemonics)) {
+    return inMnemonics;
+  }
+
+  throw new Error(
+    `Mnemonic file not found: ${mnemonicRef}. Run "xo-cli mnemonic list" to see available files.`,
+  );
+}

src/utils/rates/base-rates.ts

@@ -0,0 +1,71 @@
+import { EventEmitter } from '../event-emitter.js';
+
+/**
+ * Events emitted by our Rates Adapters
+ */
+export type RatesEventMap = {
+  rateUpdated: {
+    numeratorUnitCode: string;
+    denominatorUnitCode: string;
+    price: number;
+  };
+};
+
+export abstract class BaseRates<
+  T extends RatesEventMap = RatesEventMap,
+> extends EventEmitter<T> {
+  /** Starts the given rates adapter so that it will emit events on price updates. */
+  public abstract start(): Promise<void>;
+
+  /** Stops the given rates adapter so that it will stop checking for price updates. */
+  public abstract stop(): Promise<void>;
+
+  /**
+   * List all available market products (pairs).
+   * @returns A set of strings in the format "NUMERATOR/DENOMINATOR"
+   */
+  public abstract listPairs(): Promise<Set<string>>;
+
+  // TODO: Consider whether we actually want the below.
+  //       Ideally, we will want to replace this with something like the Units class:
+  //       See: https://gitlab.com/GeneralProtocols/xo/stack/-/issues/44
+  /**
+   * Format the amount in the target currency to the correct number of decimal places.
+   *
+   * @param {number} amount - The amount to format.
+   * @param {string} targetCurrency - The target currency.
+   *
+   * @returns The formatted amount.
+   */
+  public formatCurrency(amount: number, targetCurrency: string): string {
+    const normalizedCurrency = targetCurrency.toUpperCase();
+    const minimumFractionDigitsMap: { [currency: string]: number } = {
+      AUD: 2,
+      BCH: 8,
+      USD: 2,
+    };
+    const minimumFractionDigits = minimumFractionDigitsMap[normalizedCurrency] ?? 2;
+    const maximumFractionDigits = Math.max(minimumFractionDigits, 8);
+
+    try {
+      const formatter = new Intl.NumberFormat('en-US', {
+        style: 'currency',
+        currency: normalizedCurrency,
+        currencyDisplay: 'narrowSymbol',
+        minimumFractionDigits,
+        maximumFractionDigits,
+      });
+
+      return formatter.format(amount);
+    } catch {
+      // Some numerator symbols from oracle pairs (e.g. DOGE/BCH) are not ISO-4217
+      // fiat currency codes, so Intl currency formatting will throw a RangeError.
+      // In that case we still return a human-readable formatted value.
+      const numericFormatter = new Intl.NumberFormat('en-US', {
+        minimumFractionDigits,
+        maximumFractionDigits,
+      });
+      return `${numericFormatter.format(amount)} ${normalizedCurrency}`;
+    }
+  }
+}

src/utils/rates/rates-oracles.ts

@@ -0,0 +1,230 @@
+import {
+  OracleClient,
+  OracleMetadataMessage,
+  OraclePriceMessage,
+  type OracleMetadataMap,
+} from '@generalprotocols/oracle-client';
+
+import { type RatesEventMap, BaseRates } from './base-rates.js';
+import { type OffCallback } from '../event-emitter.js';
+import { SettingsService } from '../../services/settings.js';
+
+// Add the Oracle Price Message to our Events for this Adapter.
+export type RatesOracleEventMap = RatesEventMap & {
+  rateUpdated: {
+    oraclePriceMessage: OraclePriceMessage;
+  };
+};
+
+// TODO: Add RatesHistorical trait since Oracles can provide historical rates.
+export class RatesOracle extends BaseRates<RatesOracleEventMap> {
+  /**
+   * Create a new rates oracle.
+   *
+   * @param client The underlying oracle client. If not provided, a new client will be created.
+   * @returns The rates oracle.
+   */
+  static async from(
+    client?: OracleClient,
+    settings: SettingsService = new SettingsService(),
+  ) {
+    const ratesOracle = new RatesOracle(
+      client ?? (await OracleClient.from()),
+      settings,
+    );
+
+    return ratesOracle;
+  }
+
+  private client: OracleClient;
+  private settings: SettingsService;
+  private oracles: OracleMetadataMap;
+
+  private started: boolean = false;
+  private targetNumeratorUnitCode: string;
+  private targetDenominatorUnitCode: string = 'BCH';
+  private unsubscribeFromSettings: OffCallback | null = null;
+
+  private constructor(client: OracleClient, settings: SettingsService) {
+    super();
+
+    this.client = client;
+    this.settings = settings;
+    this.oracles = {};
+    this.targetNumeratorUnitCode = settings.getCurrency().toUpperCase();
+  }
+
+  /**
+   * Start the rates oracle and the underlying client.
+   */
+  async start() {
+    if (this.started) {
+      return;
+    }
+    this.started = true;
+    this.unsubscribeFromSettings = this.settings.on(
+      'settings-updated',
+      this.handleSettingsUpdated.bind(this),
+    );
+
+    // Create event listeners for the client.
+    this.client.setOnMetadataMessage(this.handleMetadataMessage.bind(this));
+    this.client.setOnPriceMessage(this.handlePriceMessage.bind(this));
+
+    // Get the metadata for the client.
+    this.oracles = await this.client.getMetadataMap();
+
+    // Start the client.
+    await this.client.start();
+
+    // Refresh the prices.
+    await this.refreshPrices();
+  }
+
+  /**
+   * Stop the rates oracle and the underlying client.
+   */
+  async stop() {
+    if (!this.started) {
+      return;
+    }
+    this.started = false;
+    this.unsubscribeFromSettings?.();
+    this.unsubscribeFromSettings = null;
+
+    // Remove event listeners by setting them to empty functions.
+    this.client.setOnMetadataMessage(() => {});
+    this.client.setOnPriceMessage(() => {});
+
+    await this.client.stop();
+  }
+
+  /**
+   * List the pairs that we are tracking.
+   *
+   * @returns A set of pairs.
+   */
+  async listPairs() {
+    // If metadata has not arrived yet but the client is running, query once so
+    // callers (like the currency picker) can still discover available pairs.
+    if (Object.keys(this.oracles).length === 0 && this.started) {
+      this.oracles = await this.client.getMetadataMap();
+    }
+
+    return new Set(
+      Object.values(this.oracles).map((oracle) => {
+        return `${oracle.SOURCE_NUMERATOR_UNIT_CODE}/${oracle.SOURCE_DENOMINATOR_UNIT_CODE}`;
+      }),
+    );
+  }
+
+  /**
+   * Get the latest prices for all the pairs and emit a rate updated event for each.
+   */
+  public async refreshPrices() {
+    const oracles = await this.client.getOracles();
+
+    // For each oracle, get the lastest dataSequence (price) message and emit a rate updated event.
+    await Promise.allSettled(
+      oracles.map(async (oracle) => {
+        try {
+          const messages = await this.client.getOracleMessages({
+            publicKey: oracle.publicKey,
+            minDataSequence: 1,
+            count: 1,
+          });
+
+          // We are only expecting a single message back. Just in case, we take the latest one.
+          const message = messages.reduce((latest, msg) => {
+            if (
+              msg instanceof OraclePriceMessage &&
+              msg.messageSequence > (latest?.messageSequence ?? 0)
+            ) {
+              return msg;
+            }
+            return latest;
+          }, messages[0]);
+
+          // If the message is a price message, handle it.
+          if (message instanceof OraclePriceMessage) {
+            this.handlePriceMessage(message);
+          }
+        } catch (error) {
+          console.error('Error refreshing prices for oracle:', oracle.publicKey, error);
+        }
+      }),
+    );
+  }
+
+  /**
+   * Update the metadata map that we use to track the pairs.
+   *
+   * @param message The metadata message.
+   */
+  private handleMetadataMessage(message: OracleMetadataMessage) {
+    this.oracles = OracleClient.updateMetadataMap(this.oracles, message);
+  }
+
+  /**
+   * Emit a rate updated event for the given pair.
+   *
+   * @param message The price message.
+   */
+  private handlePriceMessage(message: OraclePriceMessage) {
+    const oracle = this.oracles[message.toHexObject().publicKey];
+
+    // If the oracle doesn't have the required metadata, we can't use it.
+    if (
+      !oracle ||
+      !oracle.SOURCE_NUMERATOR_UNIT_CODE ||
+      !oracle.SOURCE_DENOMINATOR_UNIT_CODE ||
+      !oracle.ATTESTATION_SCALING
+    ) {
+      return;
+    }
+
+    const sourceNumeratorUnitCode = oracle.SOURCE_NUMERATOR_UNIT_CODE.toUpperCase();
+    const sourceDenominatorUnitCode = oracle.SOURCE_DENOMINATOR_UNIT_CODE.toUpperCase();
+
+    // Only emit the pair currently selected in settings.
+    if (
+      sourceNumeratorUnitCode !== this.targetNumeratorUnitCode ||
+      sourceDenominatorUnitCode !== this.targetDenominatorUnitCode
+    ) {
+      return;
+    }
+
+    // Scale the price
+    const priceValue = message.priceValue / oracle.ATTESTATION_SCALING;
+
+    this.emit('rateUpdated', {
+      numeratorUnitCode: sourceNumeratorUnitCode,
+      denominatorUnitCode: sourceDenominatorUnitCode,
+      price: priceValue,
+      oraclePriceMessage: message,
+    });
+  }
+
+  /**
+   * Tracks updates to settings and switches the actively emitted fiat pair.
+   */
+  private handleSettingsUpdated(
+    event: {
+      key: 'currency' | 'default-mnemonic';
+      value: string | undefined;
+    },
+  ) {
+    if (event.key !== 'currency' || !event.value) {
+      return;
+    }
+
+    this.targetNumeratorUnitCode = event.value.toUpperCase();
+
+    // Refresh so listeners get the latest value for the new currency quickly.
+    if (this.started) {
+      this.refreshPrices().catch((error) => {
+        console.error('Error refreshing prices after currency update:', error);
+      });
+    }
+  }
+}

src/utils/template-utils.ts

@@ -188,11 +188,13 @@ export function getRolesForAction(
   );
 
   return startEntries.map((entry) => {
-    const roleDef = template.roles?.[entry.role];
+    const roleDef = template.roles?.[entry.role || ''];
     const roleObj = typeof roleDef === "object" ? roleDef : null;
+
+    // TODO: This is ugly. Lot of conditionals. Need to take a much closer look at this.
     return {
-      roleId: entry.role,
+      roleId: entry.role || '',
-      name: roleObj?.name || entry.role,
+      name: roleObj?.name || entry.role || '',
       description: roleObj?.description,
     };
   });

tests/cli/arguments.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from "vitest"
+import { describe, it, expect } from "vitest";
 
 import { convertArgsToObject } from "../../src/cli/arguments";
 
@@ -11,45 +11,59 @@ const testCases = [
     },
   },
   {
-    input: ['-var-requested-satohis', '1000', '-role', 'receiver'],
+    input: ["-var-requested-satohis", "1000", "-role", "receiver"],
     expected: {
       args: [],
-      options: { "varRequestedSatohis": "1000", role: "receiver" },
+      options: { varRequestedSatohis: "1000", role: "receiver" },
     },
   },
   {
-    input: ['-o', 'output.json', '-var-requested-satohis', '1000', '-role', 'receiver'],
+    input: [
+      "-o",
+      "output.json",
+      "-var-requested-satohis",
+      "1000",
+      "-role",
+      "receiver",
+    ],
     expected: {
       args: [],
-      options: { output: "output.json", "varRequestedSatohis": "1000", role: "receiver" },
+      options: {
+        output: "output.json",
+        varRequestedSatohis: "1000",
+        role: "receiver",
+      },
     },
   },
   {
-    input: ['mnemonic', 'create', 'page', 'pencil', '-v', '-o', 'mnemonic.txt'],
+    input: ["mnemonic", "create", "page", "pencil", "-v", "-o", "mnemonic.txt"],
     expected: {
-      args: ['mnemonic', 'create', 'page', 'pencil'],
+      args: ["mnemonic", "create", "page", "pencil"],
       options: { verbose: "true", output: "mnemonic.txt" },
     },
   },
   {
-    input: ['-v', 'invitation', 'list', '-m', 'mnemonicFile'],
+    input: ["-v", "invitation", "list", "-m", "mnemonicFile"],
     expected: {
-      args: ['invitation', 'list'],
+      args: ["invitation", "list"],
       options: { verbose: "true", mnemonicFile: "mnemonicFile" },
     },
   },
   {
-    input: ['--help', 'template', 'import', 'template.json'],
+    input: ["--help", "template", "import", "template.json"],
     expected: {
-      args: ['template', 'import', 'template.json'],
+      args: ["template", "import", "template.json"],
       options: { help: "true" },
     },
   },
 ];
 
 describe("convertArgsToObject", () => {
-  it.each(testCases)("should split positional args from options", ({ input, expected }) => {
+  it.each(testCases)(
-    const result = convertArgsToObject(input);
+    "should split positional args from options",
-    expect(result).toEqual(expected);
+    ({ input, expected }) => {
-  });
+      const result = convertArgsToObject(input);
-});
+      expect(result).toEqual(expected);
+    },
+  );
+});

tests/cli/commands/handler-contracts.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from "vitest";
+
+import { handleMnemonicCommand } from "../../../src/cli/commands/mnemonic";
+import { handleTemplateCommand } from "../../../src/cli/commands/template";
+import { handleReceiveCommand } from "../../../src/cli/commands/receive";
+import { handleResourceCommand } from "../../../src/cli/commands/resource";
+import { CommandError } from "../../../src/cli/commands/types";
+import {
+  createBaseCommandDeps,
+  createCommandDeps,
+  createMockIO,
+} from "../mocks/command";
+
+const fakeApp = {
+  engine: {},
+  invitations: [],
+  unreserveAllResources: async () => 0,
+} as any;
+
+describe("command handler contracts", () => {
+  test("mnemonic throws and prints help for missing subcommand", async () => {
+    const { io, capture } = createMockIO();
+
+    await expect(
+      handleMnemonicCommand(createBaseCommandDeps(io), [], {}),
+    ).rejects.toThrow(CommandError);
+
+    try {
+      await handleMnemonicCommand(createBaseCommandDeps(io), [], {});
+    } catch (error) {
+      expect(error).toBeInstanceOf(CommandError);
+      expect((error as CommandError).event).toBe("mnemonic.subcommand.missing");
+    }
+
+    expect(capture.out.join("\n")).toContain("Usage:");
+  });
+
+  test("template throws for missing subcommand", async () => {
+    const { io, capture } = createMockIO();
+
+    await expect(
+      handleTemplateCommand(createCommandDeps(fakeApp, io), [], {}),
+    ).rejects.toThrow(CommandError);
+
+    try {
+      await handleTemplateCommand(createCommandDeps(fakeApp, io), [], {});
+    } catch (error) {
+      expect(error).toBeInstanceOf(CommandError);
+      expect((error as CommandError).event).toBe("template.subcommand.missing");
+    }
+
+    expect(capture.out.join("\n")).toContain("Usage:");
+  });
+
+  test("receive throws for missing args", async () => {
+    const { io, capture } = createMockIO();
+
+    await expect(
+      handleReceiveCommand(createCommandDeps(fakeApp, io), [], {}),
+    ).rejects.toThrow(CommandError);
+
+    try {
+      await handleReceiveCommand(createCommandDeps(fakeApp, io), [], {});
+    } catch (error) {
+      expect(error).toBeInstanceOf(CommandError);
+      expect((error as CommandError).event).toBe("receive.arguments.missing");
+    }
+
+    expect(capture.out.join("\n")).toContain("Usage:");
+  });
+
+  test("resource throws for unknown subcommand", async () => {
+    const { io } = createMockIO();
+
+    await expect(
+      handleResourceCommand(
+        createCommandDeps(fakeApp, io),
+        ["does-not-exist"],
+        {},
+      ),
+    ).rejects.toThrow(CommandError);
+
+    try {
+      await handleResourceCommand(
+        createCommandDeps(fakeApp, io),
+        ["does-not-exist"],
+        {},
+      );
+    } catch (error) {
+      expect(error).toBeInstanceOf(CommandError);
+      expect((error as CommandError).event).toBe("resource.subcommand.unknown");
+    }
+  });
+});

tests/cli/commands/mnemonic.test.ts

@@ -0,0 +1,165 @@
+import { expect, test, describe, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { DEFAULT_SEED } from "../mocks/engine";
+
+import { handleMnemonicCommand } from "../../../src/cli/commands/mnemonic";
+import { CommandError } from "../../../src/cli/commands/types";
+import {
+  createMockIO,
+  createMockPaths,
+  expectLogs,
+  type LogExpectation,
+} from "../mocks/command";
+import { BCHMnemonicURL } from "../../../src/utils/bch-mnemonic-url";
+
+type TestCase = {
+  inputs: string[];
+  options?: Record<string, string>;
+  shouldThrow: boolean;
+  expectedEvent?: string;
+  expectedData?: Record<string, unknown>;
+  logs?: LogExpectation[];
+};
+
+const testCases: TestCase[] = [
+  // Successful creation of a mnemonic file
+  {
+    inputs: ["create"],
+    shouldThrow: false,
+    expectedData: {
+      savedAs: expect.stringMatching(/^mnemonic-\w+$/),
+    },
+    logs: [{ out: "Mnemonic file created" }],
+  },
+  // Successfully creating a mnemonic file with a custom filename
+  {
+    inputs: ["create"],
+    options: { output: "custom-filename" },
+    shouldThrow: false,
+    expectedData: {
+      savedAs: "custom-filename",
+    },
+    logs: [{ out: "custom-filename" }],
+  },
+  // Successfully listing mnemonic files
+  {
+    inputs: ["list"],
+    shouldThrow: false,
+    expectedData: {
+      count: expect.toSatisfy((count: number) => count >= 1),
+    },
+    logs: [{ out: "mnemonic-test" }],
+  },
+  // Successfully exposing a mnemonic file
+  {
+    inputs: ["expose", "mnemonic-test"],
+    shouldThrow: false,
+    expectedData: {
+      mnemonic: DEFAULT_SEED,
+    },
+    logs: [{ out: DEFAULT_SEED }],
+  },
+  // Successfully importing a mnemonic file
+  {
+    inputs: ["import", ...DEFAULT_SEED.split(" ")],
+    shouldThrow: false,
+    expectedData: {
+      savedAs: expect.stringMatching(/^mnemonic-\w+$/),
+    },
+    logs: [{ out: "Mnemonic file created" }],
+  },
+  // Failure to import a mnemonic file due to missing arguments
+  {
+    inputs: ["import"],
+    shouldThrow: true,
+    expectedEvent: "mnemonic.import.seed_missing",
+  },
+  // Failure to expose a mnemonic file due to missing arguments
+  {
+    inputs: ["expose"],
+    shouldThrow: true,
+    expectedEvent: "mnemonic.expose.file_missing",
+  },
+  // Failure to expose a mnemonic file due to unknown mnemonic file
+  {
+    inputs: ["expose", "unknown-mnemonic-file"],
+    shouldThrow: true,
+    expectedEvent: "mnemonic.expose.file_not_found",
+  },
+  // Missing sub-command
+  {
+    inputs: [],
+    shouldThrow: true,
+    expectedEvent: "mnemonic.subcommand.missing",
+  },
+  // Unknown sub-command
+  {
+    inputs: ["unknown"],
+    shouldThrow: true,
+    expectedEvent: "mnemonic.subcommand.unknown",
+  },
+];
+
+describe("mnemonic commands", () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = mkdtempSync(path.join(tmpdir(), "xo-cli-mnemonic-tests-"));
+
+    // Write a single test mnemonic file to the temp directory
+    writeFileSync(
+      path.join(tempDir, "mnemonic-test"),
+      BCHMnemonicURL.fromSeed(DEFAULT_SEED).toURL(),
+      "utf8",
+    );
+  });
+
+  afterEach(async () => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  test.each(testCases)(
+    "mnemonic command: $inputs",
+    async ({
+      inputs,
+      options,
+      shouldThrow,
+      expectedEvent,
+      expectedData,
+      logs,
+    }) => {
+      const { io, spies } = createMockIO();
+      const paths = createMockPaths(tempDir);
+
+      if (shouldThrow) {
+        try {
+          await handleMnemonicCommand({ io, paths }, inputs, options ?? {});
+          expect.fail("Expected command to throw");
+        } catch (error) {
+          if (expectedEvent) {
+            expect(error).toBeInstanceOf(CommandError);
+            expect((error as CommandError).event).toBe(expectedEvent);
+          }
+        }
+      } else {
+        const result = await handleMnemonicCommand(
+          { io, paths },
+          inputs,
+          options ?? {},
+        );
+        if (expectedData) {
+          Object.entries(expectedData).forEach(([key, value]) => {
+            expect(result[key as keyof typeof result]).toEqual(value);
+          });
+        }
+      }
+
+      if (logs) {
+        expectLogs(spies, logs);
+      }
+    },
+  );
+});

tests/cli/commands/receive.test.ts

@@ -0,0 +1,142 @@
+import { expect, test, describe, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import {
+  createMockAppService,
+  createMockEngine,
+  DEFAULT_SEED,
+} from "../mocks/engine";
+import { type Engine } from "@xo-cash/engine";
+import { p2pkhTemplate } from "../mocks/template-p2pkh";
+import { AppService } from "../../../src/services/app";
+
+import { handleReceiveCommand } from "../../../src/cli/commands/receive";
+import { CommandError } from "../../../src/cli/commands/types";
+import {
+  createCommandDeps,
+  createMockIO,
+  expectLogs,
+  type LogExpectation,
+} from "../mocks/command";
+
+type TestCase = {
+  name: string;
+  inputs: string[];
+  options?: Record<string, string>;
+  shouldThrow: boolean;
+  expectedEvent?: string;
+  expectedData?: Record<string, unknown>;
+  logs?: LogExpectation[];
+};
+
+const testCases: TestCase[] = [
+  // Successful address generation with template name and output identifier
+  {
+    name: "generates address with template name and output",
+    inputs: ["Wallet (P2PKH)", "receiveOutput"],
+    shouldThrow: false,
+    expectedData: {
+      address: expect.stringMatching(/^bitcoincash:q[a-z0-9]+$/),
+    },
+    logs: [{ out: "bitcoincash:q" }],
+  },
+  // Successful address generation with role specified
+  {
+    name: "generates address with template name, output, and role",
+    inputs: ["Wallet (P2PKH)", "receiveOutput", "receiver"],
+    shouldThrow: false,
+    expectedData: {
+      address: expect.stringMatching(/^bitcoincash:q[a-z0-9]+$/),
+    },
+    logs: [{ out: "bitcoincash:q" }],
+  },
+  // Missing all required arguments
+  {
+    name: "throws when no arguments provided",
+    inputs: [],
+    shouldThrow: true,
+    expectedEvent: "receive.arguments.missing",
+  },
+  // Missing output identifier
+  {
+    name: "throws when output identifier missing",
+    inputs: ["Wallet (P2PKH)"],
+    shouldThrow: true,
+    expectedEvent: "receive.arguments.missing",
+  },
+  // Unknown template
+  {
+    name: "throws when template not found",
+    inputs: ["unknown-template", "receiveOutput"],
+    shouldThrow: true,
+    expectedEvent: "template.resolve.not_found",
+  },
+];
+
+describe("receive command", () => {
+  let engine: Engine;
+  let app: AppService;
+  let tempDir: string;
+
+  beforeEach(async () => {
+    const mockEngine = await createMockEngine(DEFAULT_SEED);
+    engine = mockEngine.engine;
+    await engine.importTemplate(p2pkhTemplate);
+
+    app = await createMockAppService(engine);
+
+    tempDir = mkdtempSync(path.join(tmpdir(), "xo-cli-receive-tests-"));
+  });
+
+  afterEach(async () => {
+    await engine.stop();
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  test.each(testCases)(
+    "$name",
+    async ({
+      inputs,
+      options,
+      shouldThrow,
+      expectedEvent,
+      expectedData,
+      logs,
+    }) => {
+      const { io, spies } = createMockIO();
+
+      if (shouldThrow) {
+        try {
+          await handleReceiveCommand(
+            createCommandDeps(app, io),
+            inputs,
+            options ?? {},
+          );
+          expect.fail("Expected command to throw");
+        } catch (error) {
+          if (expectedEvent) {
+            expect(error).toBeInstanceOf(CommandError);
+            expect((error as CommandError).event).toBe(expectedEvent);
+          }
+        }
+      } else {
+        const result = await handleReceiveCommand(
+          createCommandDeps(app, io),
+          inputs,
+          options ?? {},
+        );
+        if (expectedData) {
+          Object.entries(expectedData).forEach(([key, value]) => {
+            expect(result[key as keyof typeof result]).toEqual(value);
+          });
+        }
+      }
+
+      if (logs) {
+        expectLogs(spies, logs);
+      }
+    },
+  );
+});

tests/cli/commands/resource.test.ts

@@ -0,0 +1,366 @@
+import { expect, test, describe, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import {
+  addFakeResource,
+  createMockAppService,
+  createMockEngine,
+  DEFAULT_SEED,
+  reserveResource,
+} from "../mocks/engine";
+import { type Engine } from "@xo-cash/engine";
+import { p2pkhTemplate } from "../mocks/template-p2pkh";
+import { AppService } from "../../../src/services/app";
+
+import { handleResourceCommand } from "../../../src/cli/commands/resource";
+import { CommandError } from "../../../src/cli/commands/types";
+import {
+  createCommandDeps,
+  createMockIO,
+  expectLogs,
+  type LogExpectation,
+} from "../mocks/command";
+import { State } from "@xo-cash/state";
+
+type TestCase = {
+  name: string;
+  inputs: string[];
+  options?: Record<string, string>;
+  shouldThrow: boolean;
+  expectedEvent?: string;
+  expectedData?: Record<string, unknown>;
+  logs?: LogExpectation[];
+};
+
+const testCases: TestCase[] = [
+  // List commands (no resources in empty wallet)
+  {
+    name: "list returns empty count when no resources",
+    inputs: ["list"],
+    shouldThrow: false,
+    expectedData: {
+      count: 0,
+    },
+    logs: [{ out: "No resources found" }],
+  },
+  {
+    name: "list reserved returns empty count when no reserved resources",
+    inputs: ["list", "reserved"],
+    shouldThrow: false,
+    expectedData: {
+      count: 0,
+    },
+    logs: [{ out: "No resources found" }],
+  },
+  {
+    name: "list all returns empty count when no resources",
+    inputs: ["list", "all"],
+    shouldThrow: false,
+    expectedData: {
+      count: 0,
+    },
+    logs: [{ out: "No resources found" }],
+  },
+  // Unreserve-all with no resources
+  {
+    name: "unreserve-all returns zero count when no reserved resources",
+    inputs: ["unreserve-all"],
+    shouldThrow: false,
+    expectedData: {
+      count: 0,
+    },
+    logs: [{ out: "No reserved resources" }],
+  },
+  // Error cases
+  {
+    name: "throws when no subcommand provided",
+    inputs: [],
+    shouldThrow: true,
+    expectedEvent: "resource.subcommand.missing",
+  },
+  {
+    name: "throws when unknown subcommand provided",
+    inputs: ["unknown-subcommand"],
+    shouldThrow: true,
+    expectedEvent: "resource.subcommand.unknown",
+  },
+  {
+    name: "throws when unreserve called without outpoint",
+    inputs: ["unreserve"],
+    shouldThrow: true,
+    expectedEvent: "resource.unreserve.outpoint_missing",
+  },
+  {
+    name: "throws when unreserve called with invalid outpoint format (no colon)",
+    inputs: ["unreserve", "invalid-outpoint"],
+    shouldThrow: true,
+    expectedEvent: "resource.unreserve.outpoint_invalid",
+  },
+  {
+    name: "throws when unreserve called with invalid outpoint format (no vout)",
+    inputs: ["unreserve", "abc123:"],
+    shouldThrow: true,
+    expectedEvent: "resource.unreserve.outpoint_invalid",
+  },
+  {
+    name: "throws when unreserve called with non-existent UTXO",
+    inputs: [
+      "unreserve",
+      "0000000000000000000000000000000000000000000000000000000000000000:0",
+    ],
+    shouldThrow: true,
+    expectedEvent: "resource.unreserve.utxo_missing",
+  },
+];
+
+describe("resource command", () => {
+  let engine: Engine;
+  let app: AppService;
+  let tempDir: string;
+
+  beforeEach(async () => {
+    const mockEngine = await createMockEngine(DEFAULT_SEED);
+    engine = mockEngine.engine;
+    await engine.importTemplate(p2pkhTemplate);
+
+    app = await createMockAppService(engine);
+
+    tempDir = mkdtempSync(path.join(tmpdir(), "xo-cli-resource-tests-"));
+  });
+
+  afterEach(async () => {
+    await engine.stop();
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  test.each(testCases)(
+    "$name",
+    async ({
+      inputs,
+      options,
+      shouldThrow,
+      expectedEvent,
+      expectedData,
+      logs,
+    }) => {
+      const { io, spies } = createMockIO();
+
+      if (shouldThrow) {
+        try {
+          await handleResourceCommand(
+            createCommandDeps(app, io),
+            inputs,
+            options ?? {},
+          );
+          expect.fail("Expected command to throw");
+        } catch (error) {
+          if (expectedEvent) {
+            expect(error).toBeInstanceOf(CommandError);
+            expect((error as CommandError).event).toBe(expectedEvent);
+          }
+        }
+      } else {
+        const result = await handleResourceCommand(
+          createCommandDeps(app, io),
+          inputs,
+          options ?? {},
+        );
+        if (expectedData) {
+          Object.entries(expectedData).forEach(([key, value]) => {
+            expect(result[key as keyof typeof result]).toEqual(value);
+          });
+        }
+      }
+
+      if (logs) {
+        expectLogs(spies, logs);
+      }
+    },
+  );
+});
+
+describe("resource command with populated data", () => {
+  let engine: Engine;
+  let state: State;
+  let app: AppService;
+  let tempDir: string;
+
+  beforeEach(async () => {
+    const mockEngine = await createMockEngine(DEFAULT_SEED);
+    engine = mockEngine.engine;
+    state = mockEngine.state;
+    await engine.importTemplate(p2pkhTemplate);
+    app = await createMockAppService(engine);
+    tempDir = mkdtempSync(path.join(tmpdir(), "xo-cli-resource-tests-"));
+  });
+
+  afterEach(async () => {
+    await engine.stop();
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  test("list returns count when resources exist", async () => {
+    await addFakeResource(state, { valueSatoshis: 50000 });
+    await addFakeResource(state, { valueSatoshis: 25000 });
+
+    const { io, spies } = createMockIO();
+    const result = await handleResourceCommand(
+      createCommandDeps(app, io),
+      ["list"],
+      {},
+    );
+
+    expect(result.count).toBe(2);
+    expectLogs(spies, [{ out: "Total resources: 2" }]);
+  });
+
+  test("list shows total satoshis", async () => {
+    await addFakeResource(state, { valueSatoshis: 50000 });
+    await addFakeResource(state, { valueSatoshis: 25000 });
+
+    const { io, spies } = createMockIO();
+    await handleResourceCommand(createCommandDeps(app, io), ["list"], {});
+
+    expectLogs(spies, [{ out: "Total satoshis: 75000" }]);
+  });
+
+  test("list excludes reserved resources by default", async () => {
+    await addFakeResource(state, { valueSatoshis: 50000 });
+    await addFakeResource(state, {
+      valueSatoshis: 25000,
+      reservedBy: "inv-123",
+    });
+
+    const { io } = createMockIO();
+    const result = await handleResourceCommand(
+      createCommandDeps(app, io),
+      ["list"],
+      {},
+    );
+
+    expect(result.count).toBe(1);
+  });
+
+  test("list reserved shows only reserved resources", async () => {
+    await addFakeResource(state, { valueSatoshis: 50000 });
+    await addFakeResource(state, {
+      valueSatoshis: 25000,
+      reservedBy: "inv-123",
+    });
+    await addFakeResource(state, {
+      valueSatoshis: 10000,
+      reservedBy: "inv-456",
+    });
+
+    const { io, spies } = createMockIO();
+    const result = await handleResourceCommand(
+      createCommandDeps(app, io),
+      ["list", "reserved"],
+      {},
+    );
+
+    expect(result.count).toBe(2);
+    expectLogs(spies, [{ out: "reserved for inv-123" }]);
+  });
+
+  test("list all shows both reserved and unreserved", async () => {
+    await addFakeResource(state, { valueSatoshis: 50000 });
+    await addFakeResource(state, {
+      valueSatoshis: 25000,
+      reservedBy: "inv-123",
+    });
+
+    const { io } = createMockIO();
+    const result = await handleResourceCommand(
+      createCommandDeps(app, io),
+      ["list", "all"],
+      {},
+    );
+
+    expect(result.count).toBe(2);
+  });
+
+  test("unreserve releases a reserved UTXO", async () => {
+    const resource = await addFakeResource(state, {
+      valueSatoshis: 25000,
+      reservedBy: "inv-123",
+    });
+
+    const { io, spies } = createMockIO();
+    await handleResourceCommand(
+      createCommandDeps(app, io),
+      [
+        "unreserve",
+        `${resource.outpointTransactionHash}:${resource.outpointIndex}`,
+      ],
+      {},
+    );
+
+    expectLogs(spies, [
+      { out: "Unreserved" },
+      { out: "was reserved for inv-123" },
+    ]);
+
+    const resources = await engine.listUnspentOutputsData();
+    const target = resources.find(
+      (r) => r.outpointTransactionHash === resource.outpointTransactionHash,
+    );
+    expect(target?.reservedBy).toBeUndefined();
+  });
+
+  test("unreserve reports when UTXO is not reserved", async () => {
+    const resource = await addFakeResource(state, { valueSatoshis: 25000 });
+
+    const { io, spies } = createMockIO();
+    await handleResourceCommand(
+      createCommandDeps(app, io),
+      [
+        "unreserve",
+        `${resource.outpointTransactionHash}:${resource.outpointIndex}`,
+      ],
+      {},
+    );
+
+    expectLogs(spies, [{ out: "UTXO is not reserved" }]);
+  });
+
+  test("unreserve-all releases all reserved UTXOs", async () => {
+    await addFakeResource(state, { valueSatoshis: 50000 });
+    await addFakeResource(state, {
+      valueSatoshis: 25000,
+      reservedBy: "inv-123",
+    });
+    await addFakeResource(state, {
+      valueSatoshis: 10000,
+      reservedBy: "inv-456",
+    });
+
+    const { io, spies } = createMockIO();
+    const result = await handleResourceCommand(
+      createCommandDeps(app, io),
+      ["unreserve-all"],
+      {},
+    );
+
+    expect(result.count).toBe(2);
+    expectLogs(spies, [{ out: "Unreserved" }, { out: "2" }]);
+
+    const resources = await engine.listUnspentOutputsData();
+    const reserved = resources.filter((r) => r.reservedBy);
+    expect(reserved).toHaveLength(0);
+  });
+
+  test("list displays outpoint information", async () => {
+    const resource = await addFakeResource(state, { valueSatoshis: 12345 });
+
+    const { io, spies } = createMockIO();
+    await handleResourceCommand(createCommandDeps(app, io), ["list"], {});
+
+    expectLogs(spies, [
+      { out: resource.outpointTransactionHash },
+      { out: "12345 sats" },
+    ]);
+  });
+});

tests/cli/commands/settings.test.ts

@@ -0,0 +1,83 @@
+/// <reference types="node" />
+
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { handleSettingsCommand } from "../../../src/cli/commands/settings";
+import { CommandError } from "../../../src/cli/commands/types";
+import { createMockIO, createMockPaths } from "../mocks/command";
+
+describe("settings command", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(path.join(tmpdir(), "xo-cli-settings-command-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  test("shows default settings when .wallet does not exist", async () => {
+    const { io, capture } = createMockIO();
+    const paths = createMockPaths(tempDir);
+
+    const result = await handleSettingsCommand({ io, paths }, ["show"], {});
+
+    expect(result).toEqual({ currency: "USD" });
+    expect(capture.out.join("\n")).toContain("currency");
+    expect(capture.out.join("\n")).toContain("USD");
+  });
+
+  test("sets and gets currency", async () => {
+    const { io, capture } = createMockIO();
+    const paths = createMockPaths(tempDir);
+
+    await handleSettingsCommand({ io, paths }, ["set", "currency", "aud"], {});
+    const getResult = await handleSettingsCommand(
+      { io, paths },
+      ["get", "currency"],
+      {},
+    );
+
+    expect(getResult).toEqual({ key: "currency", value: "AUD" });
+    expect(capture.out).toContain("Updated currency: AUD");
+    expect(capture.out).toContain("AUD");
+  });
+
+  test("sets default-mnemonic and persists JSON .wallet", async () => {
+    const { io } = createMockIO();
+    const paths = createMockPaths(tempDir);
+
+    await handleSettingsCommand(
+      { io, paths },
+      ["set", "default-mnemonic", "mnemonic-primary"],
+      {},
+    );
+
+    const persisted = JSON.parse(readFileSync(paths.walletConfigPath, "utf8")) as {
+      currency: string;
+      "default-mnemonic"?: string;
+    };
+
+    expect(persisted).toEqual({
+      currency: "USD",
+      "default-mnemonic": "mnemonic-primary",
+    });
+  });
+
+  test("throws command error for unknown subcommand", async () => {
+    const { io } = createMockIO();
+    const paths = createMockPaths(tempDir);
+
+    try {
+      await handleSettingsCommand({ io, paths }, ["unknown"], {});
+      expect.fail("Expected settings command to throw");
+    } catch (error) {
+      expect(error).toBeInstanceOf(CommandError);
+      expect((error as CommandError).event).toBe("settings.subcommand.unknown");
+    }
+  });
+});

tests/cli/commands/template.test.ts

@@ -0,0 +1,266 @@
+import { expect, test, describe, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import {
+  createMockAppService,
+  createMockEngine,
+  DEFAULT_SEED,
+} from "../mocks/engine";
+import { type Engine } from "@xo-cash/engine";
+import {
+  p2pkhTemplate,
+  p2pkhTemplateIdentifier,
+} from "../mocks/template-p2pkh";
+import { AppService } from "../../../src/services/app";
+
+import { handleTemplateCommand } from "../../../src/cli/commands/template";
+import { CommandError } from "../../../src/cli/commands/types";
+import {
+  createCommandDeps,
+  createMockIO,
+  expectLogs,
+  type LogExpectation,
+} from "../mocks/command";
+
+type TestCase = {
+  name: string;
+  inputs: string[];
+  options?: Record<string, string>;
+  shouldThrow: boolean;
+  expectedEvent?: string;
+  expectedData?: Record<string, unknown>;
+  logs?: LogExpectation[];
+};
+
+const testCases: TestCase[] = [
+  // List command
+  {
+    name: "list returns count of imported templates",
+    inputs: ["list"],
+    shouldThrow: false,
+    expectedData: {
+      count: 1,
+    },
+    logs: [{ out: "Wallet (P2PKH)" }],
+  },
+  // List by category
+  {
+    name: "list action returns actions for template",
+    inputs: ["list", "action", p2pkhTemplateIdentifier],
+    shouldThrow: false,
+    expectedData: {},
+    logs: [{ out: "receive" }],
+  },
+  {
+    name: "list output returns outputs for template",
+    inputs: ["list", "output", p2pkhTemplateIdentifier],
+    shouldThrow: false,
+    expectedData: {},
+    logs: [{ out: "receiveOutput" }],
+  },
+  {
+    name: "list variable returns variables for template",
+    inputs: ["list", "variable", p2pkhTemplateIdentifier],
+    shouldThrow: false,
+    expectedData: {},
+    logs: [{ out: "ownerKey" }],
+  },
+  {
+    name: "list transaction returns transactions for template",
+    inputs: ["list", "transaction", p2pkhTemplateIdentifier],
+    shouldThrow: false,
+    expectedData: {},
+  },
+  {
+    name: "list lockingscript returns locking scripts for template",
+    inputs: ["list", "lockingscript", p2pkhTemplateIdentifier],
+    shouldThrow: false,
+    expectedData: {},
+  },
+  // Inspect command
+  {
+    name: "inspect action returns action details",
+    inputs: ["inspect", "action", p2pkhTemplateIdentifier, "receive"],
+    shouldThrow: false,
+    expectedData: {},
+  },
+  {
+    name: "inspect output returns output details",
+    inputs: ["inspect", "output", p2pkhTemplateIdentifier, "receiveOutput"],
+    shouldThrow: false,
+    expectedData: {},
+  },
+  {
+    name: "inspect variable returns variable details",
+    inputs: ["inspect", "variable", p2pkhTemplateIdentifier, "ownerKey"],
+    shouldThrow: false,
+    expectedData: {},
+  },
+  // Error cases - subcommand
+  {
+    name: "throws when no subcommand provided",
+    inputs: [],
+    shouldThrow: true,
+    expectedEvent: "template.subcommand.missing",
+  },
+  {
+    name: "throws when unknown subcommand provided",
+    inputs: ["unknown-subcommand"],
+    shouldThrow: true,
+    expectedEvent: "template.subcommand.unknown",
+  },
+  // Error cases - import
+  {
+    name: "throws when import called without file",
+    inputs: ["import"],
+    shouldThrow: true,
+    expectedEvent: "template.import.file_missing",
+  },
+  {
+    name: "throws when import called with non-existent file",
+    inputs: ["import", "non-existent-file.json"],
+    shouldThrow: true,
+    expectedEvent: "template.import.file_not_found",
+  },
+  // Error cases - list category
+  {
+    name: "throws when list category called without template identifier",
+    inputs: ["list", "action"],
+    shouldThrow: true,
+    expectedEvent: "template.list.identifier_missing",
+  },
+  {
+    name: "throws when list category called with unknown template",
+    inputs: ["list", "action", "unknown-template"],
+    shouldThrow: true,
+    expectedEvent: "template.list.not_found",
+  },
+  {
+    name: "throws when list called with unknown category",
+    inputs: ["list", "unknown-category", p2pkhTemplateIdentifier],
+    shouldThrow: true,
+    expectedEvent: "template.list.category_unknown",
+  },
+  // Error cases - inspect
+  {
+    name: "throws when inspect called without all arguments",
+    inputs: ["inspect", "action"],
+    shouldThrow: true,
+    expectedEvent: "template.inspect.arguments_missing",
+  },
+  {
+    name: "throws when inspect called with unknown template",
+    inputs: ["inspect", "action", "unknown-template", "receive"],
+    shouldThrow: true,
+    expectedEvent: "template.resolve.not_found",
+  },
+  {
+    name: "throws when inspect called with unknown action",
+    inputs: ["inspect", "action", p2pkhTemplateIdentifier, "unknown-action"],
+    shouldThrow: true,
+    expectedEvent: "template.inspect.action_missing",
+  },
+  {
+    name: "throws when inspect called with unknown category",
+    inputs: ["inspect", "unknown-category", p2pkhTemplateIdentifier, "field"],
+    shouldThrow: true,
+    expectedEvent: "template.inspect.category_unknown",
+  },
+  // Error cases - set-default
+  {
+    name: "throws when set-default called without all arguments",
+    inputs: ["set-default", "template"],
+    shouldThrow: true,
+    expectedEvent: "template.default.arguments_missing",
+  },
+];
+
+describe("template command", () => {
+  let engine: Engine;
+  let app: AppService;
+  let tempDir: string;
+
+  beforeEach(async () => {
+    const mockEngine = await createMockEngine(DEFAULT_SEED);
+    engine = mockEngine.engine;
+    await engine.importTemplate(p2pkhTemplate);
+
+    app = await createMockAppService(engine);
+
+    tempDir = mkdtempSync(path.join(tmpdir(), "xo-cli-template-tests-"));
+  });
+
+  afterEach(async () => {
+    await engine.stop();
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  test.each(testCases)(
+    "$name",
+    async ({
+      inputs,
+      options,
+      shouldThrow,
+      expectedEvent,
+      expectedData,
+      logs,
+    }) => {
+      const { io, spies } = createMockIO();
+
+      if (shouldThrow) {
+        try {
+          await handleTemplateCommand(
+            createCommandDeps(app, io),
+            inputs,
+            options ?? {},
+          );
+          expect.fail("Expected command to throw");
+        } catch (error) {
+          if (expectedEvent) {
+            expect(error).toBeInstanceOf(CommandError);
+            expect((error as CommandError).event).toBe(expectedEvent);
+          }
+        }
+      } else {
+        const result = await handleTemplateCommand(
+          createCommandDeps(app, io),
+          inputs,
+          options ?? {},
+        );
+        if (expectedData) {
+          Object.entries(expectedData).forEach(([key, value]) => {
+            expect(result[key as keyof typeof result]).toEqual(value);
+          });
+        }
+      }
+
+      if (logs) {
+        expectLogs(spies, logs);
+      }
+    },
+  );
+
+  test("import imports template from file", async () => {
+    const templatePath = path.join(tempDir, "test-template.json");
+    writeFileSync(templatePath, JSON.stringify(p2pkhTemplate));
+
+    const { io } = createMockIO();
+
+    const originalCwd = process.cwd();
+    process.chdir(tempDir);
+
+    try {
+      const result = await handleTemplateCommand(
+        createCommandDeps(app, io),
+        ["import", "test-template.json"],
+        {},
+      );
+
+      expect(result.templateFile).toBe("test-template.json");
+    } finally {
+      process.chdir(originalCwd);
+    }
+  });
+});

tests/cli/integration/entry.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "vitest";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+
+const runCli = (args: string[]) => {
+  const tsxPath = path.resolve(process.cwd(), "node_modules/.bin/tsx");
+  const cliPath = path.resolve(process.cwd(), "src/cli/index.ts");
+
+  return spawnSync(tsxPath, [cliPath, ...args], {
+    encoding: "utf8",
+    cwd: process.cwd(),
+  });
+};
+
+describe("cli entry boundary behavior", () => {
+  test("returns non-zero for incomplete mnemonic invocation", () => {
+    const result = runCli(["mnemonic"]);
+
+    expect(result.status).toBe(1);
+    expect(result.stdout).toContain("Usage:");
+  });
+
+  test("returns zero for mnemonic list invocation", () => {
+    const result = runCli(["mnemonic", "list"]);
+
+    expect(result.status).toBe(0);
+  });
+});

tests/cli/mnemonic.test.ts

@@ -0,0 +1,214 @@
+import { expect, test, describe, beforeEach, afterEach } from "vitest";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import {
+  createMnemonicSeed,
+  createMnemonicFile,
+  resolveMnemonicFilePath,
+  loadMnemonic,
+  listMnemonicFiles,
+} from "../../src/cli/mnemonic";
+import { BCHMnemonicURL } from "../../src/utils/bch-mnemonic-url";
+
+const TEST_SEED =
+  "page pencil stock planet limb cluster assault speak off joke private pioneer";
+
+describe("mnemonic utilities", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = path.join(tmpdir(), `xo-cli-mnemonic-utils-test-${Date.now()}`);
+    mkdirSync(tempDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  describe("createMnemonicSeed", () => {
+    test("generates a valid BIP39 mnemonic", () => {
+      const mnemonic = createMnemonicSeed();
+
+      expect(typeof mnemonic).toBe("string");
+      const words = mnemonic.split(" ");
+      expect(words.length).toBe(12);
+    });
+
+    test("generates unique mnemonics on each call", () => {
+      const mnemonic1 = createMnemonicSeed();
+      const mnemonic2 = createMnemonicSeed();
+
+      expect(mnemonic1).not.toBe(mnemonic2);
+    });
+  });
+
+  describe("createMnemonicFile", () => {
+    test("creates a mnemonic file with auto-generated name", () => {
+      const filename = createMnemonicFile(tempDir, TEST_SEED);
+
+      expect(filename).toMatch(/^mnemonic-page$/);
+      expect(existsSync(path.join(tempDir, filename))).toBe(true);
+    });
+
+    test("creates a mnemonic file with custom name", () => {
+      const filename = createMnemonicFile(tempDir, TEST_SEED, "my-wallet");
+
+      expect(filename).toBe("my-wallet");
+      expect(existsSync(path.join(tempDir, filename))).toBe(true);
+    });
+
+    test("writes valid BCHMnemonicURL format", () => {
+      const filename = createMnemonicFile(tempDir, TEST_SEED, "test-wallet");
+      const content = readFileSync(path.join(tempDir, filename), "utf8");
+
+      expect(content).toMatch(/^bch-mnemonic:/);
+      const parsed = BCHMnemonicURL.fromURL(content);
+      expect(parsed).toBeDefined();
+    });
+
+    test("sanitizes filename to basename only", () => {
+      const filename = createMnemonicFile(
+        tempDir,
+        TEST_SEED,
+        "../../../evil-path",
+      );
+
+      expect(filename).toBe("evil-path");
+      expect(existsSync(path.join(tempDir, "evil-path"))).toBe(true);
+      expect(existsSync(path.join(tempDir, "../../../evil-path"))).toBe(false);
+    });
+
+    test("throws when mnemonic is empty", () => {
+      expect(() => createMnemonicFile(tempDir, "")).toThrow();
+    });
+  });
+
+  describe("resolveMnemonicFilePath", () => {
+    test("resolves absolute path when file exists", () => {
+      const filePath = path.join(tempDir, "mnemonic-absolute");
+      writeFileSync(filePath, "test");
+
+      const resolved = resolveMnemonicFilePath(tempDir, filePath);
+      expect(resolved).toBe(filePath);
+    });
+
+    test("resolves path relative to cwd when file exists", () => {
+      const originalCwd = process.cwd();
+      process.chdir(tempDir);
+
+      try {
+        writeFileSync(path.join(tempDir, "mnemonic-relative"), "test");
+        const resolved = resolveMnemonicFilePath(
+          "/nonexistent",
+          "mnemonic-relative",
+        );
+        expect(resolved).toBe(path.join(tempDir, "mnemonic-relative"));
+      } finally {
+        process.chdir(originalCwd);
+      }
+    });
+
+    test("resolves from mnemonicsDir when file exists there", () => {
+      writeFileSync(path.join(tempDir, "mnemonic-test"), "test");
+
+      const resolved = resolveMnemonicFilePath(tempDir, "mnemonic-test");
+      expect(resolved).toBe(path.join(tempDir, "mnemonic-test"));
+    });
+
+    test("throws when file not found anywhere", () => {
+      expect(() =>
+        resolveMnemonicFilePath(tempDir, "nonexistent-file"),
+      ).toThrow(/Mnemonic file not found/);
+    });
+
+    test("strips path components and looks up basename in mnemonicsDir", () => {
+      writeFileSync(path.join(tempDir, "mnemonic-basename"), "test");
+
+      const resolved = resolveMnemonicFilePath(
+        tempDir,
+        "some/path/mnemonic-basename",
+      );
+      expect(resolved).toBe(path.join(tempDir, "mnemonic-basename"));
+    });
+  });
+
+  describe("loadMnemonic", () => {
+    test("loads mnemonic from file", () => {
+      createMnemonicFile(tempDir, TEST_SEED, "test-load");
+
+      const loaded = loadMnemonic(tempDir, "test-load");
+      expect(loaded).toBe(TEST_SEED);
+    });
+
+    test("loads mnemonic from absolute path", () => {
+      const filePath = path.join(tempDir, "mnemonic-absolute-load");
+      createMnemonicFile(tempDir, TEST_SEED, "mnemonic-absolute-load");
+
+      const loaded = loadMnemonic(tempDir, filePath);
+      expect(loaded).toBe(TEST_SEED);
+    });
+
+    test("throws when file not found", () => {
+      expect(() => loadMnemonic(tempDir, "nonexistent")).toThrow(
+        /Mnemonic file not found/,
+      );
+    });
+
+    test("throws when file contains invalid data", () => {
+      writeFileSync(
+        path.join(tempDir, "mnemonic-invalid"),
+        "not a valid mnemonic url",
+      );
+
+      expect(() => loadMnemonic(tempDir, "mnemonic-invalid")).toThrow();
+    });
+  });
+
+  describe("listMnemonicFiles", () => {
+    test("returns empty array when no mnemonic files exist", () => {
+      const files = listMnemonicFiles(tempDir);
+      expect(files).toEqual([]);
+    });
+
+    test("lists only files starting with 'mnemonic-'", () => {
+      writeFileSync(path.join(tempDir, "mnemonic-one"), "test");
+      writeFileSync(path.join(tempDir, "mnemonic-two"), "test");
+      writeFileSync(path.join(tempDir, "other-file"), "test");
+      writeFileSync(path.join(tempDir, "wallet.json"), "test");
+
+      const files = listMnemonicFiles(tempDir);
+      expect(files).toHaveLength(2);
+      expect(files).toContain("mnemonic-one");
+      expect(files).toContain("mnemonic-two");
+      expect(files).not.toContain("other-file");
+      expect(files).not.toContain("wallet.json");
+    });
+
+    test("returns sorted or consistent ordering", () => {
+      writeFileSync(path.join(tempDir, "mnemonic-zebra"), "test");
+      writeFileSync(path.join(tempDir, "mnemonic-alpha"), "test");
+      writeFileSync(path.join(tempDir, "mnemonic-beta"), "test");
+
+      const files = listMnemonicFiles(tempDir);
+      expect(files).toHaveLength(3);
+    });
+  });
+
+  describe("round-trip", () => {
+    test("create and load preserves mnemonic exactly", () => {
+      const original = createMnemonicSeed();
+      createMnemonicFile(tempDir, original, "roundtrip-test");
+
+      const loaded = loadMnemonic(tempDir, "roundtrip-test");
+      expect(loaded).toBe(original);
+    });
+  });
+});

tests/cli/mocks/command.ts

@@ -0,0 +1,171 @@
+import { vi, expect, type Mock } from "vitest";
+import type {
+  BaseCommandDependencies,
+  CommandDependencies,
+  CommandIO,
+  CommandPaths,
+} from "../../../src/cli/commands/types";
+import type { AppService } from "../../../src/services/app";
+
+/**
+ * Captured CLI IO buffers used by tests.
+ */
+export type MockIOCapture = {
+  out: string[];
+  err: string[];
+  verbose: string[];
+};
+
+/**
+ * Spy functions for each IO channel.
+ */
+export type MockIOSpies = {
+  out: Mock;
+  err: Mock;
+  verbose: Mock;
+};
+
+/**
+ * Complete mock IO result including the IO adapter, capture buffers, and spies.
+ */
+export type MockIO = {
+  io: CommandIO;
+  capture: MockIOCapture;
+  spies: MockIOSpies;
+};
+
+/**
+ * Defines an expected log message for assertion.
+ * At least one of out, err, or verbose should be specified.
+ */
+export type LogExpectation = {
+  /** Expected substring (or exact match if exact=true) in io.out */
+  out?: string;
+  /** Expected substring (or exact match if exact=true) in io.err */
+  err?: string;
+  /** Expected substring (or exact match if exact=true) in io.verbose */
+  verbose?: string;
+  /** If true, match the string exactly instead of using contains (default: false) */
+  exact?: boolean;
+};
+
+/**
+ * Creates a command IO adapter that records every message using vi.fn() spies.
+ * This enables vitest's built-in matchers like toHaveBeenCalledWith.
+ */
+export const createMockIO = (): MockIO => {
+  const capture: MockIOCapture = {
+    out: [],
+    err: [],
+    verbose: [],
+  };
+
+  const outSpy = vi.fn((message: string) => {
+    capture.out.push(message);
+  });
+  const errSpy = vi.fn((message: string) => {
+    capture.err.push(message);
+  });
+  const verboseSpy = vi.fn((message: string) => {
+    capture.verbose.push(message);
+  });
+
+  const io: CommandIO = {
+    out: outSpy,
+    err: errSpy,
+    verbose: verboseSpy,
+  };
+
+  return {
+    io,
+    capture,
+    spies: {
+      out: outSpy,
+      err: errSpy,
+      verbose: verboseSpy,
+    },
+  };
+};
+
+/**
+ * Asserts that the expected log messages were printed to the appropriate IO channels.
+ * @param spies - The mock IO spies from createMockIO
+ * @param logs - Array of log expectations to validate
+ */
+export const expectLogs = (
+  spies: MockIOSpies,
+  logs: LogExpectation[],
+): void => {
+  for (const log of logs) {
+    if (log.out !== undefined) {
+      if (log.exact) {
+        expect(spies.out).toHaveBeenCalledWith(log.out);
+      } else {
+        expect(spies.out).toHaveBeenCalledWith(
+          expect.stringContaining(log.out),
+        );
+      }
+    }
+    if (log.err !== undefined) {
+      if (log.exact) {
+        expect(spies.err).toHaveBeenCalledWith(log.err);
+      } else {
+        expect(spies.err).toHaveBeenCalledWith(
+          expect.stringContaining(log.err),
+        );
+      }
+    }
+    if (log.verbose !== undefined) {
+      if (log.exact) {
+        expect(spies.verbose).toHaveBeenCalledWith(log.verbose);
+      } else {
+        expect(spies.verbose).toHaveBeenCalledWith(
+          expect.stringContaining(log.verbose),
+        );
+      }
+    }
+  }
+};
+
+/**
+ * Creates mock paths for testing.
+ * @param tempDir - Optional temp directory to use as base for all paths
+ */
+export const createMockPaths = (tempDir?: string): CommandPaths => {
+  const base = tempDir ?? "/tmp/xo-cli-test";
+  return {
+    mnemonicsDir: base,
+    dataDir: base,
+    walletConfigPath: `${base}/.wallet`,
+    workingDir: base,
+  };
+};
+
+/**
+ * Creates base command dependencies for commands that do not require the app.
+ * @param io - Command IO adapter
+ * @param paths - Optional custom paths (defaults to mock paths)
+ */
+export const createBaseCommandDeps = (
+  io: CommandIO,
+  paths?: CommandPaths,
+): BaseCommandDependencies => ({
+  io,
+  paths: paths ?? createMockPaths(),
+});
+
+/**
+ * Creates command dependencies for app-backed command handlers.
+ * @param app - App service instance
+ * @param io - Command IO adapter
+ * @param paths - Optional custom paths (defaults to mock paths)
+ */
+export const createCommandDeps = (
+  app: AppService,
+  io: CommandIO,
+  paths?: CommandPaths,
+): CommandDependencies => ({
+  app,
+  io,
+  paths: paths ?? createMockPaths(),
+});

tests/cli/mocks/electrum-service.ts

@@ -0,0 +1,12 @@
+/**
+ * Mock Electrum service for testing.
+ * NOTE & TODO: Do we even need this in the actual app? I forget why we had this, but it seems like its just overly complicating things
+ *              And we end up in stupid situations where we are creating a mock for a single function class.
+ */
+export class MockElectrumService {
+  constructor() {}
+
+  async hasSeenTransaction(transactionHash: string): Promise<boolean> {
+    return true;
+  }
+}

tests/cli/mocks/engine.ts

@@ -0,0 +1,180 @@
+import { BlockchainMonitor, Engine } from "@xo-cash/engine";
+
+import {
+  createStorageAdapter,
+  State,
+  StorageType,
+  UnspentOutputStatus,
+  type UnspentOutputData,
+} from "@xo-cash/state";
+import { InMemoryBlockchainProvider } from "@xo-cash/engine";
+import { convertMnemonicToSeedBytes } from "@xo-cash/crypto";
+
+import { binToHex, sha256 } from "@bitauth/libauth";
+import { AppService } from "../../../src/services/app";
+import { InMemoryStorage } from "../../../src/services/storage";
+import { MockElectrumService } from "./electrum-service";
+import { MockRatesService } from "./rates-service";
+import { RatesService } from "../../../src/services/rates";
+
+export const DEFAULT_SEED =
+  "page pencil stock planet limb cluster assault speak off joke private pioneer";
+
+/**
+ * Options for creating a fake resource (UTXO) in tests.
+ */
+export type FakeResourceOptions = {
+  /** Transaction hash of the outpoint. Auto-generated if not provided. */
+  outpointTransactionHash?: string;
+  /** Index of the outpoint in the transaction. Defaults to 0. */
+  outpointIndex?: number;
+  /** Value in satoshis. Defaults to 10000. */
+  valueSatoshis?: number;
+  /** Template identifier. Defaults to "test-template". */
+  templateIdentifier?: string;
+  /** Output identifier from the template. Defaults to "receiveOutput". */
+  outputIdentifier?: string;
+  /** Locking bytecode for this output. Defaults to a placeholder. */
+  lockingBytecode?: string;
+  /** Block height where the UTXO was mined. Defaults to 800000. */
+  minedAtHeight?: number;
+  /** Invitation identifier that reserves this output. Undefined means unreserved. */
+  reservedBy?: string;
+};
+
+/**
+ * Generates a random 64-character hex string representing a transaction hash.
+ */
+export const randomTxHash = (): string => {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+};
+
+/**
+ * Adds a fake resource (UTXO) to the engine's state for testing purposes.
+ * @param engine - The engine instance to add the resource to.
+ * @param options - Options for the fake resource. All fields have sensible defaults.
+ * @returns The created UnspentOutputData object.
+ */
+export const addFakeResource = async (
+  state: State,
+  options: FakeResourceOptions = {},
+): Promise<UnspentOutputData> => {
+  const resource: UnspentOutputData = {
+    status: UnspentOutputStatus.CONFIRMED,
+    selectable: true,
+    privacy: false,
+    templateIdentifier: options.templateIdentifier ?? "test-template",
+    outputIdentifier: options.outputIdentifier ?? "receiveOutput",
+    outpointIndex: options.outpointIndex ?? 0,
+    outpointTransactionHash: options.outpointTransactionHash ?? randomTxHash(),
+    minedAtHeight: options.minedAtHeight ?? 800000,
+    valueSatoshis: options.valueSatoshis ?? 10000,
+    scriptHash:
+      options.lockingBytecode ??
+      "76a914000000000000000000000000000000000000000088ac",
+    reservedBy: options.reservedBy,
+  };
+
+  await state.storeUnspentOutputData(resource);
+  return resource;
+};
+
+/**
+ * Reserves a resource for a specific invitation.
+ * @param engine - The engine instance.
+ * @param outpointTransactionHash - The transaction hash of the UTXO to reserve.
+ * @param outpointIndex - The output index of the UTXO to reserve.
+ * @param invitationIdentifier - The invitation identifier to reserve for.
+ */
+export const reserveResource = async (
+  state: State,
+  outpointTransactionHash: string,
+  outpointIndex: number,
+  invitationIdentifier: string,
+): Promise<void> => {
+  await state.executeBulkUnspentOutputReservation(
+    [{ outpointTransactionHash, outpointIndex }],
+    true,
+    invitationIdentifier,
+  );
+};
+
+/**
+ * Unreserves a resource from a specific invitation.
+ * @param engine - The engine instance.
+ * @param outpointTransactionHash - The transaction hash of the UTXO to unreserve.
+ * @param outpointIndex - The output index of the UTXO to unreserve.
+ * @param invitationIdentifier - The invitation identifier to unreserve from.
+ */
+export const unreserveResource = async (
+  state: State,
+  outpointTransactionHash: string,
+  outpointIndex: number,
+  invitationIdentifier: string,
+): Promise<void> => {
+  await state.executeBulkUnspentOutputReservation(
+    [{ outpointTransactionHash, outpointIndex }],
+    false,
+    invitationIdentifier,
+  );
+};
+
+/**
+ * Create a mock engine instance with a given seed. Uses the in-memory storage and blockchain provider.
+ * @param seed - The seed to use for the engine.
+ * @returns A mock engine instance.
+ */
+export const createMockEngine = async (seed: string) => {
+  // Create the in-memory storage adapter.
+  const storage = await createStorageAdapter({
+    storageType: "inmemory",
+    accountHash: binToHex(sha256.hash(convertMnemonicToSeedBytes(seed))),
+  });
+
+  // Initialize the storage adapter.
+  await storage.initialize();
+
+  // Create the state instance.
+  const state = new State(storage);
+
+  // Create the in-memory blockchain provider.
+  const blockchainProvider = new InMemoryBlockchainProvider();
+  await blockchainProvider.initialize({
+    applicationIdentifier: "xo-cli-tests",
+    electrumOptions: {},
+  });
+
+  // Create the blockchain monitor instance.
+  const blockchainMonitor = new BlockchainMonitor(state, blockchainProvider);
+  await blockchainMonitor.initializeEventListeners();
+
+  // Create the engine instance.
+  const engine = new Engine(seed, state, blockchainMonitor, blockchainProvider);
+  await engine.initializeStateSync();
+
+  return { engine, state, blockchainMonitor, blockchainProvider };
+};
+
+export const createMockAppService = async (engine: Engine) => {
+  const storage = await InMemoryStorage.create();
+
+  const mockRates = new MockRatesService();
+  const rates = new RatesService(mockRates);
+
+  const mockElectrum = new MockElectrumService();
+
+  const config = {
+    syncServerUrl: "http://localhost:3000",
+    engineConfig: {
+      databasePath: "test-data",
+      databaseFilename: "xo-wallet.db",
+    },
+    invitationStoragePath: "test-invitations.db",
+  };
+
+  return new AppService(engine, storage, config, mockElectrum, rates);
+};

tests/cli/mocks/rates-service.ts

@@ -0,0 +1,23 @@
+import { BaseRates } from "../../../src/utils/rates/base-rates";
+
+export class MockRatesService extends BaseRates {
+  constructor() {
+    super();
+  }
+
+  async getRate(numeratorUnitCode: string, denominatorUnitCode: string): Promise<number> {
+    return 1;
+  }
+
+  async start(): Promise<void> {
+    return;
+  }
+
+  async stop(): Promise<void> {
+    return;
+  }
+
+  async listPairs(): Promise<Set<string>> {
+    return new Set();
+  }
+}

tests/cli/paths.test.ts

@@ -0,0 +1,153 @@
+import { expect, test, describe, beforeEach, afterEach } from "vitest";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import path from "node:path";
+
+import {
+  getConfigDir,
+  getMnemonicsDir,
+  getDataDir,
+  getWalletConfigPath,
+  resolveMnemonicFilePath,
+} from "../../src/utils/paths";
+
+describe("paths utilities", () => {
+  describe("getConfigDir", () => {
+    test("returns path under ~/.config/xo-cli", () => {
+      const configDir = getConfigDir();
+
+      expect(configDir).toBe(path.join(homedir(), ".config", "xo-cli"));
+    });
+
+    test("creates the directory if it does not exist", () => {
+      const configDir = getConfigDir();
+
+      expect(existsSync(configDir)).toBe(true);
+    });
+  });
+
+  describe("getMnemonicsDir", () => {
+    test("returns path under config dir", () => {
+      const mnemonicsDir = getMnemonicsDir();
+
+      expect(mnemonicsDir).toBe(
+        path.join(homedir(), ".config", "xo-cli", "mnemonics"),
+      );
+    });
+
+    test("creates the directory if it does not exist", () => {
+      const mnemonicsDir = getMnemonicsDir();
+
+      expect(existsSync(mnemonicsDir)).toBe(true);
+    });
+  });
+
+  describe("getDataDir", () => {
+    test("returns path under config dir", () => {
+      const dataDir = getDataDir();
+
+      expect(dataDir).toBe(path.join(homedir(), ".config", "xo-cli", "data"));
+    });
+
+    test("creates the directory if it does not exist", () => {
+      const dataDir = getDataDir();
+
+      expect(existsSync(dataDir)).toBe(true);
+    });
+  });
+
+  describe("getWalletConfigPath", () => {
+    test("returns .wallet file path under config dir", () => {
+      const walletConfigPath = getWalletConfigPath();
+
+      expect(walletConfigPath).toBe(
+        path.join(homedir(), ".config", "xo-cli", ".wallet"),
+      );
+    });
+  });
+
+  describe("resolveMnemonicFilePath (global)", () => {
+    let tempDir: string;
+
+    beforeEach(() => {
+      tempDir = path.join(tmpdir(), `xo-cli-paths-test-${Date.now()}`);
+      mkdirSync(tempDir, { recursive: true });
+    });
+
+    afterEach(() => {
+      rmSync(tempDir, { recursive: true, force: true });
+    });
+
+    test("resolves absolute path when file exists", () => {
+      const filePath = path.join(tempDir, "mnemonic-test");
+      writeFileSync(filePath, "test");
+
+      const resolved = resolveMnemonicFilePath(filePath);
+      expect(resolved).toBe(filePath);
+    });
+
+    test("resolves path relative to cwd when file exists", () => {
+      const originalCwd = process.cwd();
+      process.chdir(tempDir);
+
+      try {
+        writeFileSync(path.join(tempDir, "mnemonic-cwd-test"), "test");
+        const resolved = resolveMnemonicFilePath("mnemonic-cwd-test");
+        expect(resolved).toBe(path.join(tempDir, "mnemonic-cwd-test"));
+      } finally {
+        process.chdir(originalCwd);
+      }
+    });
+
+    test("resolves from global mnemonics dir when file exists there", () => {
+      const mnemonicsDir = getMnemonicsDir();
+      const testFile = path.join(mnemonicsDir, "mnemonic-global-test");
+
+      try {
+        writeFileSync(testFile, "test");
+        const resolved = resolveMnemonicFilePath("mnemonic-global-test");
+        expect(resolved).toBe(testFile);
+      } finally {
+        if (existsSync(testFile)) {
+          rmSync(testFile);
+        }
+      }
+    });
+
+    test("throws when file not found anywhere", () => {
+      expect(() =>
+        resolveMnemonicFilePath("nonexistent-mnemonic-file-xyz"),
+      ).toThrow(/Mnemonic file not found/);
+    });
+
+    test("does not resolve absolute path if file does not exist", () => {
+      const nonExistentPath = "/nonexistent/path/mnemonic-test";
+      expect(() => resolveMnemonicFilePath(nonExistentPath)).toThrow(
+        /Mnemonic file not found/,
+      );
+    });
+  });
+
+  describe("path hierarchy", () => {
+    test("mnemonics dir is under config dir", () => {
+      const configDir = getConfigDir();
+      const mnemonicsDir = getMnemonicsDir();
+
+      expect(mnemonicsDir.startsWith(configDir)).toBe(true);
+    });
+
+    test("data dir is under config dir", () => {
+      const configDir = getConfigDir();
+      const dataDir = getDataDir();
+
+      expect(dataDir.startsWith(configDir)).toBe(true);
+    });
+
+    test("wallet config is under config dir", () => {
+      const configDir = getConfigDir();
+      const walletConfig = getWalletConfigPath();
+
+      expect(walletConfig.startsWith(configDir)).toBe(true);
+    });
+  });
+});

tests/cli/rates-format.test.ts

@@ -0,0 +1,40 @@
+/// <reference types="node" />
+
+import { describe, expect, test } from "vitest";
+
+import { BaseRates } from "../../src/utils/rates/base-rates";
+
+/**
+ * Minimal concrete adapter used only for testing BaseRates helpers.
+ */
+class TestRatesAdapter extends BaseRates {
+  public async start(): Promise<void> {
+    return;
+  }
+
+  public async stop(): Promise<void> {
+    return;
+  }
+
+  public async listPairs(): Promise<Set<string>> {
+    return new Set(["USD/BCH", "DOGE/BCH"]);
+  }
+}
+
+describe("BaseRates.formatCurrency", () => {
+  test("formats ISO currency codes with Intl currency style", () => {
+    const rates = new TestRatesAdapter();
+    const formatted = rates.formatCurrency(12.5, "USD");
+
+    expect(formatted).toContain("$");
+    expect(formatted).toContain("12.50");
+  });
+
+  test("formats non-ISO symbols without throwing", () => {
+    const rates = new TestRatesAdapter();
+    const formatted = rates.formatCurrency(12.3456789, "DOGE");
+
+    expect(formatted).toContain("DOGE");
+    expect(formatted).toContain("12.3456789");
+  });
+});

tests/cli/settings.test.ts

@@ -0,0 +1,96 @@
+/// <reference types="node" />
+
+import { beforeEach, afterEach, describe, expect, test } from "vitest";
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { SettingsService } from "../../src/services/settings";
+
+/**
+ * Tests for SettingsService persistence and migration behavior.
+ */
+describe("SettingsService", () => {
+  let testDir: string;
+  let settingsPath: string;
+
+  beforeEach(() => {
+    testDir = mkdtempSync(join(tmpdir(), "xo-cli-settings-test-"));
+    settingsPath = join(testDir, ".wallet");
+  });
+
+  afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  test("returns defaults when settings file does not exist", () => {
+    const settings = new SettingsService(settingsPath);
+
+    expect(settings.getDefaultMnemonic()).toBeUndefined();
+    expect(settings.getCurrency()).toBe("USD");
+    expect(settings.getSettings()).toEqual({ currency: "USD" });
+    expect(existsSync(settingsPath)).toBe(false);
+  });
+
+  test("migrates legacy .wallet plaintext mnemonic to JSON", () => {
+    writeFileSync(settingsPath, "mnemonic-legacy", "utf8");
+
+    const settings = new SettingsService(settingsPath);
+
+    expect(settings.getDefaultMnemonic()).toBe("mnemonic-legacy");
+    expect(settings.getCurrency()).toBe("USD");
+
+    const persisted = JSON.parse(readFileSync(settingsPath, "utf8")) as {
+      "default-mnemonic"?: string;
+      currency: string;
+    };
+    expect(persisted).toEqual({
+      "default-mnemonic": "mnemonic-legacy",
+      currency: "USD",
+    });
+  });
+
+  test("normalizes and persists currency and default-mnemonic", () => {
+    const settings = new SettingsService(settingsPath);
+
+    settings.setDefaultMnemonic("  mnemonic-primary  ");
+    settings.setCurrency("aud");
+
+    expect(settings.getSettings()).toEqual({
+      "default-mnemonic": "mnemonic-primary",
+      currency: "AUD",
+    });
+
+    const persisted = JSON.parse(readFileSync(settingsPath, "utf8")) as {
+      "default-mnemonic"?: string;
+      currency: string;
+    };
+    expect(persisted).toEqual({
+      "default-mnemonic": "mnemonic-primary",
+      currency: "AUD",
+    });
+  });
+
+  test("emits settings-updated events on setting changes", () => {
+    const settings = new SettingsService(settingsPath);
+    const events: Array<{ key: string; value: string | undefined }> = [];
+
+    settings.on("settings-updated", (event) => {
+      events.push({ key: event.key, value: event.value });
+    });
+
+    settings.setCurrency("cad");
+    settings.setDefaultMnemonic("mnemonic-blue");
+
+    expect(events).toEqual([
+      { key: "currency", value: "CAD" },
+      { key: "default-mnemonic", value: "mnemonic-blue" },
+    ]);
+  });
+});