HartiiLabs docs

HartiiLabs

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.

The CLI also includes hartii trader, a BETA personal trader that runs on your own computer in Observe or Paper mode. Live trading is not available. See Personal holder trader.

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. Verification includes the project's tests, synthetic signing/receipt tests, and read-only checks of the exported CLI package. Read-only or dry-run success does not prove funded execution; start with small amounts and --dry-run.

Install

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

bash
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 installed command; expected for this release: 0.7.0
hartii            # after a global install, this opens the full-screen UI (guided setup if you have no wallet yet)

Help is always one keystroke away: hartii ? (or hartii help), hartii buy ? for one command, and a mistyped command suggests the right one. hartii commands --json lists everything; hartii completion bash|zsh|fish|powershell prints shell completion.

Verify the download against the published checksum:

bash
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

The download page also publishes hartii-cli.tgz.sig, an ed25519 signature of the release. A checksum on its own only proves the file matches the number next to it, and both come from the same website. The signature is checked against a public key built into the CLI you already have, so a copied or tampered file cannot pass it. hartii update does this check for you (see Updating); a first install with npm install -g is not signature-checked, so compare the checksum above.

The website's Labs version and the CLI package version are separate. CLI 0.7.0 ships with Labs 1.75.0 (security hardening and hartii verify-site). CLI 0.6.1 shipped with Labs 1.74.1 (setup's "Waiting for funds" no longer misses a deposit that lands before its first balance check; the README now describes 0.6.0; hartii qi ? prints its example correctly). CLI 0.6.0 shipped with Labs 1.74.0 (guided setup, plainer sends, signed updates, Qi). CLI 0.5.0 shipped with Labs 1.66.0 and adds Constraint Desk / Fill Ledger. CLI 0.4.0 shipped with Labs 1.53.0 (CLI 0.3.3 with Labs 1.22.1, CLI 0.3.2 shipped with Labs 1.21.3, CLI 0.3.0 with Labs 1.21.0); a docs refresh or browser reload does not upgrade an installed command.

Updating

From 0.2.3 on, hartii update updates the CLI:

bash
hartii update          # check, ask, then download, verify the sha256 and install the newest version
hartii update --check  # only report: "You're on the latest version (x.y.z)" or "Update available: a → b"
hartii update --yes    # no prompt (needed when not in an interactive terminal; also with --json)

It reads the manifest https://hartiilabs.com/downloads/hartii-cli.json (version, sha256, url). It downloads the tarball to a temporary file, refuses to install unless its sha256 equals the published one, verifies the release's ed25519 signature (from the manifest or from hartii-cli.tgz.sig next to the download) against the Hartii release key built into the CLI, runs npm install -g on that verified file, and then confirms with the new hartii --version. An unsigned release, or one whose signature does not match the built-in key, is refused, and there is no flag to override that. The signing key itself is kept off the website. Only CLI 0.6.0 and newer check the signature, so the update that brings you to 0.6.0 is still checked by the older checksum rule; later updates are signature-checked. If npm fails, it prints the exact manual command; on macOS or Linux permission errors it adds a sudo / npm-prefix hint. The MCP server never updates anything. CLI 0.3.0 needs Node.js 22 or newer, so install Node.js 22 before you update.

On 0.2.2 or older? Those versions only printed the upgrade command. Run it once to get the new updater: npm install -g https://hartiilabs.com/downloads/hartii-cli.tgz, then check hartii --version. Release verification must check the actual archive and its adjacent checksum.

Quickstart

bash
hartii ui --demo               # look around on fixture data — no wallet, no network, never signs
hartii                         # no wallet yet: opens the guided setup (see "Guided first run")
hartii wallet new              # on a terminal, the same guided setup; in a script, a plain encrypted keystore
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 --demo --dry-run    # labelled fixture, no network or signing
hartii buy <token-address> 5 --dry-run  # replace the address, then review current live terms

Global flags: --json, --network mainnet|orchard, --rpc <url>, --wallet <name>, --yes, --dry-run, --demo, --key-env <VAR>, plus --details and --terse for how a send is shown and --new-recipient-ok for unattended sends (all below). 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.

Guided first run (CLI 0.6.0)

Run hartii with no wallet and the full-screen UI opens a setup instead of an empty dashboard. hartii init and hartii wallet new on a terminal run the same setup, in plain prompts. It takes a couple of minutes and nothing leaves your computer.

  1. Create or import. Create a new wallet, or import one from a recovery phrase or a private key (typed at a hidden prompt).
  2. Password. At least 12 characters, typed twice, with a strength hint. The password locks the wallet file on this computer and the CLI cannot recover it. Wallets you made earlier with a shorter password still unlock; the 12-character rule is for new wallets.
  3. Recovery phrase, shown once. A new wallet's 12 words appear on a screen that is cleared as soon as you move on (in a plain terminal, on the alternate screen, so they never stay in your scroll-back). They are not saved, logged or copied. Write them on paper, in order.
  4. Backup check. The CLI asks for 3 of the words, picked at random. If you got them wrong you can look at the phrase again. Or choose Back up later: you have to confirm it a second time, and the CLI then keeps a reminder.
  5. Spending caps (optional). Setup recommends them and lets you pick a preset (Conservative, Normal, Degen), enter your own amounts, or skip. See Spending caps.
  6. Receive. Your address and a QR code, then a "waiting for funds" screen that switches to "Received" when the balance goes up. You can skip it.

