# CLI Reference

Complete command reference for the Harmoniis Wallet (`hrmw`). All commands operate on the wallet database stored in `~/.harmoniis/` by default.

## Global Flags

These flags can be used with any command:

| Flag | Description | Default |
|------|-------------|---------|
| `--wallet <path>` | Override the wallet data directory | `~/.harmoniis/` |
| `--api <url>` | Override the marketplace API endpoint | Production server |
| `--direct` | Bypass the marketplace API and interact directly with the protocol | Off |
| `--payment-rail <rail>` | Force a specific payment rail (`webcash` or `bitcoin`) | Auto-detect |
| `--bitcoin-secret <secret>` | Provide Bitcoin payment secret inline | Prompt |

---

## Setup and Info

### `setup`

Initialize a new wallet or update settings on an existing one. On first run, generates a 12-word BIP39 mnemonic, derives the root key, and creates all database files in `~/.harmoniis/`.

Re-running on an existing wallet is safe (idempotent) — it shows current wallet state and applies setting changes without destroying key material, contracts, or identities.

```bash
# First-time setup (creates wallet, stores credentials)
hrmw setup

# Specify password manager mode
hrmw setup --password-manager required
hrmw setup --password-manager best-effort
hrmw setup --password-manager off

# Change password manager on existing wallet
hrmw setup --password-manager off        # remove from OS credential store
hrmw setup --password-manager required   # (re-)store in OS credential store
```

| Flag | Description | Default |
|------|-------------|---------|
| `--password-manager <mode>` | OS credential store: `required`, `best-effort`, or `off` | `required` |
| `--secret <hex>` | Import BIP39 entropy hex (first run only) | Generate new |

Credential stores: macOS Keychain, Linux Secret Service, Windows Credential Manager.

After switching to `off`, back up your master key: `hrmw key export --format mnemonic`.

### `info`

Display wallet status: identity fingerprint, nickname, balances, slot map, and registration status.

```bash
hrmw info
```

---

## Identity

Identity keys are Ed25519 signing keypairs derived from slot family 4 (legacy-named "PGP"). The wallet supports up to 1000 keys (index 0 through 999).

### `identity register`

Register your active identity key on the marketplace server.

```bash
hrmw identity register --nick satoshi
```

| Flag | Description | Required |
|------|-------------|----------|
| `--nick <name>` | Marketplace nickname | Yes |

### `identity pgp-list`

List all identity keys with their labels, fingerprints, and active status.

```bash
hrmw identity pgp-list
```

Example output:

```
Index  Label          Fingerprint                                                      Active
0      default        a1b2c3d4e5f6...                                                  *
1      alt-identity   f6e5d4c3b2a1...
```

### `identity pgp-new`

Derive a new Ed25519 identity key at the next available slot index.

```bash
hrmw identity pgp-new --label "trading-key"
```

| Flag | Description | Required |
|------|-------------|----------|
| `--label <name>` | Human-readable label for the key | Yes |

### `identity pgp-use`

Switch the active identity key by label.

```bash
hrmw identity pgp-use --label "trading-key"
```

| Flag | Description | Required |
|------|-------------|----------|
| `--label <name>` | Label of the key to activate | Yes |

---

## Donation

### `donation claim`

Claim the one-time free Webcash donation for new identities.

```bash
hrmw donation claim
```

---

## Webcash

Webcash is a bearer e-cash system. Tokens have the format `e{amount}:secret:{hex}`.

### `webcash info`

Display current Webcash balance.

```bash
hrmw webcash info
```

### `webcash insert`

Insert a Webcash token into the wallet.

```bash
hrmw webcash insert "e500:secret:a1b2c3d4..."
```

### `webcash pay`

Pay Webcash to a recipient.

```bash
hrmw webcash pay --amount 100 --to "e100:secret:recipient_hex..."
```

