xo-cli/src/cli/README.md

XO CLI

Command-line interface for the XO Engine. Create wallets, manage templates, build invitations, sign transactions, and broadcast them to the Bitcoin Cash network.

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	Last-used mnemonic reference (so -m can be omitted)

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:

cd engine/cli
npm install
npm run build
npm link
# xo-cli and xo-tui are now on your PATH

Development without linking:

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

# 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 mnemonic basenames (use with -m)
xo-cli mnemonic list

Options: -o <filename> — basename only; file is written under the global mnemonics directory.

Wallet Persistence

The first time you pass -m <name>, that reference is saved to ~/.config/xo-cli/.wallet. Later runs can omit -m.

Mnemonic resolution order:

1. Absolute path, if the file exists
2. Path relative to the current working directory
3. ~/.config/xo-cli/mnemonics/<basename>

xo-cli resource list -m mnemonic-nuclear
xo-cli resource list

Global Options (xo-cli)

Flag	Description
-m, --mnemonic-file <file>	Mnemonic file (basename, cwd-relative, or absolute)
-v, --verbose	Verbose output
-h, --help	Help

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

Commands

mnemonic — Manage Wallet Files

xo-cli mnemonic create
xo-cli mnemonic import <seed words...>
xo-cli mnemonic list

template — Manage Templates

xo-cli template import <template-file>
xo-cli template list
xo-cli template list <category> <template-id>
xo-cli template inspect <category> <template-id> <field>
xo-cli template set-default <template-file> <output-id> <role>

Categories: action, transaction, output, lockingscript, variable

Template paths are resolved relative to the current working directory.

resource — Manage UTXOs

xo-cli resource list
xo-cli resource list reserved
xo-cli resource list all
xo-cli resource unreserve <txhash:vout>
xo-cli resource unreserve-all

receive — Generate a Receiving Address

xo-cli receive <template-file> <output-identifier> [role-identifier]

invitation — Build, Sign & Broadcast

xo-cli invitation create <template-file> <action-id> [options]
xo-cli invitation append <invitation-id> [options]
xo-cli invitation sign <invitation-id>
xo-cli invitation broadcast <invitation-id>
xo-cli invitation requirements <invitation-id>
xo-cli invitation import <invitation-file>
xo-cli invitation list

Create / append options:

Flag	Description
-var-<name> <value>	Template variable
--add-input <txhash:vout>	Inputs (comma-separated)
--add-output <id>	Override outputs (omit to auto-discover)
--auto-inputs	Auto-select UTXOs
-role <role>	Role for variables / bytecode
--sign	Auto-sign when complete
--broadcast	Auto-broadcast (implies --sign)

Invitation JSON files from create / append are written to the current working directory.

One-command send

xo-cli resource list
xo-cli invitation create p2pkh-template.json sendSatoshis \
  -var-transferred-satoshis 4678 \
  -var-recipient-lockingscript "bitcoincash:qz..." \
  --add-input <txhash>:<vout> \
  -role sender \
  --broadcast

xo-tui

xo-tui

Launches the full-screen wallet UI; uses the same global data directory unless overridden by env vars.

Shell Completions

eval "$(xo-cli completions bash)"
eval "$(xo-cli completions zsh)"
xo-cli completions fish | source

File Conventions

Location	Purpose
~/.config/xo-cli/	Global wallet state
./ (cwd)	Templates, invitation JSON, explicit paths