Hartii CLI (hartii) is a terminal wallet and trading terminal for Quai Network (Cyprus-1). One engine, three ways in:

1. TUI — run hartii: a full-screen, arrow-key terminal UI with the live block height, a 32-block trade ribbon, balances, a watchlist and live trades per block.
2. Scripts — every command has a stable --json output for pipelines and bots.
3. MCP server — hartii mcp lets AI coding agents (Claude Code, Cursor) read markets and balances and, only when you explicitly allow it, trade under caps you set.

It is wired to Hartii's own products: HartiiLabs bonding curves, HartiiSwap, Airdrop, OTC Link, Claim and the Wall of Blocks, plus the live trade feed. Beta (0.1.0): covered by the project's own mocked-RPC tests and a review, not an independent audit — start with small amounts. No telemetry.

#Install

Node 20 or newer. No npm registry needed — the package is served from hartiilabs.com:

npx -y https://hartiilabs.com/downloads/hartii-cli.tgz --help
# or install the command globally
npm install -g https://hartiilabs.com/downloads/hartii-cli.tgz
hartii --version

Verify the download against the published checksum:

curl -sO https://hartiilabs.com/downloads/hartii-cli.tgz
curl -s https://hartiilabs.com/downloads/hartii-cli.tgz.sha256
sha256sum hartii-cli.tgz          # PowerShell: Get-FileHash hartii-cli.tgz -Algorithm SHA256

#Quickstart

hartii ui --demo               # look around on fixture data — no wallet, no network, never signs
hartii wallet new              # encrypted keystore (password prompt), selected automatically
hartii doctor                  # RPC, chain id, keystore permissions, API, clock skew
hartii balance --tokens        # QUAI plus HartiiLabs-indexed holdings valued in QUAI
hartii tokens trending
hartii buy DEMO 5 --dry-run    # exact simulated summary, signs nothing
hartii buy DEMO 5              # same summary, then y/N, then send

Global flags: --json, --network mainnet|orchard, --rpc <url>, --wallet <name>, --yes, --dry-run, --demo, --key-env <VAR>. Mainnet is chain 9 (https://rpc.quai.network/cyprus1); Orchard is chain 15000. The chain id is verified before every write. Market and tool commands (tokens, buy, sell, swap, watch, airdrop, otc, claim, wall) are mainnet-only.

#Commands

#How every write is protected

Addresses are validated (Quai ledger only, checksummed on mainnet) → spending guard → the transaction is simulated from your own address → a Quai access list is attached → gas = estimate × 1.2 at the live gas price → you see a confirmation summary (action, amounts, fees, gas cost, destination, network) → y/N → send → success only when the receipt status is 1, with the quaiscan link. --dry-run stops after the summary.

• Keystore: ~/.hartii/keystore/<name>.json, scrypt keystore v3, file mode 0600 where the OS supports it. Password from a hidden prompt or HARTII_PASSWORD; --key-env (raw key from an env var, for CI) prints a warning.
• Spending guard: per-transaction (default 100 QUAI) and daily (default 500 QUAI) limits, shared by the CLI, TUI and MCP. Token-denominated writes are valued in QUAI from a live quote and refused if no valuation exists.
• Fee ceiling: a transaction whose estimated network fee exceeds max(1 QUAI, 5% of the value moved) is refused unless you pass --max-fee; the fee counts toward the spending guard.
• Chain pinned: every transaction carries the expected chain id and is refused if the RPC reports a different one.
• Approvals are for the exact amount, never unlimited. Curves are verified on-chain as deployed by a HartiiLabs factory before any send or approval.
• Tool contracts (Airdrop, OTC, Claim): the addresses bundled in the CLI are authoritative. If hartiibiome.com/live-addresses.json disagrees, the command is refused with "update the CLI".
• Summaries show the token address next to every symbol, so a look-alike token cannot pass as another.

#MCP server for AI agents

hartii mcp                                              # read-only
hartii mcp --allow-writes --max-per-tx 5 --max-per-day 20

Read tools are always on (wallet, balance, portfolio, trending, token, quote, tx status, OTC list, claim eligibility, wall stats). Write tools (send, buy, sell, swap, OTC fill/cancel, claim) are registered only with --allow-writes, which also requires --max-per-tx and --max-per-day (they can only tighten your configured caps). Every write is a dry run unless the call passes confirm: true; writes take token addresses, not tickers; slippage is capped at 10%; and an agent can never raise the fee ceiling or trust unverified addresses. Signing needs HARTII_PASSWORD in the server's environment (stdio is the protocol channel, so there is no prompt).

claude mcp add hartii -- npx -y https://hartiilabs.com/downloads/hartii-cli.tgz mcp

Token names, symbols and wall messages are third-party text and are passed to the model as data. Give an agent write access only to a wallet holding what you are willing to let it spend. For an on-chain, capped vault an agent trades from instead of your own key, see the Agent Terminal.