| Flag | Description | Required |
|------|-------------|----------|
| `--amount <wats>` | Amount in wats to pay | Yes |
| `--to <target>` | Recipient token or address | Yes |

### `webcash check`

Verify the validity and balance of a Webcash token.

```bash
hrmw webcash check "e500:secret:a1b2c3d4..."
```

### `webcash recover`

Deterministically recover Webcash tokens from the master secret.

```bash
hrmw webcash recover
```

### `webcash merge`

Merge multiple smaller tokens into a single larger token to reduce wallet clutter.

```bash
hrmw webcash merge
```

---

## Bitcoin (On-chain)

The Bitcoin wallet derives from the root key at bitcoin[0] slot (family 3). Primary address type is Taproot (BIP86) with SegWit (BIP84) fallback. Balances and UTXOs sync via Esplora.

### `bitcoin info`

Display Bitcoin wallet status: balance, address type, and UTXO count.

```bash
hrmw bitcoin info
```

### `bitcoin address`

Display your Bitcoin receive address.

```bash
hrmw bitcoin address
```

### `bitcoin sync`

Sync wallet state with the Bitcoin network via Esplora.

```bash
hrmw bitcoin sync
```

### `bitcoin send`

Send an on-chain Bitcoin transaction.

```bash
hrmw bitcoin send --to bc1q... --amount 50000
```

| Flag | Description | Required |
|------|-------------|----------|
| `--to <address>` | Destination Bitcoin address | Yes |
| `--amount <sats>` | Amount in satoshis | Yes |

---

## Bitcoin ARK (Off-chain)

ARK is an off-chain Bitcoin payment protocol using VTXOs via an Arkade ASP (default: `https://arkade.computer`). Payment proof format: `ark:{vtxo_txid}:{amount_sats}`.

### `bitcoin ark info`

Display ARK wallet status and ASP connection.

```bash
hrmw bitcoin ark info
```

### `bitcoin ark deposit`

Initiate a deposit from on-chain Bitcoin into the ARK protocol.

```bash
hrmw bitcoin ark deposit --amount 100000
```

| Flag | Description | Required |
|------|-------------|----------|
| `--amount <sats>` | Amount in satoshis to deposit | Yes |

### `bitcoin ark offchain`

Display off-chain (VTXO) balance details.

```bash
hrmw bitcoin ark offchain
```

### `bitcoin ark onchain`

Display on-chain balance details within the ARK context.

```bash
hrmw bitcoin ark onchain
```

### `bitcoin ark balance`

Display combined ARK balance (on-chain + off-chain).

```bash
hrmw bitcoin ark balance
```

### `bitcoin ark boarding`

Display boarding output status. Boarding outputs are the intermediate state between on-chain deposit and VTXO creation.

```bash
hrmw bitcoin ark boarding
```

### `bitcoin ark send`

Send an off-chain ARK payment.

```bash
hrmw bitcoin ark send --to <recipient> --amount 5000
```

| Flag | Description | Required |
|------|-------------|----------|
| `--to <recipient>` | Recipient ARK address or identity | Yes |
| `--amount <sats>` | Amount in satoshis | Yes |

### `bitcoin ark settle`

Settle VTXOs back to on-chain Bitcoin (unilateral exit from ARK).

```bash
hrmw bitcoin ark settle
```

### `bitcoin ark settle-address`

Display the on-chain address that VTXOs will settle to.

```bash
hrmw bitcoin ark settle-address
```

---

## Contracts

RGB21 bearer contracts with ZKP witness commitments. Envelope encryption uses X25519 + ChaCha20-Poly1305.

Contract types: `Service`, `ProductDigital`, `ProductPhysical`

Status lifecycle: `Issued` -> `Active` -> `Delivered` -> `Burned` or `Refunded`

### `contract buy`

Initiate a contract purchase on a marketplace listing.

```bash
hrmw contract buy --listing <listing_id>
```

| Flag | Description | Required |
|------|-------------|----------|
| `--listing <id>` | Marketplace listing ID | Yes |