An imported wallet skips steps 3 and 4. A wallet imported from a private key has no recovery phrase, so it cannot be backed up this way (and cannot use Qi).

If you chose "Back up later", or quit before the check was done, the home screen keeps a banner: press B to do the backup check later. In a plain terminal, hartii wallet export shows the phrase after a typed confirmation.

Scripts are different on purpose. With --json, HARTII_PASSWORD, or no terminal attached, hartii wallet new stays non-interactive and never shows the recovery phrase. The 12-character minimum still applies to the new password. The guided setup refuses to run without an interactive terminal (and with TERM=dumb, which cannot hide the phrase afterwards).

Reviewing a send

Before anything is signed, the CLI shows a review. It starts with a plain sentence, for example "You send 2.5 QUAI to 0x00ab…12cd", then the network fee, the most that can leave your wallet in total, any warnings, and a line saying nothing is sent until you confirm (or, with --dry-run, that this is a preview and nothing is sent). The same review is used for buy, sell, swap, approve, Airdrop, OTC, Claim and the Wall.

bash
hartii send 0xRECIPIENT 2.5 --dry-run             # the plain review
hartii send 0xRECIPIENT 2.5 --dry-run --details   # adds the technical fields
hartii send 0xRECIPIENT 2.5 --terse               # the review on one line
hartii config set ui.terse true                  # make the one-line review the default
  • --details appends the technical block: chain, gas limit and price, fee estimate, what counts toward your limits, the call selector and data digest. --json output is unchanged: it carries the full summary.
  • --terse (or ui.terse true) shortens the review to one line with the fee and the number of warnings. --details wins if you pass both.
  • The full recipient address is always shown, also for a saved contact.

Warnings that never block

Some things deserve a loud warning but are still your call. These appear in the review and do not stop the transaction:

WarningWhen
Slippage above 10%You asked for more than 10% slippage on a buy, sell or swap.
Token chosen by nameYou typed a ticker instead of a token address. Tickers are not unique. Shown as a "Careful" note; check the address printed below it.
Fee bigger than the amountThe network fee is more than the value you are sending.
New recipientYou have never paid this address from this computer.
Look-alike addressThe address starts and ends with the same 4 characters as one of your contacts or an address you paid before, but it is a different address (a common scam).

The first four are shown as "Warning" in red when your terminal has colour. Every warning carries a word, so it reads the same with NO_COLOR.

New payee and contacts

A recipient you have never paid (a payment only counts once its receipt is confirmed) is marked NEW. Instead of a plain "Proceed? y/N", an interactive send asks you to type the last 4 characters of the address. A wrong answer cancels the send.

Unattended sends cannot type anything, so they must opt in on purpose:

bash
hartii send 0xNEWADDRESS 1 --yes --new-recipient-ok   # needs spending caps (below)

A look-alike address is never allowed unattended: with --yes it is refused, and you have to run it again at a terminal and check the address. Sending to a new recipient with no terminal and no --yes --new-recipient-ok also stops with an explanation. An AI agent (hartii mcp) can only send to addresses this computer has already paid: pay a new address once from the terminal first. The agent's dry run still works.

The contact book is a private file on your computer; names never leave it.

bash
hartii contacts add alice 0xADDRESS
hartii contacts list
hartii contacts rename alice alice-shop
hartii contacts remove alice-shop
hartii send alice 5          # resolves the saved name; the review still shows the full address

A contact name must not look like an address or a token ticker. Adding an address that looks like one you already know prints a warning. After a confirmed first payment on a terminal, the CLI offers to save the new recipient as a contact.

Spending caps: you choose them

There are no default spending caps. A fresh install has no per-transaction and no daily limit; setup only recommends them. Caps you set work as before (checked before anything is signed, and shared by the CLI, the full-screen UI and hartii mcp).

bash
hartii config set limits.perTxQuai 25    # most QUAI in one transaction
hartii config set limits.dailyQuai 100   # most QUAI per UTC day, including unconfirmed reservations
hartii config set limits.perTxQuai none  # remove a cap (also: off)
hartii limits                            # what is set, and today's spend

--yes only works when you have set at least one cap. It skips the review question, so without caps the CLI refuses it and tells you how to set one. Without --yes, you confirm every send by hand. hartii mcp --allow-writes still needs its own --max-per-tx and --max-per-day (or a --preset); see below.

These caps are stored in a plain config file. They stop mistakes and runaway scripts, not malware on your computer.

Encrypted local files

The CLI's private bookkeeping is encrypted with your wallet password: the spending ledger, the list of addresses you have paid, your contacts and the Constraint Desk journal. The encryption starts the first time a command that writes them runs with your password (for example your first send, or adding a contact); existing plain files are encrypted at that moment. A file that is plain text after that point is refused rather than trusted, so it cannot be swapped to reset your limits.

If you use several wallets with different passwords, let the second one open the same data once:

bash
hartii vault enroll <wallet>   # asks for a password that already opens the data, then the other wallet's password

The watchlist stays readable on purpose: it is only a list of public token references, and the dashboard reads it before a password could be asked. The wallet keystore was already encrypted. Replacing an encrypted file with an older encrypted copy is not detected.

Qi (BETA, Orchard first)

Qi is Quai's UTXO cash coin with reusable payment codes. hartii qi is BETA and is tried on the Orchard test network first.

