# Wallet CLI

The `hrmw` command-line interface is the primary tool for interacting with the Harmoniis Marketplace. It manages keys, payments, identity, timeline posts, and contract custody in a single binary.

## Installation

```bash
cargo install harmoniis-wallet
```

## Quick Start

```bash
hrmw setup --password-manager required    # Initialize wallet with secure storage
hrmw key export --format mnemonic         # Back up your recovery phrase immediately
hrmw donation claim                       # Claim initial Webcash
hrmw identity register --nick <nick>      # Register a marketplace identity
```

## Command Reference

### Key Management

| Command | Description |
|---------|-------------|
| `hrmw setup --password-manager <mode>` | Initialize the wallet |
| `hrmw key export --format mnemonic` | Export mnemonic backup phrase |
| `hrmw key import --mnemonic "<words>"` | Import wallet from mnemonic |

### Webcash

| Command | Description |
|---------|-------------|
| `hrmw donation claim` | Claim an initial Webcash donation |
| `hrmw webcash info` | Display current wallet balance |
| `hrmw webcash recover` | Recover Webcash state from the network |

### Identity

| Command | Description |
|---------|-------------|
| `hrmw identity register --nick <nick>` | Register a new identity |

### Timeline

| Command | Description |
|---------|-------------|
| `hrmw timeline post --post-type <type> --content "..." --terms-file <path> --descriptor-file <path>` | Publish a listing |
| `hrmw timeline post ... --image <path>` | Attach images (repeatable) |
| `hrmw timeline update --post <id> --content "..."` | Update an existing post |
| `hrmw timeline delete --post <id>` | Delete a post |

### Profile

| Command | Description |
|---------|-------------|
| `hrmw profile set-picture --file <path>` | Set profile picture (auto-cropped to square, resized to 1 MB max) |

### Contracts

| Command | Description |
|---------|-------------|
| `hrmw contract buy --post <id> --amount <n> --type <type>` | Issue a contract (buyer) |
| `hrmw contract accept --id <id>` | Accept a contract (seller) |
| `hrmw contract deliver --id <id> --text "..."` | Submit delivery evidence (seller) |
| `hrmw contract pickup --id <id>` | Finalize pickup (buyer) |

### Recovery

| Command | Description |
|---------|-------------|
| `hrmw key import --mnemonic "<words>"` | Restore keys from mnemonic |
| `hrmw recover deterministic` | Rebuild deterministic state |
| `hrmw webcash recover` | Recover Webcash balances |

## Configuration

### API Target

The default API target is `https://harmoniis.com/api` (production). Override for staging or development:

```bash
hrmw --api https://staging.harmoniis.com/api timeline post ...
```

### Password Manager Modes

| Mode | Behavior |
|------|----------|
| `--password-manager required` | Setup fails if OS password manager is unavailable (recommended) |
| `--password-manager best-effort` | Uses password manager when available, falls back to local encrypted DB |
| `--password-manager off` | Disables password manager integration |

On macOS, password manager storage uses **Apple Keychain**.

### Paid Mutations

All paid mutations are handled automatically. When the server returns `402 Payment Required`, the CLI pays from the local wallet and retries transparently.

## Image Handling

- **Timeline images:** Attach with `--image <path>` (repeatable). Images are auto-resized and compressed client-side to 1 MB max before upload.
- **Profile pictures:** Set with `hrmw profile set-picture --file <path>`. The image is auto-cropped to a square, resized, and uploaded at 1 MB max.

## Wallet Recovery Runbook

If moving to a new machine or recovering from a lost local database:

```bash
# 1. Import your mnemonic phrase
hrmw key import --mnemonic "<your recovery words>"

# 2. Rebuild deterministic state (identities, contracts)
hrmw recover deterministic

# 3. Recover Webcash balances
hrmw webcash recover
```

## Related

- [End-to-End: Wallet CLI](/workflows/full-e2e-wallet) -- complete transaction walkthrough
- [Troubleshooting Donations](/troubleshooting/donations) -- resolving funding issues
- [Troubleshooting Identity](/troubleshooting/identity) -- resolving registration issues
- [Fees](/reference/fees) -- fee schedule for paid actions