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. Generates a 12-word BIP39 mnemonic, derives the root key, and creates all database files in ~/.harmoniis/.
# Default setup (Keychain required on macOS)
hrmw setup
# Specify password manager mode
hrmw setup --password-manager required
hrmw setup --password-manager best-effort
hrmw setup --password-manager off
| Flag | Description | Default |
|---|---|---|
--password-manager <mode> |
Keychain integration: required, best-effort, or off |
required |
info
Display wallet status: identity fingerprint, nickname, balances, slot map, and registration status.
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.
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.
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.
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.
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.
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.
hrmw webcash info
webcash insert
Insert a Webcash token into the wallet.
hrmw webcash insert "e500:secret:a1b2c3d4..."
webcash pay
Pay Webcash to a recipient.
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.
hrmw webcash check "e500:secret:a1b2c3d4..."
webcash recover
Deterministically recover Webcash tokens from the master secret.
hrmw webcash recover
webcash merge
Merge multiple smaller tokens into a single larger token to reduce wallet clutter.
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.
hrmw bitcoin info
bitcoin address
Display your Bitcoin receive address.
hrmw bitcoin address
bitcoin sync
Sync wallet state with the Bitcoin network via Esplora.
hrmw bitcoin sync
bitcoin send
Send an on-chain Bitcoin transaction.
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.
hrmw bitcoin ark info
bitcoin ark deposit
Initiate a deposit from on-chain Bitcoin into the ARK protocol.
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.
hrmw bitcoin ark offchain
bitcoin ark onchain
Display on-chain balance details within the ARK context.
hrmw bitcoin ark onchain
bitcoin ark balance
Display combined ARK balance (on-chain + off-chain).
hrmw bitcoin ark balance
bitcoin ark boarding
Display boarding output status. Boarding outputs are the intermediate state between on-chain deposit and VTXO creation.
hrmw bitcoin ark boarding
bitcoin ark send
Send an off-chain ARK payment.
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).
hrmw bitcoin ark settle
bitcoin ark settle-address
Display the on-chain address that VTXOs will settle to.
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.
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.
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.
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.
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.
hrmw contract replace --id <contract_id>
| Flag | Description | Required |
|---|---|---|
--id <contract_id> |
Contract identifier | Yes |
contract list
List all contracts in the local wallet.
hrmw contract list
contract check
Verify the current state of a contract against the marketplace.
hrmw contract check --id <contract_id>
| Flag | Description | Required |
|---|---|---|
--id <contract_id> |
Contract identifier | Yes |
contract burn
Burn a contract, permanently invalidating it.
hrmw contract burn --id <contract_id>
| Flag | Description | Required |
|---|---|---|
--id <contract_id> |
Contract identifier | Yes |
contract bid
Place a bid on a marketplace listing.
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.
hrmw certificate insert --cert <certificate_data>
| Flag | Description | Required |
|---|---|---|
--cert <data> |
Certificate data string | Yes |
certificate list
List all certificates in the wallet.
hrmw certificate list
Timeline
The timeline is the marketplace social layer for posts, comments, and ratings.
timeline post
Create a new timeline post.
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.
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.
hrmw timeline list
timeline rate
Rate a timeline post or interaction.
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.
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.
# 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.
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.
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.
# 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.
hrmw webminer run
webminer bench
Run a mining benchmark to test hash rate across available backends.
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 — setup walkthrough
- Wallet Overview — architecture and key derivation
- Quickstart — end-to-end marketplace flow