Add readme for CLI
This commit is contained in:
234
src/cli/README.md
Normal file
234
src/cli/README.md
Normal file
@@ -0,0 +1,234 @@
|
|||||||
|
# XO CLI
|
||||||
|
|
||||||
|
Command-line interface for the XO Engine. Create wallets, manage templates, build invitations, sign transactions, and broadcast them to the Bitcoin Cash network.
|
||||||
|
|
||||||
|
## Getting Started
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Run any command via tsx from the cli/ directory
|
||||||
|
npx tsx src/cli/index.ts <command> [options]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Wallet Setup
|
||||||
|
|
||||||
|
Before using most commands you need a mnemonic wallet file.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Generate a new mnemonic and save it to a file
|
||||||
|
xo-cli mnemonic create
|
||||||
|
|
||||||
|
# Import an existing mnemonic seed phrase
|
||||||
|
xo-cli mnemonic import page pencil stock planet limb cluster assault speak off joke private pioneer
|
||||||
|
|
||||||
|
# List available mnemonic files in the current directory
|
||||||
|
xo-cli mnemonic list
|
||||||
|
```
|
||||||
|
|
||||||
|
Mnemonic files are stored in the working directory with the prefix `mnemonic-`.
|
||||||
|
|
||||||
|
### Wallet Persistence
|
||||||
|
|
||||||
|
The first time you pass `-m <file>`, the choice is saved to `.xo-cli-wallet`. Subsequent commands will use that wallet automatically so you can omit `-m`.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# First run — pass the wallet explicitly
|
||||||
|
xo-cli resource list -m mnemonic-nuclear
|
||||||
|
|
||||||
|
# All future runs remember the wallet
|
||||||
|
xo-cli resource list
|
||||||
|
```
|
||||||
|
|
||||||
|
To switch wallets, pass `-m` again with a different file.
|
||||||
|
|
||||||
|
## Global Options
|
||||||
|
|
||||||
|
| Flag | Description |
|
||||||
|
|---|---|
|
||||||
|
| `-m`, `--mnemonic-file <file>` | Mnemonic file to use (persisted after first use) |
|
||||||
|
| `-v`, `--verbose` | Show detailed debug output |
|
||||||
|
| `-h`, `--help` | Show help message |
|
||||||
|
|
||||||
|
## Commands
|
||||||
|
|
||||||
|
### `mnemonic` — Manage Wallet Files
|
||||||
|
|
||||||
|
```bash
|
||||||
|
xo-cli mnemonic create # Generate a new mnemonic
|
||||||
|
xo-cli mnemonic import <seed words...> # Import a mnemonic from seed words
|
||||||
|
xo-cli mnemonic list # List mnemonic files in cwd
|
||||||
|
```
|
||||||
|
|
||||||
|
**Options:**
|
||||||
|
- `-o <filename>` — Custom output filename for the mnemonic file.
|
||||||
|
|
||||||
|
### `template` — Manage Templates
|
||||||
|
|
||||||
|
```bash
|
||||||
|
xo-cli template import <template-file> # Import a template
|
||||||
|
xo-cli template list # List imported templates
|
||||||
|
xo-cli template list <category> <template-id> # List items in a category
|
||||||
|
xo-cli template inspect <category> <template-id> <field> # Inspect a specific field
|
||||||
|
xo-cli template set-default <template-file> <output-id> <role> # Set default locking params
|
||||||
|
```
|
||||||
|
|
||||||
|
**Categories:** `action`, `transaction`, `output`, `lockingscript`, `variable`
|
||||||
|
|
||||||
|
**Example — discover what a template offers:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
xo-cli template import p2pkh-template.json
|
||||||
|
xo-cli template list
|
||||||
|
xo-cli template list action <template-identifier>
|
||||||
|
```
|
||||||
|
|
||||||
|
### `resource` — Manage UTXOs
|
||||||
|
|
||||||
|
```bash
|
||||||
|
xo-cli resource list # List unreserved (spendable) UTXOs
|
||||||
|
xo-cli resource list reserved # List UTXOs reserved by invitations
|
||||||
|
xo-cli resource list all # List all UTXOs (reserved + unreserved)
|
||||||
|
xo-cli resource unreserve <txhash:vout> # Unreserve a specific UTXO
|
||||||
|
xo-cli resource unreserve-all # Unreserve all reserved UTXOs
|
||||||
|
```
|
||||||
|
|
||||||
|
Each UTXO is displayed as `<txhash>:<vout> <sats> <outputId> (height <n>)`.
|
||||||
|
|
||||||
|
### `receive` — Generate a Receiving Address
|
||||||
|
|
||||||
|
```bash
|
||||||
|
xo-cli receive <template-file> <output-identifier> [role-identifier]
|
||||||
|
```
|
||||||
|
|
||||||
|
Generates a single-use BCH cash address from a template. If the role is omitted, the first available role is used.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
xo-cli receive p2pkh-template.json receiveOutput receiver
|
||||||
|
```
|
||||||
|
|
||||||
|
### `invitation` — Build, Sign & Broadcast Transactions
|
||||||
|
|
||||||
|
This is the core command for sending funds. An invitation goes through these stages: **create** → **sign** → **broadcast**.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
xo-cli invitation create <template-file> <action-id> [options]
|
||||||
|
xo-cli invitation append <invitation-id> [options]
|
||||||
|
xo-cli invitation sign <invitation-id>
|
||||||
|
xo-cli invitation broadcast <invitation-id>
|
||||||
|
xo-cli invitation requirements <invitation-id>
|
||||||
|
xo-cli invitation import <invitation-file>
|
||||||
|
xo-cli invitation list
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Create / Append Options
|
||||||
|
|
||||||
|
| Flag | Description |
|
||||||
|
|---|---|
|
||||||
|
| `-var-<name> <value>` | Set a template variable (kebab-case → camelCase) |
|
||||||
|
| `--add-input <txhash:vout>` | Add UTXO input(s), comma-separated |
|
||||||
|
| `--add-output <id>` | Override output(s) — **omit to auto-discover from template** |
|
||||||
|
| `--auto-inputs` | Automatically select UTXOs to cover the required amount |
|
||||||
|
| `-role <role>` | Role identifier for variable scoping and bytecode generation |
|
||||||
|
| `--sign` | Auto-sign after all requirements are satisfied |
|
||||||
|
| `--broadcast` | Auto-broadcast after signing (implies `--sign`) |
|
||||||
|
|
||||||
|
When inputs are provided, a **change output is automatically added** if the input total exceeds the required amount + fee (500 sats). Change below the dust threshold (546 sats) is donated as fee.
|
||||||
|
|
||||||
|
Outputs are **auto-discovered from the template** when `--add-output` is omitted, so you typically don't need to specify them.
|
||||||
|
|
||||||
|
#### Variable Naming
|
||||||
|
|
||||||
|
Variable flags use kebab-case which maps to the template's camelCase identifiers:
|
||||||
|
|
||||||
|
```
|
||||||
|
-var-transferred-satoshis 4678 → transferredSatoshis = "4678"
|
||||||
|
-var-recipient-lockingscript <addr> → recipientLockingscript = "<addr>"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Full Send Flow
|
||||||
|
|
||||||
|
### One-Command Send (Recommended)
|
||||||
|
|
||||||
|
With `--broadcast`, the entire create → sign → broadcast flow happens in a single invocation:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. List UTXOs to pick an input
|
||||||
|
xo-cli resource list
|
||||||
|
|
||||||
|
# 2. Send in one shot
|
||||||
|
xo-cli invitation create p2pkh-template.json sendSatoshis \
|
||||||
|
-var-transferred-satoshis 4678 \
|
||||||
|
-var-recipient-lockingscript "bitcoincash:qz..." \
|
||||||
|
--add-input <txhash>:<vout> \
|
||||||
|
-role sender \
|
||||||
|
--broadcast
|
||||||
|
```
|
||||||
|
|
||||||
|
Output:
|
||||||
|
|
||||||
|
```
|
||||||
|
Invitation created: abc123.json (abc123)
|
||||||
|
Invitation signed: abc123
|
||||||
|
Transaction broadcast: <txid>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step-by-Step Send
|
||||||
|
|
||||||
|
For multi-party transactions or debugging, you can run each step separately:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Import template (only needed once)
|
||||||
|
xo-cli template import p2pkh-template.json
|
||||||
|
|
||||||
|
# 2. Check available UTXOs
|
||||||
|
xo-cli resource list
|
||||||
|
|
||||||
|
# 3. Create the invitation with variables and inputs
|
||||||
|
xo-cli invitation create p2pkh-template.json sendSatoshis \
|
||||||
|
-var-transferred-satoshis 4678 \
|
||||||
|
-var-recipient-lockingscript "bitcoincash:qz..." \
|
||||||
|
--add-input <txhash>:<vout> \
|
||||||
|
-role sender
|
||||||
|
|
||||||
|
# 4. Sign
|
||||||
|
xo-cli invitation sign <invitation-id>
|
||||||
|
|
||||||
|
# 5. Broadcast
|
||||||
|
xo-cli invitation broadcast <invitation-id>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Using Auto-Inputs
|
||||||
|
|
||||||
|
Instead of manually selecting UTXOs, let the CLI pick them:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
xo-cli invitation create p2pkh-template.json sendSatoshis \
|
||||||
|
-var-transferred-satoshis 4678 \
|
||||||
|
-var-recipient-lockingscript "bitcoincash:qz..." \
|
||||||
|
--auto-inputs \
|
||||||
|
-role sender \
|
||||||
|
--broadcast
|
||||||
|
```
|
||||||
|
|
||||||
|
## Shell Completions
|
||||||
|
|
||||||
|
Tab-completion is available for bash, zsh, and fish:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Bash
|
||||||
|
eval "$(xo-cli completions bash)"
|
||||||
|
|
||||||
|
# Zsh
|
||||||
|
eval "$(xo-cli completions zsh)"
|
||||||
|
|
||||||
|
# Fish
|
||||||
|
xo-cli completions fish | source
|
||||||
|
```
|
||||||
|
|
||||||
|
## File Conventions
|
||||||
|
|
||||||
|
| File/Pattern | Purpose |
|
||||||
|
|---|---|
|
||||||
|
| `mnemonic-*` | Wallet mnemonic files |
|
||||||
|
| `.xo-cli-wallet` | Persisted wallet selection |
|
||||||
|
| `*.json` | Invitation files (saved by create/append) |
|
||||||
|
| `*.db` | Engine database files |
|
||||||
Reference in New Issue
Block a user