215 lines
7.3 KiB
Markdown
215 lines
7.3 KiB
Markdown
# 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:
|
||
|
||
```bash
|
||
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
|
||
|
||
| Variable | Default |
|
||
| ------------------------- | --------------------------------------- |
|
||
| `XO_CONFIG_DIR` | `~/.config/xo-cli` |
|
||
| `SYNC_SERVER_URL` | `https://v2.sync.xo.harvmaster.com` |
|
||
| `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
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
1. Absolute path, if the file exists
|
||
2. Path relative to the current working directory
|
||
3. `$XO_CONFIG_DIR/mnemonics/<basename>`
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
xo-cli mnemonic create
|
||
xo-cli mnemonic import <seed words...>
|
||
xo-cli mnemonic list
|
||
xo-cli mnemonic expose <mnemonic-file>
|
||
```
|
||
|
||
### `template` — Manage Templates
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```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
|
||
|
||
```bash
|
||
xo-cli receive <template-file> <output-identifier> [role-identifier]
|
||
```
|
||
|
||
### `invitation` — Build, 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 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
|
||
|
||
```bash
|
||
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`
|
||
|
||
```bash
|
||
xo-tui
|
||
```
|
||
|
||
Launches the full-screen wallet UI; uses the same global data directory unless overridden by env vars.
|
||
|
||
## Shell Completions
|
||
|
||
```bash
|
||
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 |
|