Tests. Autocomplete. Few Fixes. Mocks for Electrum Service. Template-to-Json parser. Fix global paths. Use IO Dependency injection for logging from cli. Additional commands in CLI.
This commit is contained in:
@@ -2,112 +2,135 @@
|
||||
|
||||
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` | 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:
|
||||
|
||||
```bash
|
||||
# Run any command via tsx from the cli/ directory
|
||||
npx tsx src/cli/index.ts <command> [options]
|
||||
cd engine/cli
|
||||
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 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>`
|
||||
|
||||
```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
|
||||
## Global Options (`xo-cli`)
|
||||
|
||||
| Flag | Description |
|
||||
|---|---|
|
||||
| `-m`, `--mnemonic-file <file>` | Mnemonic file to use (persisted after first use) |
|
||||
| `-v`, `--verbose` | Show detailed debug output |
|
||||
| `-h`, `--help` | Show help message |
|
||||
|------|-------------|
|
||||
| `-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
|
||||
|
||||
```bash
|
||||
xo-cli mnemonic create # Generate a new mnemonic
|
||||
xo-cli mnemonic import <seed words...> # Import a mnemonic from seed words
|
||||
xo-cli mnemonic list # List mnemonic files in cwd
|
||||
xo-cli mnemonic create
|
||||
xo-cli mnemonic import <seed words...>
|
||||
xo-cli mnemonic list
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-o <filename>` — Custom output filename for the mnemonic file.
|
||||
|
||||
### `template` — Manage Templates
|
||||
|
||||
```bash
|
||||
xo-cli template import <template-file> # Import a template
|
||||
xo-cli template list # List imported templates
|
||||
xo-cli template list <category> <template-id> # List items in a category
|
||||
xo-cli template inspect <category> <template-id> <field> # Inspect a specific field
|
||||
xo-cli template set-default <template-file> <output-id> <role> # Set default locking params
|
||||
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`
|
||||
|
||||
**Example — discover what a template offers:**
|
||||
|
||||
```bash
|
||||
xo-cli template import p2pkh-template.json
|
||||
xo-cli template list
|
||||
xo-cli template list action <template-identifier>
|
||||
```
|
||||
Template paths are resolved relative to the **current working directory**.
|
||||
|
||||
### `resource` — Manage UTXOs
|
||||
|
||||
```bash
|
||||
xo-cli resource list # List unreserved (spendable) UTXOs
|
||||
xo-cli resource list reserved # List UTXOs reserved by invitations
|
||||
xo-cli resource list all # List all UTXOs (reserved + unreserved)
|
||||
xo-cli resource unreserve <txhash:vout> # Unreserve a specific UTXO
|
||||
xo-cli resource unreserve-all # Unreserve all reserved UTXOs
|
||||
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
|
||||
```
|
||||
|
||||
Each UTXO is displayed as `<txhash>:<vout> <sats> <outputId> (height <n>)`.
|
||||
|
||||
### `receive` — Generate a Receiving Address
|
||||
|
||||
```bash
|
||||
xo-cli receive <template-file> <output-identifier> [role-identifier]
|
||||
```
|
||||
|
||||
Generates a single-use BCH cash address from a template. If the role is omitted, the first available role is used.
|
||||
|
||||
```bash
|
||||
xo-cli receive p2pkh-template.json receiveOutput receiver
|
||||
```
|
||||
|
||||
### `invitation` — Build, Sign & Broadcast Transactions
|
||||
|
||||
This is the core command for sending funds. An invitation goes through these stages: **create** → **sign** → **broadcast**.
|
||||
### `invitation` — Build, Sign & Broadcast
|
||||
|
||||
```bash
|
||||
xo-cli invitation create <template-file> <action-id> [options]
|
||||
@@ -119,42 +142,24 @@ xo-cli invitation import <invitation-file>
|
||||
xo-cli invitation list
|
||||
```
|
||||
|
||||
#### Create / Append Options
|
||||
**Create / append options:**
|
||||
|
||||
| Flag | Description |
|
||||
|---|---|
|
||||
| `-var-<name> <value>` | Set a template variable (kebab-case → camelCase) |
|
||||
| `--add-input <txhash:vout>` | Add UTXO input(s), comma-separated |
|
||||
| `--add-output <id>` | Override output(s) — **omit to auto-discover from template** |
|
||||
| `--auto-inputs` | Automatically select UTXOs to cover the required amount |
|
||||
| `-role <role>` | Role identifier for variable scoping and bytecode generation |
|
||||
| `--sign` | Auto-sign after all requirements are satisfied |
|
||||
| `--broadcast` | Auto-broadcast after signing (implies `--sign`) |
|
||||
|------|-------------|
|
||||
| `-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`) |
|
||||
|
||||
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.
|
||||
|
||||
#### 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:
|
||||
### One-command send
|
||||
|
||||
```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 +168,25 @@ xo-cli invitation create p2pkh-template.json sendSatoshis \
|
||||
--broadcast
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
Invitation created: abc123.json (abc123)
|
||||
Invitation signed: abc123
|
||||
Transaction broadcast: <txid>
|
||||
```
|
||||
|
||||
### Step-by-Step Send
|
||||
|
||||
For multi-party transactions or debugging, you can run each step separately:
|
||||
### `xo-tui`
|
||||
|
||||
```bash
|
||||
# 1. Import template (only needed once)
|
||||
xo-cli template import p2pkh-template.json
|
||||
|
||||
# 2. Check available UTXOs
|
||||
xo-cli resource list
|
||||
|
||||
# 3. Create the invitation with variables and inputs
|
||||
xo-cli invitation create p2pkh-template.json sendSatoshis \
|
||||
-var-transferred-satoshis 4678 \
|
||||
-var-recipient-lockingscript "bitcoincash:qz..." \
|
||||
--add-input <txhash>:<vout> \
|
||||
-role sender
|
||||
|
||||
# 4. Sign
|
||||
xo-cli invitation sign <invitation-id>
|
||||
|
||||
# 5. Broadcast
|
||||
xo-cli invitation broadcast <invitation-id>
|
||||
xo-tui
|
||||
```
|
||||
|
||||
### Using Auto-Inputs
|
||||
|
||||
Instead of manually selecting UTXOs, let the CLI pick them:
|
||||
|
||||
```bash
|
||||
xo-cli invitation create p2pkh-template.json sendSatoshis \
|
||||
-var-transferred-satoshis 4678 \
|
||||
-var-recipient-lockingscript "bitcoincash:qz..." \
|
||||
--auto-inputs \
|
||||
-role sender \
|
||||
--broadcast
|
||||
```
|
||||
Launches the full-screen wallet UI; uses the same global data directory unless overridden by env vars.
|
||||
|
||||
## Shell Completions
|
||||
|
||||
Tab-completion is available for bash, zsh, and fish:
|
||||
|
||||
```bash
|
||||
# Bash
|
||||
eval "$(xo-cli completions bash)"
|
||||
|
||||
# Zsh
|
||||
eval "$(xo-cli completions zsh)"
|
||||
|
||||
# Fish
|
||||
xo-cli completions fish | source
|
||||
```
|
||||
|
||||
## File Conventions
|
||||
|
||||
| File/Pattern | Purpose |
|
||||
|---|---|
|
||||
| `mnemonic-*` | Wallet mnemonic files |
|
||||
| `.xo-cli-wallet` | Persisted wallet selection |
|
||||
| `*.json` | Invitation files (saved by create/append) |
|
||||
| `*.db` | Engine database files |
|
||||
| Location | Purpose |
|
||||
|----------|---------|
|
||||
| `~/.config/xo-cli/` | Global wallet state |
|
||||
| `./` (cwd) | Templates, invitation JSON, explicit paths |
|
||||
|
||||
Reference in New Issue
Block a user