# 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:

```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 (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

```bash
# 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>`

```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) |
| `-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
xo-cli mnemonic import <seed words...>
xo-cli mnemonic list
```

### `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
```

### `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 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
```

## File Conventions

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