### `contract insert`

Insert a contract into the local wallet database.

```bash
hrmw contract insert --contract "n:contract_id:secret:hex64..."
```

| Flag | Description | Required |
|------|-------------|----------|
| `--contract <witness>` | WitnessSecret string | Yes |

### `contract accept`

Accept a contract as the seller, transitioning it from Issued to Active.

```bash
hrmw contract accept --id <contract_id>
```

| Flag | Description | Required |
|------|-------------|----------|
| `--id <contract_id>` | Contract identifier | Yes |

### `contract deliver`

Deliver work or goods for an active contract, transitioning it to Delivered.

```bash
hrmw contract deliver --id <contract_id>
```

| Flag | Description | Required |
|------|-------------|----------|
| `--id <contract_id>` | Contract identifier | Yes |

### `contract replace`

Rotate the witness state of a contract. The old secret is invalidated and a new WitnessSecret is generated.

```bash
hrmw contract replace --id <contract_id>
```

| Flag | Description | Required |
|------|-------------|----------|
| `--id <contract_id>` | Contract identifier | Yes |

### `contract list`

List all contracts in the local wallet.

```bash
hrmw contract list
```

### `contract check`

Verify the current state of a contract against the marketplace.

```bash
hrmw contract check --id <contract_id>
```

| Flag | Description | Required |
|------|-------------|----------|
| `--id <contract_id>` | Contract identifier | Yes |

### `contract burn`

Burn a contract, permanently invalidating it.

```bash
hrmw contract burn --id <contract_id>
```

| Flag | Description | Required |
|------|-------------|----------|
| `--id <contract_id>` | Contract identifier | Yes |

### `contract bid`

Place a bid on a marketplace listing.

```bash
hrmw contract bid --listing <listing_id> --amount 1000
```

| Flag | Description | Required |
|------|-------------|----------|
| `--listing <id>` | Marketplace listing ID | Yes |
| `--amount <value>` | Bid amount | Yes |

---

## Certificates

### `certificate insert`

Insert a certificate into the local wallet.

```bash
hrmw certificate insert --cert <certificate_data>
```

| Flag | Description | Required |
|------|-------------|----------|
| `--cert <data>` | Certificate data string | Yes |

### `certificate list`

List all certificates in the wallet.

```bash
hrmw certificate list
```

---

## Timeline

The timeline is the marketplace social layer for posts, comments, and ratings.

### `timeline post`

Create a new timeline post.

```bash
hrmw timeline post --content "Offering web development services"
```

| Flag | Description | Required |
|------|-------------|----------|
| `--content <text>` | Post content | Yes |

### `timeline comment`

Add a comment to a timeline post.

```bash
hrmw timeline comment --post <post_id> --content "Interested in this offer"
```

| Flag | Description | Required |
|------|-------------|----------|
| `--post <id>` | Target post ID | Yes |
| `--content <text>` | Comment content | Yes |

### `timeline list`

List timeline posts.

```bash
hrmw timeline list
```

### `timeline rate`

Rate a timeline post or interaction.

```bash
hrmw timeline rate --post <post_id> --score 5
```

| Flag | Description | Required |
|------|-------------|----------|
| `--post <id>` | Target post ID | Yes |
| `--score <n>` | Rating score | Yes |

---

## Profile

### `profile update`

Update your marketplace profile information.

```bash
hrmw profile update --bio "Rust developer and Bitcoin enthusiast"
```

| Flag | Description | Required |
|------|-------------|----------|
| `--bio <text>` | Profile biography text | No |

---

## Keys

### `key export`

Export the master key in mnemonic or hex format.

```bash
# Export as 12-word mnemonic
hrmw key export --format mnemonic

# Export as raw hex entropy
hrmw key export --format hex
```

| Flag | Description | Required |
|------|-------------|----------|
| `--format <fmt>` | Export format: `mnemonic` or `hex` | Yes |

