7.3 KiB
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 ${XO_CONFIG_DIR:-~/.config/xo-cli}, so you can run commands from any directory. Set XO_CONFIG_DIR to use a different wallet-state root.
| Path | Purpose |
|---|---|
$XO_CONFIG_DIR/mnemonics/ |
Mnemonic files (mnemonic-*) |
$XO_CONFIG_DIR/data/ |
Engine DB (xo-wallet.db) and invitation storage (xo-invitations.db) |
$XO_CONFIG_DIR/.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:
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
| Variable | Default |
|---|---|
XO_CONFIG_DIR |
~/.config/xo-cli |
SYNC_SERVER_URL |
http://localhost:3000 |
DB_PATH |
$XO_CONFIG_DIR/data |
DB_FILENAME |
xo-wallet.db |
INVITATION_STORAGE_PATH |
$XO_CONFIG_DIR/data/xo-invitations.db |
Use an absolute path for a custom root. Setting XO_CONFIG_DIR does not copy state from the default directory.
Getting Started
Wallet Setup
# Generate a new mnemonic (saved under $XO_CONFIG_DIR/mnemonics/)
xo-cli mnemonic create
# Import an existing mnemonic seed phrase
xo-cli mnemonic import oven crop same above under tower promote decrease vocal pretty require slow
# 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 as
default-mnemonic in $XO_CONFIG_DIR/.wallet. Later runs can omit -m.
currency controls the fiat unit used when showing BCH/sats conversions in the TUI.
Mnemonic resolution order:
- Absolute path, if the file exists
- Path relative to the current working directory
$XO_CONFIG_DIR/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) |
--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 |
Advanced: you can pass --database-path, --database-filename, and --invitation-storage-path to override the defaults under $XO_CONFIG_DIR/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
xo-cli mnemonic expose <mnemonic-file>
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
settings — Manage Persisted Settings
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
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 inspect <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
xo-cli completions <shell> --install adds a default XO_CONFIG_DIR assignment to the shell startup file if one is not already present. Mnemonic aliases are completed directly from $XO_CONFIG_DIR/mnemonics/; database-backed suggestions still use xo-complete.
File Conventions
| Location | Purpose |
|---|---|
$XO_CONFIG_DIR |
Global wallet state |
./ (cwd) |
Templates, invitation JSON, explicit paths |