bash
hartii qi address --network orchard                         # your payment code and a first free address, with a QR
hartii qi balance --network orchard                         # spendable, locked and total Qi
hartii qi notes --network orchard                           # the individual notes you hold
hartii qi receive --network orchard [--no-wait]             # show the code and wait for Qi to arrive
hartii qi send <payment-code|qi-address> 1 --network orchard --dry-run
  • A Qi wallet is derived from the recovery phrase of the selected wallet, so the wallet must have been created from a phrase. A wallet imported from a private key, or --key-env, cannot do Qi.
  • Share the payment code; it works many times and stays private. A plain Qi address is a one-off, and reusing one is less private.
  • A send review lists what leaves your wallet: the amount, the fee in Qi, the notes spent and the change. The first send to a payment code also posts a small on-chain notice, paid in QUAI from your Quai address.
  • The spending caps above are counted in Qi for Qi sends, and --yes needs them here too.
  • Mainnet Qi sends are not described as live. They are blocked unless you name the network on purpose and opt in: --network mainnet --allow-mainnet-qi. Even then the CLI prints a BETA warning to use very small amounts.
  • Verification so far: one Qi send on Orchard (2026-11-17) was confirmed.

Look and feel

The home screen of the full-screen UI is wallet-first: your balance, then Receive and Send as the two main actions, with trading (Buy, Sell, Swap) and Hartii tools (Airdrop, OTC, Claim, Wall) one step away. Violet is the accent; red is kept for danger.

  • HARTII_ASCII=1 forces plain ASCII characters. The CLI also switches to ASCII by itself on terminals that cannot draw the box and block characters (for example an older Windows console, a non-UTF-8 locale or TERM=dumb). HARTII_ASCII=0 forces Unicode.
  • HARTII_REDUCED_MOTION=1 turns off the animation.
  • NO_COLOR (any non-empty value) turns colour off; meaning is also carried by words, never by colour alone.

Who sees what

There is no analytics in the CLI. Looking things up needs the network, and these are the services that see something:

ServiceWhat it can see
The Quai RPC node you use (the default, or the one you pass with --rpc)Every address and balance you query, and your IP address.
hartiilabs.comTicker and token lookups, your address on portfolio reads, and the live trade feed connection.
hartiibiome.com and hartiigallery.comThe address and NFT lookups you ask for.

--dry-run and hartii ui --demo differ: a dry run still reads from these services, --demo reads nothing. Transactions are public on chain. Contacts, the paid list, the spending ledger and the journal stay on your computer.

Receive and send QUAI

bash
hartii receive                              # address + HPAY link + terminal QR; never unlocks
hartii receive --amount 2.5 --memo Coffee     # exact mainnet QUAI request
hartii receive --out payment.svg             # share or scan a locally generated SVG
hartii receive --address-qr                  # raw public-address QR for a wallet scanner
hartii wallet address --qr                   # the selected address as QR
hartii send 0xYOUR_CYPRUS1_QUAI_ADDRESS 2.5 --dry-run
hartii send "https://hartiipay.app/hpay?to=...&amt=...&chain=9&v=1" --dry-run
hartii tx pending                           # inspect local reservations; no signing

HPAY requests encode native QUAI in exact integer wei and target mainnet chain 9. They contain no private key or recovery phrase. Address QR codes do not identify a network: the payer must select the displayed network. On Orchard, use an explicit --address-qr; a mainnet HPAY request is refused. A large memo may need a wider terminal; SVG export preserves the complete QR.

The CLI accepts fixed-address HPAY links only from the approved HTTPS Hartii origins, with explicit chain/version, unambiguous fields, positive exact amounts and valid expiry. A conflicting supplied amount or token transfer is refused. @name links should be resolved in HPAY or regenerated as address links. Expiry is checked again before submission. Normal address sending uses the same simulation, confirmation, identity and spending checks. The TUI Actions menu includes Receive and Send.

In CLI 0.3.2, Receive immediately shows the complete public-address QR and separate address/paylink copy actions. Copy success requires a successful local clipboard setter; unsupported or blocked clipboard access is shown honestly. Closing the pane, changing wallet/network or quitting cancels pending copies. If the terminal cannot fit the QR and its quiet zone, resize as shown or use SVG export. Demo receiving never copies a funding address.

No transaction is sent by receiving, --demo or --dry-run. Review the full recipient, amount, network and maximum fee before approving a real write.

Commands

