HartiiLabs docs

Guides

CLI guide 1: install and first wallet

By the end of this guide you will have the Hartii CLI (hartii) installed, a new encrypted wallet on your computer, and a health check that passes. You will not spend anything.

Who this is for: anyone comfortable typing a few commands in a terminal. No coding needed.

What you will need

  • Node.js 22 or newer (node --version should print v22 or higher).
  • A terminal (Terminal, PowerShell, Windows Terminal, or similar).
  • Later, a small amount of QUAI to fund the wallet. Not needed for this guide.

Step 1: install

bash
npm install -g https://hartiilabs.com/downloads/hartii-cli.tgz
hartii --version

The second command prints the installed CLI version; the current release is CLI 0.7.0 (it ships with Labs 1.75.0). The website has a separate Labs version. To try it once without installing, put npx -y https://hartiilabs.com/downloads/hartii-cli.tgz in front of any command instead of hartii.

The download's checksum is published next to it at https://hartiilabs.com/downloads/hartii-cli.tgz.sha256 if you want to verify the file.

Updating: run hartii update. From CLI 0.2.3 it checks for a newer version, asks, then downloads it, checks the file against the published checksum, installs it and shows the new version. From CLI 0.6.0 it also checks the release's signature (the download page publishes hartii-cli.tgz.sig) against a key built into the CLI, and refuses an unsigned or mismatched release. hartii update --check only tells you whether an update exists. On 0.2.2 or older, run the install command above once instead; after that, hartii update works. A browser or documentation update never updates the installed command.

CLI 0.7.0: security hardening. wallet export and wallet remove need a real terminal and always ask for your wallet password. Raising or clearing a spending cap needs a terminal confirmation. Update downloads are size-limited and the signature is checked before the file is opened. The new hartii verify-site command checks that hartiilabs.com serves the build Hartii signed; see Verify the website. Details: CLI reference.

Step 2: look around with demo data

bash
hartii ui --demo

This opens a full-screen terminal app filled with fixture data. It has no wallet, makes no wallet actions and can never sign anything, so it is a safe way to explore. Use the arrow keys to move, Tab to switch panes, ? for help and q to quit. Run without a real terminal (for example piped into a file), it prints one plain 80x24 frame instead.

Step 3: see every command

bash
hartii ?

You get the full command list in groups: Start here, Wallet, Look things up, Trade, Hartii tools, Setup, Agents. Ask for help on one command with hartii buy ? or hartii help buy. If you mistype a command, the CLI suggests the closest ones.

Step 4: create your wallet

bash
hartii

With no wallet yet, hartii opens a guided setup. (hartii init and hartii wallet new in a terminal run the same setup in plain prompts.) Nothing leaves your computer. The steps are:

  1. Create a new wallet, or import one. To import, you give a recovery phrase or a private key at a hidden prompt.
  2. Choose a password. At least 12 characters, typed twice, hidden as you type. It locks the wallet file on this computer. The CLI cannot recover it.
  3. Write down your recovery phrase. The 12 words appear once on a screen that is cleared when you continue. They are not saved or copied anywhere. Write them on paper, in order, and keep the paper offline.
  4. Prove you wrote them down. The CLI asks for 3 of the words, picked at random. If you are not ready, you can show the phrase again, or choose Back up later (you have to confirm that choice, and the CLI keeps a reminder).
  5. Spending caps (optional). Setup recommends a limit on how much one send, or one day of sends, can move: pick a preset, enter your own amounts or skip. Nothing is capped unless you choose it here or later with hartii config set limits.perTxQuai 25.
  6. Receive. You see your address and a QR code, and a "waiting for funds" screen that turns into "Received" when QUAI arrives. You can skip it and fund the wallet later.

If you chose Back up later, the home screen shows a banner: press B to do the backup check. In a plain terminal, hartii wallet export shows the phrase again after you type the wallet's name to confirm. Write the 12 words on paper and keep them offline.

An imported wallet skips steps 3 and 4. A wallet imported from a private key has no recovery phrase to back up.

Scripts and --json runs never show a recovery phrase: hartii wallet new with HARTII_PASSWORD set, or with no terminal, only creates the encrypted wallet (the 12-character minimum still applies). Back that wallet up with hartii wallet export.

Already have a wallet? Choose import in the setup, or use hartii wallet import mnemonic and hartii wallet import key, which ask for the phrase or key at a hidden prompt (or from piped input). Never put a secret on the command line.

Step 5: find your address

bash
hartii wallet address

It prints your Cyprus-1 Quai address, the address you send QUAI to. hartii whoami shows your wallet name, address and network together, and hartii wallet list shows every wallet on this computer.

Step 6: run the health check

bash
hartii doctor

Each line starts with PASS or a failure. The checks are rpc (can it reach the Quai node), chainId (is it mainnet, chain 9), keystorePerms (is your wallet file readable only by you), addressLedger, api (is hartiilabs.com up) and clockSkew (does your clock match the chain). All PASS means you are ready. On Windows, keystorePerms reports "not checked on this platform".

Safety

  • Your password protects the wallet file. The CLI cannot recover it. Your recovery phrase can rebuild the wallet on any machine.
  • The same password encrypts the CLI's private files (spending ledger, list of addresses you paid, contacts and the Constraint Desk journal), starting with your first send or contact.
  • Never paste a recovery phrase or private key into a chat, an AI agent, a website or a message. Nobody legitimate will ask for it.
  • Keys live only in the encrypted keystore (~/.hartii/keystore/). There is no telemetry. Network lookups are seen by the Quai RPC node (addresses, balances, your IP), by hartiilabs.com (token lookups, portfolio reads, the live feed) and by hartiibiome.com and hartiigallery.com (address and NFT lookups); see Who sees what.
  • Spending caps are yours to set. There are none by default. Setup recommends them; they stop mistakes, not malware.
  • Updates are signed. hartii update refuses a release whose signature does not match the key built into the CLI.
  • Use a dedicated wallet that holds only what you are happy to risk.

Common mistakes

ProblemFix
hartii: command not foundClose and reopen the terminal; make sure npm's global bin folder is on your PATH.
Unknown command "?"Older build. Reinstall with the command in Step 1.
Use at least 12 characters (you have N).Pick a longer password for a new wallet.
Wallet "..." already exists.Choose another name, for example hartii wallet new trading.
A doctor line fails on rpc or apiCheck your internet connection and retry, or pass --rpc <url> to use your own node.

Next

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.