### `key import`

Import a master key from a mnemonic backup. This overwrites the existing wallet.

```bash
hrmw key import --mnemonic "word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12" --force
```

| Flag | Description | Required |
|------|-------------|----------|
| `--mnemonic <words>` | 12-word BIP39 mnemonic | Yes |
| `--force` | Confirm overwrite of existing wallet | Yes |

### `key fingerprint`

Display the fingerprint (64-char public key hex) of the active identity key.

```bash
hrmw key fingerprint
```

---

## Recovery

### `recover deterministic`

Re-derive all keys from the master mnemonic. Scans the specified range of PGP slot indices to recover identity keys.

```bash
# Recover all possible keys (full scan)
hrmw recover deterministic --pgp-start 0 --pgp-end 999

# Recover a specific range
hrmw recover deterministic --pgp-start 0 --pgp-end 10
```

| Flag | Description | Required |
|------|-------------|----------|
| `--pgp-start <n>` | Starting PGP slot index | Yes |
| `--pgp-end <n>` | Ending PGP slot index (inclusive) | Yes |

---

## Mining

The built-in miner uses SHA256 midstate optimization with a NonceTable grid (1000x1000 = 1M combinations). Backend auto-detection order: CUDA (Linux), Vulkan/wgpu, CPU (rayon parallel).

### `webminer run`

Start the Proof-of-Work miner. Accepted keeps are inserted with replace semantics.

```bash
hrmw webminer run
```

### `webminer bench`

Run a mining benchmark to test hash rate across available backends.

```bash
hrmw webminer bench
```

---

## Command Quick Reference

| Group | Commands |
|-------|----------|
| **Setup** | `setup`, `info` |
| **Identity** | `identity register`, `identity pgp-list`, `identity pgp-new`, `identity pgp-use` |
| **Donation** | `donation claim` |
| **Webcash** | `webcash info`, `webcash insert`, `webcash pay`, `webcash check`, `webcash recover`, `webcash merge` |
| **Bitcoin** | `bitcoin info`, `bitcoin address`, `bitcoin sync`, `bitcoin send` |
| **Bitcoin ARK** | `bitcoin ark info`, `bitcoin ark deposit`, `bitcoin ark offchain`, `bitcoin ark onchain`, `bitcoin ark balance`, `bitcoin ark boarding`, `bitcoin ark send`, `bitcoin ark settle`, `bitcoin ark settle-address` |
| **Contracts** | `contract buy`, `contract insert`, `contract accept`, `contract deliver`, `contract replace`, `contract list`, `contract check`, `contract burn`, `contract bid` |
| **Certificates** | `certificate insert`, `certificate list` |
| **Timeline** | `timeline post`, `timeline comment`, `timeline list`, `timeline rate` |
| **Profile** | `profile update` |
| **Keys** | `key export`, `key import`, `key fingerprint` |
| **Recovery** | `recover deterministic` |
| **Mining** | `webminer run`, `webminer bench` |

---

## Default Paths

| Path | Contents |
|------|----------|
| `~/.harmoniis/master.db` | Root key entropy, mnemonic, identity registry, wallet slots, nickname |
| `~/.harmoniis/rgb.db` | Contracts, certificates, timeline posts, comments, bids |
| `~/.harmoniis/webcash.db` | Webcash balance state |
| `~/.harmoniis/bitcoin.db` | Bitcoin/ARK wallet state, boarding outputs |
| `~/.harmoniis/miner.log` | Mining activity log |
| `~/.harmoniis/miner_status.json` | Miner status and statistics |
| `~/.harmoniis/miner_pending_keeps.log` | Pending mined keeps |

## Next Steps

- [Installation](/docs/wallet/installation) — setup walkthrough
- [Wallet Overview](/docs/wallet/overview) — architecture and key derivation
- [Quickstart](/docs/quickstart) — end-to-end marketplace flow