CommandWhat it does
hartii · hartii ui [--demo]Full-screen TUI (one plain 80×24 frame when piped)
wallet new · import mnemonic · import key · list · use · address · renameManage encrypted wallets; on a terminal wallet new runs the guided setup; imports read the phrase/key from a hidden prompt or stdin (never the command line), and nothing is printed back
wallet export / wallet removeTyped-wallet-name confirmation: export displays the key/phrase for backup; remove deletes the encrypted wallet. Neither confirmation is bypassed by --yes. Since 0.7.0 both need an interactive terminal, and export always asks for the wallet password at a hidden prompt.
balance [--tokens] [--address <addr>]QUAI and token holdings; --address reads any Quai address. With --tokens (and in portfolio) it also lists the NFTs the address holds, grouped by collection (CLI 0.4.0)
send <to|contact> <amount> [--token <addr|ticker>] [--details|--terse] [--yes --new-recipient-ok]QUAI or token transfer; amount as decimal, 50% or all. Plain-sentence review; --yes needs spending caps you set
contacts add|list|remove|renamePrivate local contact book
vault enroll <wallet>Let another wallet's password open the encrypted local files
qi address|balance|notes|receive|sendBETA Qi, Orchard first
tokens [trending|new|search <q>] · token <addr|ticker>Launchpad directory and one token's curve state, graduation progress, holders
buy <token> <quai> [--slippage 3] · sell <token> <amount|all|50%>Bonding-curve trades with on-chain quotes and a slippage floor
swap <in> <out> <amount>HartiiSwap router (QUAI/WQUAI wrap 1:1)
tx <hash> · tx pending · watch <token|all>Transaction status; live trade stream (NDJSON with --json)
airdrop --csv <file>Hartii Airdrop batches, up to 500 recipients per transaction
otc create|fill|cancel|listOTC Link offers (token for QUAI)
claim list · claim <campaignId> [--check]Hartii Claim — leaves re-verified against the on-chain Merkle root
`gallery search <name0x address>·gallery collection <address
studio rooms [query] · `studio open <collectionname> [tokenId] [--open]`
wall engrave "<msg>" · wall stats · wall recentWall of Blocks
config get|set · doctorSettings (network, currentWallet, ui.terse, optional spending caps limits.perTxQuai / limits.dailyQuai; none clears a cap) and a health check
verify-site [--json]Checks that hartiilabs.com serves exactly the build Hartii signed (CLI 0.7.0). See Verify the website
init · whoami · limits · networks · about · updateFirst-run setup (guided on a terminal when you have no wallet), your address, spending caps you set and today's spend, networks, version, signed self-update
price · quote buy|sell · holders · trades · gas · block · openRead-only lookups — no wallet needed
Shortcutsbal, pf, ls, use, addr, top, new, search, me
trader init|paper|run --observe|watch|status|pause|exportBETA personal trader. Observe and Paper only; see Personal holder trader
mcp [--allow-writes] [--preset conservative|normal|degen] [--max-per-tx <q>] [--max-per-day <q>]stdio MCP server

Constraint Desk and Fill Ledger (beta)

CLI 0.5.0 adds hartii desk: manually reviewed HartiiSwap decisions and a private local evidence report. It uses the existing swap engine and spending limits. It does not start the personal trader.

bash
hartii desk --demo                       # fixture only: no wallet, network or trading journal
hartii desk --demo --out desk-demo.html   # save an offline example; choose a new filename
hartii desk positions --address <Cyprus-1-Quai-address> --json
hartii desk preview QUAI <token-address> 1 --json
hartii desk swap QUAI <token-address> 1   # separately confirm each approval and swap
hartii desk journal --day 2026-11-12 --limit 25
hartii desk receipt <decision-id>         # observe evidence, never resend
hartii desk export --day 2026-11-12 --out session.html

Replace placeholders before running live reads. Positions show native QUAI and at most 200 indexed token holdings. An indexed mark is not a fresh execution quote; its observation time, historical lot basis and realized or unrealized P&L are unknown here. This is not a complete wallet inventory. Position JSON keeps the exact indexed mark in indexedValueWei and its formatted QUAI amount in indexedValueQuai. The portfolio API's field named valueQuai is also an integer wei string; the CLI balance table converts it before displaying QUAI. Missing or malformed Desk marks stay unknown; an actual zero remains zero. Offline balance fixtures use the same wei units as live API data.

Preview is a read-only preflight. If allowance is missing, only the approval is simulated: approval gas is not whole-swap gas. desk swap obtains fresh terms and requires native confirmation for each transaction; --yes is refused. Desk currently records supported exact-input swaps through the bundled HartiiSwap router, with approvals stored separately. It is not a comparison of every venue or a wrap/unwrap journal.

The reviewed transaction, its locally verified signed hash and a possible-broadcast marker are recorded separately. The operation is bounded to five minutes. Before broadcast, gas terms moving beyond 20%, a new estimate above the signed limit or a fresh quote below the reviewed minimum cause refusal. Original network, nonce, simulation, fee and spending checks still apply.

Only a receipt matching the captured authority and canonical block establishes an observed mined outcome. Receipt gas is separate from the reviewed fee ceiling. ERC-20 output requires matching transfer evidence and canonical pair provenance; transfer events do not prove every token's balance effects. Native proceeds, missing evidence and historical P&L stay unknown. A later observation can change after a reorganization. Reading a receipt does not clear the native spending reservation and never retries a transaction.

Records are local under ~/.hartii/desk/mainnet/<UTC-day>/. Journal, status and export default to today's UTC day; pass --day YYYY-MM-DD for an earlier day. A signed status records a local signature without a possible-broadcast marker. It is not evidence of submission or a mined outcome; read its evidence reason. Journal pages and exports select at most 100 decisions; use the returned nextCursor with --before to select another page. An export contains only that selection, not complete wallet history. HTML and JSON exports refuse an existing destination and are bounded to 8 MiB. The HTML report supports search, outcome filters, expandable evidence, theme switching and JSON download without automatic network requests. The selected records include public addresses and transaction data; share them deliberately. No signing key or wallet-unlock function is in the report.

Desk is available from the shell. It does not add an MCP write tool or grant an agent signing authority. Use hartii help desk to check the installed command set. No funded execution qualification is implied by the synthetic signing tests or read-only checks of this feature.

Personal holder trader (beta)

hartii trader runs a spot trader on your own computer. It reads Hartii markets, applies fixed rules and records every decision. It has two modes, Observe and Paper. Neither needs a private key. Neither sends a transaction.

bash
hartii trader paper --demo --once    # offline demo: no wallet, no network, no files
hartii trader init --owner <address> --create-wallet --capital <QUAI> --max-per-tx <QUAI> --max-per-day <QUAI> --max-fee <QUAI>
hartii trader paper --once           # one Paper cycle on real markets
hartii trader watch                  # latest snapshot, refreshes every 2 seconds

Rules, budgets, models, files and the dashboard are on Personal holder trader. A step-by-step version is in the guide.

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 → the complete reviewed transaction is signed locally and its canonical bytes and sender are verified → final chain, nonce and applicable expiry/review checks → one broadcast → success only when the receipt has the exact submitted transaction hash and canonical status 1, with the quaiscan link. --dry-run stops after the summary. Since 0.6.0 the summary is a plain-sentence review with warnings; a new recipient also needs the last 4 characters typed.

  • Keystore: ~/.hartii/keystore/<name>.json, scrypt keystore v3, file mode 0600 where the OS supports it. New wallets need a password of at least 12 characters. Password from a hidden prompt or HARTII_PASSWORD; --key-env (raw key from an env var, for CI) prints a warning.
  • Spending guard: optional per-transaction and daily limits that you set (there are no defaults), shared by the CLI, TUI and MCP. Token-denominated writes are valued in QUAI from a live quote and refused if no valuation exists while a cap is set. See Spending caps.
  • Every mined transaction charges gas, including a revert returned in a receipt or carried by an SDK submission/wait error. A mined revert charges its gas rather than the reverted transfer value. Success charges the guarded value plus gas. The receipt fee is preferred, then receipt gas usage and price; incomplete fee data uses conservative signed gas terms. The daily cap can therefore stop repeated reverted transactions before another signing attempt.
  • Uncertain outcomes keep reservations: a local failure before broadcast, or a recognized node admission rejection tied to the exact signed raw transaction, releases its allowance. An error code alone does not. A timeout, unknown submission or missing/non-final receipt keeps the reserved allowance and any recorded hash, including across UTC day changes. Check the chain before retrying; no automatic resend is performed. A later mined outcome is settled against its gas cost.
  • Unsafe local storage stops writes: the spending ledger is validated, reservations are persisted before the signer is called, and a home-wide exclusive lock prevents concurrent ledger writes. Unreadable/damaged state or a failed storage operation cannot reset the limits or authorize another send. The CLI never automatically removes a stale lock.
  • Untrusted text is sanitised: token names, symbols and wall messages lose control, bidirectional and zero-width characters before they reach your terminal or an agent.
  • Fee ceiling: a transaction whose estimated network fee exceeds max(25 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.

Pending recovery and local limits

Use hartii tx <hash> or the transaction's explorer link to establish its receipt status before retrying an uncertain write. If a process stopped while holding the spending lock, first stop all writers, inspect its pending reservations and reconcile their hashes/receipts. Repair the ledger or remove the stale lock only after that review. Deleting pending state or starting a different local profile can discard this accident-prevention history; it does not prove that an earlier transaction was cancelled.

CLI 0.2.2 computes the transaction hash from its verified signed bytes before broadcasting. If the node receives the transaction but the response is lost, that local hash remains available in the error and hartii tx pending, and the allowance stays reserved. pending or not found from one read does not prove the transaction cannot still land. Do not submit a replacement, remove the reservation or change profiles to get around the block. A status read does not automatically reconcile the local reservation.

If you have set spending caps, they are local caps, not an on-chain vault restriction. Editing configuration/state, using a different CLI home or signing through another client can bypass them. Protect the local profile and use an Agent Terminal vault when on-chain limits are required.

MCP server for AI agents

bash
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, the Gallery and Studio reads hartii_studio_rooms, hartii_studio_link, hartii_gallery_search, hartii_gallery_collection, hartii_gallery_item and hartii_gallery_trending (CLI 0.4.0), and the three local trader reads hartii_trader_status, hartii_trader_limits and hartii_trader_activity). 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 or a --preset (they can only tighten your configured caps). Presets: conservative 10 QUAI per tx, 50 per day, 1% max slippage; normal 50 / 250 / 2%; degen 250 / 1000 / 5%. Explicit caps may only lower a preset, and a preset alone does not enable writes. The slippage ceiling applies to MCP buy/sell/swap: stated slippage above it is rejected, unstated defaults to the lower of 3% and the ceiling. hartii trader init --preset ... applies the same per-tx and per-day caps to the local trader, defaults to conservative when no preset is given, and sets its slippage protection: the preset's bps (100 / 200 / 500; --slippage-bps <n> may only lower it) is the on-chain minimum-out of every trader buy and sell, clamped to the owner-signed policy ceiling (100 bps today, so normal and degen clamp to 1% for the trader). A breach before send skips the trade and logs a slippage_skip; it is never retried looser. 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).

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

From CLI 0.3.0, every result carries a structured copy (structuredContent) and the same JSON as text. A _hartii block names the authority (read-only, or reviewed-wallet when writes are on), the mode (read-only, dry-run or live), the chain and the zone. The mode describes the call. It does not prove a transaction was sent or confirmed. A failed call sets isError and returns {"error":{"code":"TOOL_ERROR","message":"..."},"retryable":false}. Unknown input fields are rejected. The three trader tools read the local profile named default and cannot start, pause or change the trader.

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.

Signed agent requests and replay state

The local stdio MCP server uses the CLI's local spending ledger; it does not require a remote D1 database for every CLI transaction. Separately, HartiiLabs' signed agent API binds authorization to the verified signer and exact canonical intent, including action, vault, parameters and timestamp. Equivalent textual signature encodings do not make a used intent fresh. Acceptance requires an atomic durable replay claim; a missing, failed or uncertain storage claim refuses authorization rather than permitting a write.

Funded agent workers also coordinate shared signer and vault authority durably. An unresolved invocation is not unlocked just because a lease expired or a caller restarted. Those server protections and their reconciliation procedures are separate from the CLI's local file lock. Existing session tokens and any historically exposed credentials are not revoked or rotated merely by installing these code changes.

Privacy and storage

The CLI stores encrypted keystores, selected wallet/network settings, any spending caps you set, public wallet addresses, spending totals, pending reservations and recorded transaction hashes in its local profile. From 0.6.0 the spending ledger, paid list, contacts and Constraint Desk journal are encrypted with your wallet password (see Encrypted local files). For which services see which lookups, read Who sees what. File modes restrict access where the OS supports them; protect that profile using your operating system's account and filesystem permissions. Removing local files cannot erase public-chain transactions.

Live and dry-run commands contact the configured RPC and relevant Hartii APIs. Those services see the requested public addresses/market data and normal connection metadata, including the requester's IP. --dry-run avoids signing and broadcasting; it does not make those network reads private. hartii ui --demo uses fixture data without a wallet or network reads. Wallet export is an explicit local disclosure; keep its output out of logs, agent context and shared terminals.

When an AI client uses stdio MCP, it receives the command/tool outputs and may retain them under its own policies. The CLI cannot guarantee that an external agent, RPC, hosting service or model provider collects nothing. Server replay records can retain a digest and expiry instead of the original signed text or credential; this does not erase separate session/message retention or public on-chain data.

Local unresolved reservations block further sends by the same signer and chain, including after restart or a new UTC day. Legacy records with missing chain metadata block every chain. hartii tx pending exposes public metadata only and never deletes reservations or unlocks a spending lock. A successful read does not reconcile an unknown submission. Other apps or separate profiles do not share this local guard.

Secret argv imports (--from-arg) are refused. Use the hidden prompt or stdin. MCP write access requires the bare --allow-writes flag plus valid caps; values such as --allow-writes=no do not opt in.

CLI 0.3.4 Boolean safety

Boolean options are bare switches. Use --dry-run, --demo, --yes or --allow-writes; omit the switch to disable it. Forms such as --dry-run=true, --demo=false and --allow-writes=true are rejected before command, TUI or MCP dispatch. They never silently turn into a different Boolean value. Value options still accept their documented value forms, including --network=mainnet.

Parser failures exit 1, keep JSON/MCP stdout clean and do not echo the supplied inline value. This is input-safety proof from synthetic process and package tests; it is not funded-wallet or transaction proof.

CLI 0.2.1 hardening

Verified against the 0.2.1 release changelog and tests (synthetic wallets and RPC fixtures; no funded mainnet rehearsal):

  • Gas and reservations: an "all balance" send/buy/swap reserves gas from the real transaction shape, and a recognized admission rejection releases its spend reservation. CLI 0.2.2 narrows this to errors bound to the exact locally signed raw transaction; other submission errors stay pending. --key-env dry runs resolve the same sender as the real run.
  • Clean output: all console messages go to stderr, so --json and MCP stdout stay machine-readable. Text from the network or a token is passed through a terminal-text sanitizer before it is shown.
  • TUI confirmation shows the entire summary (scrolling if needed) or refuses to proceed.
  • MCP writes need a one-use reviewToken from the matching dry run, and the terms are re-checked before signing.
  • Secret prompts: a non-interactive session refuses to ask for a password or key unless HARTII_PASSWORD is set or --stdin is used.
  • receive --expires accepts only 30m, 2h or 7d style values, at most 365 days.
  • otc and claim lists paginate instead of stopping at the first page.
  • An http:// RPC URL is refused unless --allow-insecure-rpc is given and the host is localhost.

CLI 0.2.2 buy reliability

CLI 0.2.2 addresses reproduced synthetic failures in the actual CLI command and signing path:

  • Reviewed terms stay exact. The CLI signs a complete transaction locally, including a reviewed nonce of zero, and compares the decoded signed transaction with the reviewed canonical transaction before sending. It rechecks chain, pending nonce and any payment expiry or MCP review immediately before one broadcast. A changed term requires a fresh review; the CLI does not silently repopulate the transaction or resend it.
  • Cyprus-1 fee reads. The SDK fee request supplies Zone.Cyprus1. The existing raw gas-price fallback uses the same configured RPC; fee ceilings and spending caps still apply.
  • Balance-based buys leave gas. buy <token> all, 100% and other percentages, such as 90%, estimate the buy with its access list. If amount plus gas exceeds the balance, the CLI reduces the amount, requotes and checks gas again. Preparation is bounded; unstable terms or a balance too low for gas stop the buy. Read the final quaiIn, minimum output and maximum fee rather than assuming the typed percentage is the final amount. Decimal amounts still require enough QUAI for the amount plus gas.
  • Unknown broadcast keeps its hash. A lost or mismatched response retains the locally computed signed hash and reservation. Use the pending recovery procedure.

Coverage uses synthetic wallets, the pinned quais signing implementation and fake RPC responses. It does not prove funded mainnet execution or that every reported customer failure has been reproduced.

CLI 0.3.0: personal trader and MCP results

  • Node.js 22 or newer. The package declares node >=22.
  • hartii trader (BETA). A personal spot trader with Observe and Paper modes. Both run without a private key and never send a transaction. The Live commands stay blocked, and the HBOME access registry is proposed, not deployed. See Personal holder trader.
  • Three trader read tools in hartii mcp. hartii_trader_status, hartii_trader_limits and hartii_trader_activity are read-only. By default the server now registers 13 read tools. With --allow-writes and both caps it registers 20.
  • Structured MCP results. Results include structuredContent, an outputSchema and read/write annotations on each tool. Errors now return a JSON object with isError set. Before 0.3.0 they returned text that began with "Error:". Unknown input fields are rejected.
  • Windows updates. hartii update accepts a Windows profile or temp path that contains a short-name tilde.

Verification of the trader uses synthetic wallets and fixtures. No funded rehearsal has been performed.

CLI 0.3.2: wallet reliability and scripting repairs

  • First-use SDK response. The pinned SDK's numeric nonce-zero response is restored from the byte-verified signed transaction only after its hash matches. Actual changed identity and uncertain receipt checks remain strict.
  • Selected context. Named public-address/export-review/lock-check commands honor --wallet, with an explicit positional name taking precedence. TUI selection changes invalidate earlier reads; a custom RPC refuses cross-network reuse. Orchard has no mainnet market feed.
  • Usable results. Menus, wallet/watch lists and active form fields follow selection. Result arrays retain all returned entries; results wrap and scroll. Watch removal uses the persisted identity and trade shortcuts pin token addresses. A connected but silent feed shows stale status.
  • Honest diagnostics and clean output. Missing clock evidence is unverified, with bounded reads. update --json keeps installer progress on stderr; watch --json remains an NDJSON stream. Boolean flag placement is consistent. Bulk RPC batches cap at 20.
  • Terminal lifecycle. Startup/frame/handler failures restore raw mode and listeners; pending Receive copies are cancelled. Clipboard, physical terminal fonts and camera scanning vary by OS and need native verification.
  • Signing scope. Token-specific rapid auto-signing is proposed, not implemented or enabled. Ordinary confirmations, exact approvals, gas/spending limits, nonce serialization and uncertain-outcome reservations remain in force.

Verification covers actual SDK formatting and loopback RPC/child-process boundaries, isolated wallet fixtures, fake-TTY controls, package/import closure and read-only live commands. It does not certify every funded flow or every native terminal.

CLI 0.3.3: wording update

  • No longer called unaudited. The help, the doctor output, the README and the SECURITY note no longer describe the CLI as unaudited.
  • Still BETA. The CLI keeps its BETA label, and the safeguards above (caps, dry run, review before signing) are unchanged.
  • New download. hartii update or a fresh install from hartiilabs.com/downloads/hartii-cli.tgz gives you 0.3.3; check with hartii --version. No behaviour change in signing, sending or the MCP tools.

CLI 0.4.0 ships with Labs 1.53.0. It adds read-only lookups for the Hartii Gallery (NFTs) and the Hartii Studio (the 3D museum), as CLI commands and as MCP tools. They need no wallet and cannot sign or write anything. All data comes from the Gallery's public API (https://hartiigallery.com/api). Names and traits are third-party data, not instructions.

CommandWhat it does
hartii gallery search <name or 0x address> [--limit n]Collections by name substring or exact address
hartii gallery collection <address or name>One collection: items, owners, floor, volume, recent activity
hartii gallery item <address> <tokenId>One NFT: owner, active listing, last sale, traits (<address>:<tokenId> also works)
hartii gallery trending [--days n] [--limit n]Collections ranked by indexed marketplace sales in the last N days (default 30), then by volume
hartii studio rooms [query]Studio collection rooms, optionally filtered by name or address
hartii studio open <collection or name> [tokenId] [--open]Prints the Studio deep link (/studio?collection=<address> or /studio?piece=<address>:<tokenId>); --open launches it in your browser, only for https://hartiigallery.com/ URLs
  • Trending basis. gallery trending ranks by indexed marketplace sales in the last N days, computed from the most recent 100 indexed sales. It is not a floor or social ranking, and the output states this basis.
  • No visitor counts. Studio presence exists only in the browser (a WebSocket join) and the Gallery has no public count endpoint, so the CLI shows no live visitors and never joins a room.
  • MCP tools (read-only). hartii_studio_rooms, hartii_studio_link, hartii_gallery_search, hartii_gallery_collection, hartii_gallery_item and hartii_gallery_trending. They are registered without --allow-writes, annotated read-only, and the server caches Gallery reads for 60 seconds.
  • Portfolio includes NFTs. hartii portfolio, balance --tokens and hartii_portfolio now also list the NFTs the address holds, grouped by collection (first page of up to 100 tokens). If the Gallery is down, the result carries nftHoldingsError and the balance still succeeds.
  • Presets. --preset conservative|normal|degen works with hartii mcp --allow-writes and hartii trader init (see above).
  • --demo has no Gallery fixtures; run these commands without it.

CLI 0.6.0: guided setup, plainer sends and Qi

CLI 0.6.0 (BETA) ships with Labs 1.74.0. It keeps the signing engine and adds a safer, friendlier surface around it.

  • Guided first run. hartii with no wallet, hartii init and hartii wallet new on a terminal run one setup: create or import, a 12-character minimum password, the recovery phrase shown once on a screen that is cleared, a 3-word backup check (or "Back up later" with a reminder and the B key), an optional spending-cap step and a receive screen that waits for funds. Scripts and --json stay non-interactive and never show the phrase.
  • No default spending caps. The old 100 QUAI per transaction and 500 QUAI per day defaults are gone. Caps apply only if you set them (hartii config set limits.perTxQuai <n>, limits.dailyQuai <n>, none clears). --yes works only when a cap is set.
  • Plain-sentence send review, --details for the technical fields, --terse / ui.terse for one line.
  • Warnings that never block: slippage above 10%, a token chosen by ticker, a fee bigger than the amount, a new recipient, a look-alike address.
  • New payee needs the last 4 characters typed; unattended needs --yes --new-recipient-ok; a look-alike address is never allowed unattended.
  • Contacts: hartii contacts add|list|remove|rename and hartii send <name> <amount>.
  • Encrypted local files (spending ledger, paid list, contacts, desk journal) with your wallet password; hartii vault enroll <wallet>. The watchlist stays readable.
  • Signed updates. hartii update verifies an ed25519 signature against the key built into the CLI and refuses unsigned or mismatched releases.
  • hartii qi (BETA, Orchard first): address, balance, notes, receive and send to a payment code or a Qi address. Mainnet Qi sends need --network mainnet --allow-mainnet-qi and are not live.
  • New look: wallet-first home, ASCII fallback (HARTII_ASCII=1), reduced motion (HARTII_REDUCED_MOTION=1), NO_COLOR.
  • Who sees what is now written down: see Who sees what. Lookups behave as before.
  • The MCP server gains no new write tools; hartii mcp --allow-writes still needs its own caps or a preset.

Verification of 0.6.0 uses the package tests and one confirmed Qi send on Orchard (2026-11-17). It does not establish funded mainnet execution. The CLI stays BETA until an independent review and 30 days of our own real use.

CLI 0.7.0: security hardening

CLI 0.7.0 (BETA) ships with Labs 1.75.0. It comes from a security review in which every finding was reproduced by a test before it was fixed. It adds no new write tools. What changed for you:

  • Exporting or removing a wallet needs a terminal. wallet export and wallet remove refuse to run without an interactive terminal. Export always asks for the wallet password at a hidden prompt: HARTII_PASSWORD, --key-env and piped input no longer unlock it. wallet remove also drops that wallet's slot in the local encrypted-files vault. The last slot is retired rather than deleted, so your data stays reachable, and hartii vault enroll guides you to re-enrol.
  • Loosening or clearing a spending cap needs a terminal. hartii config set limits.perTxQuai or limits.dailyQuai to a higher value, or to none, asks for a yes on a real terminal and refuses in a script or pipe. Lowering a cap, or setting one where none existed, still works anywhere.
  • MCP swaps are limited to verified tokens. hartii_swap in hartii mcp accepts QUAI, WQUAI and tokens that a bundled Hartii launch factory registered. Any other token address is refused. hartii swap in a terminal is unchanged.
  • The Qi payment notice goes through the normal write checks. When a payment-code send announces itself with a QUAI transaction, that transaction now gets the same chain check, simulation, access list, 25 QUAI fee ceiling, spend-ledger entry and write lock as any other send.
  • The Qi address ledger is sealed with the same local vault as the spending ledger, and reads as locked when no password is available. A plain ledger is sealed when the vault is created.
  • Wrong checksums are refused. A mixed-case Quai or Qi address with an invalid checksum is refused; an all-lowercase address is accepted and shown checksummed. A Qi cap with more than 3 decimals is an error, never treated as "no cap".
  • Look-alike addresses need the differing characters. When an address starts and ends like one you already know, typing the last 4 characters proves nothing. The CLI now asks for the 6 characters where the two addresses first differ. A look-alike address is never sent unattended.
  • Update downloads are limited. hartii update caps the download at 50 MB while streaming and the unpacked archive at 200 MB, and checks the release signature before the archive is parsed when the manifest names the version.
  • Stronger vault key. New vault slots use scrypt N=2^17. A vault asking for more than N=2^18 is refused as tampered, and older slots are re-wrapped at the next unlock.
  • hartii verify-site checks the live website against its signed build. See below.

hartii verify-site

bash
hartii verify-site          # a short pass/fail report
hartii verify-site --json   # { ok, version, commit, keyId, checked, failures }

It talks only to https://hartiilabs.com (a fixed origin, no redirects) and checks:

  1. The signed build manifest at /.well-known/hartii-build.json and its signature /.well-known/hartii-build.json.sig. The ed25519 signature is verified with the web release key, id a17f68595150dac6.
  2. Every listed file that is not an HTML page, fetched live, has the signed sha256.
  3. The home page / references only scripts and styles that are in the signed manifest.

The web release key is built into the CLI, which itself ships as a signed release, so the check does not rely on a key that the website supplies. It reports a mismatch; it does not fix one. Limits: manifest 2 MB, signature 1 KB, 25 MB per file. The exit code is 0 only when every check passes and 1 on any failure. What the check does and does not cover is described in Verify the website.

What the caps protect, and what they do not

  • MCP caps are a real control. The caps of hartii mcp --allow-writes come from the operator's launch flags and can only tighten yours. Every write needs a dry run and a review token, and the server has no export, config or update tool.
  • A shell with the wallet password is full access. Any process that can run hartii with HARTII_PASSWORD or --key-env in its environment has the same access to that wallet as you. Caps and typed checks stop mistakes and a hijacked agent on MCP; they do not stop a script you gave the password to. Do not put HARTII_PASSWORD into an AI agent's shell.

Verification: the package tests, including a test that fails if any module outside the reviewed write paths signs or broadcasts. The CLI stays BETA.

Quai Network mainnet · chain 9 · Cyprus-1. Figures marked "read on" a date were read from the chain that day; re-read before relying on them.