How to use heso.

Any one of them will fetch the wheel from PyPI, drop the heso binary on your PATH, and expose the same Python API. uv tool installis the recommended path — fast, isolated, and won't collide with system Python.

• uvuv tool install heso
  recommendedcopy →
• pipxpipx install heso
  copy →
• pippip install heso
  copy →

The npm package @ixla/heso bundles the same binary and exposes a TypeScript / JavaScript API. npx works without installing — useful for a one-off call from a script.

• npmnpm install -g @ixla/heso
  copy →
• npxnpx @ixla/heso open https://example.com
  one-shot, no installcopy →

If you'd rather avoid a package manager, grab the zip straight from the latest release. The PowerShell snippet below downloads, extracts, and leaves heso.exe in the current directory.

$ powershell -c "irm https://github.com/blank3rs/heso/releases/latest/download/heso.zip -OutFile heso.zip; Expand-Archive heso.zip -DestinationPath ."

You need a stable Rust toolchain (1.80+). cargo install fetches the crate, builds, and drops heso on your PATH.

$ cargo install --git https://github.com/blank3rs/heso heso-cli

Or clone the repo and build in place — the release artifact lands in target/release/heso.

$ git clone https://github.com/blank3rs/heso
$ cd heso
$ cargo build --release -p heso-cli

If a version prints, you're ready for chapter 02. If not, the error in your terminal is the place to start — missing toolchain, missing build dependency, or a stale$PATH.

$ heso --version

readfetches the URL, runs the page's JavaScript in a sandboxed engine, and writes one JSON object to stdout. Redirect it to a file:

$ heso read https://example.com > page.json

What you just wrote to page.json looks something like this (trimmed for clarity):

{
  "url":          "https://example.com",
  "title":        "Example Domain",
  "text":         "Example Domain. This domain is for use in…",
  "actions": [
    { "ref": "@e0", "role": "link", "name": "More information",
      "href": "https://www.iana.org/domains/example" }
  ],
  "forms":        [],
  "cookies":      [],
  "console":      [],
  "framework":    null,
  "content_hash": "abf42bb66917095eb4cafdd4deb00c068…",
  "lazy_hints":   [],
  "partial":      false
}

Read top to bottom — the order is roughly how often you'll touch each one.

title · textWhat a human reads

The page title and the rendered visible text after scripts have run. Everything else is for the agent.

actionsClickable / fillable elements

Each has a stable @ref (@e0, @e1, …) you can pass to click, fill, or submit. Refs survive across actions on the same page.

formsForm schemas

One entry per form: inputs with their refs, the submit ref. Use it to plan a fill+submit without re-reading the page.

cookies · consoleSide effects heso captured

Cookies the page set, anything it logged to console.* — useful when scripts misbehave.

framework"next" | "react" | "vue" | null

heso's best guess at the rendering stack. null when it can't tell.

content_hashFingerprint of what came back

Pass it next call as --since <hash> and heso returns a delta describing what changed (actions_added, actions_removed, forms_changed, text_changed, title_changed).

lazy_hints["infinite_scroll", "load_more_button", …]

Non-empty when heso thinks more content is hiding. Re-run with --complete to loop "fire pending observers → click load-more → wait for DOM to settle" until the page stops changing.

partialfalse on a clean run

Combined with --best-effort, becomes true plus a partial_reason and failed_scripts list when scripts crash, waits time out, fetches fail, or parsing breaks — instead of a non-zero exit.

Two flags come up often enough that they belong in chapter 02 rather than chapter 03. The first turns crashes into structured output; the second prevents the crash in the first place.

--best-effortExit 0 on partial failures

On open / read / wait. Output gains partial: true, partial_reason ("script_crash" | "wait_timeout" | "fetch_failed" | "parse_error"), and failed_scripts: [...]. Your agent decides what to try next instead of dying on a non-zero exit.

--inject-scriptShim a missing global before page scripts run

Takes inline JS or @file.js. Use it when sibling scripts cascade — the canonical case is a page where script A reads window.lunr that script B was supposed to set. Inject the stub, the cascade resolves, the page works.

The rest of the docs is the catalogue of verbs (chapter 03), how to script them from your agent (chapter 04), four common flows (chapter 05), and the one knob heso has for reproducible output (chapter 06).

Discover content. The five verbs that take a URL or a query and return JSON without changing the world.

$ heso search "rust web scraping" --limit 5
{ "query": "rust web scraping",
  "results": [ { "title": "…", "url": "…", "snippet": "…" }, … ] }

$ heso open https://example.com
{ "title": "Example Domain",
  "headings": [ … ],
  "actions": [ { "ref": "@e0", "role": "link", "name": "More information" } ] }

$ heso read https://nextjs.org/
{ "title": "…", "text": "…", "actions": [ … ], "forms": [ … ],
  "cookies": [ … ], "console": [ … ], "framework": "next",
  "content_hash": "abf42b…", "lazy_hints": [], "partial": false }

$ heso batch read u1 u2 u3 --parallel 3
{ "url": "u1", "title": "…", … }
{ "url": "u2", "title": "…", … }
{ "url": "u3", "title": "…", … }

$ heso wait https://app.example.com/ --selector-exists ".dashboard" --timeout 5s
{ "ok": true, "matched": ".dashboard", "elapsed_ms": 612 }

Drive interactions. Each verb dispatches real DOM events and returns a receipt of what changed.

$ heso click https://news.ycombinator.com --text "More"
{ "ok": true, "navigated": "/news?p=2",
  "content_hash": "c12e89…" }

$ heso fill https://example.com @e3 "hello"
{ "ok": true, "ref": "@e3", "value": "hello" }

$ heso submit https://example.com @e9
{ "ok": true, "navigated": "/results?q=…",
  "content_hash": "9a3b21…" }

$ heso navigate https://example.com/next
{ "ok": true, "url": "https://example.com/next" }

Run your own JavaScript. One verb fetches a page first, the other doesn't.

$ heso eval-dom https://example.com 'document.title'
"Example Domain"

$ heso eval-js --seed 42 'Math.random()'
0.5140492957650241

Plans, plats, and the edit/replay loop. A plan is a JSON array of canonical actions; a plat is an observation that embeds the plan it ran. plat_hash is BLAKE3 over RFC 8785 canonical JSON.

$ heso stamp plan.json > plat.json
# plat.json — the plan + the observation, hashed together.
# Exit 0 on a clean run; exit 1 with partial plat if a step failed.

$ heso replay plat.json
# step log on stdout: each verb, what changed, exit per step.

$ heso unpack plat.json > plan-again.json
[
  { "verb": "open",  "url": "https://news.ycombinator.com/" },
  { "verb": "click", "ref": "@e3" }
]

Ed25519 keypairs + signed receipts. Every open / read can emit a receipt; recipients verify against an allowlist of trusted pubkeys.

$ heso identity init
{ "path": "heso-local-data/identity.key",
  "public_key": "fdibx2…IE=", "algorithm": "Ed25519" }

$ heso receipt-verify --trusted-keys trusted.json receipt.json
OK fdibx2rLqGfrIf+duGbRKlM1iPwVSynHUq+nEisjwIE=
# exit 0 valid · 1 invalid · 2 missing or malformed

One long-running stateful session. Cookies, DOM mutations, listeners, history persist across calls.

$ heso serve
# stdin  ← { "jsonrpc": "2.0", "method": "read",
#            "params": { "url": "…" }, "id": 1 }
# stdout → { "jsonrpc": "2.0",
#            "result": { "page_id": "p_a4f0", "title": "…", … },
#            "id": 1 }

JSON-RPC 2.0 over stdin / stdout, one JSON object per line. Errors on stderr. Requests are independent — fire many in flight, match responses by id.

transport

stdio · jsonl frames

protocol

JSON-RPC 2.0

state

keyed by page_id

cancellation

drop the request id

concurrency

many page_ids, one process

persistence

cookies · dom · listeners

Three tabs: the raw RPC session you'd see on the wire, a TypeScript client you can paste into a Node project, and the equivalent in Python. The flow is the same — open a page, read its actions, click one by visible text.

# spawn heso serve as a subprocess of your agent
$ heso serve

# step 1: open the page (or read, if you want full content)
{ "jsonrpc": "2.0", "method": "open",
  "params":  { "url": "https://news.ycombinator.com" },
  "id":      1 }

{ "jsonrpc": "2.0",
  "result":  { "page_id":      "p_a4f0",
               "title":        "Hacker News",
               "actions":      [ { "ref": "@e0", "role": "link",
                                   "name": "Hacker News" },
                                 { "ref": "@e220", "role": "link",
                                   "name": "More" } ] },
  "id":      1 }

# step 2: click by visible text — no locator step required
{ "jsonrpc": "2.0", "method": "click",
  "params":  { "page_id": "p_a4f0", "text": "More" },
  "id":      2 }

{ "jsonrpc": "2.0",
  "result":  { "ok": true,
               "navigated":    "/news?p=2",
               "content_hash": "c12e89…" },
  "id":      2 }

• 01
  Search, then batch readsearch returns a list of URLs without an API key.
  ●
• 02
  Click by visible textNo locator step.
  ○
• 03
  Wait for an SPA, then readwait blocks inside the binary until a predicate is true.
  ○
• 04
  Rescue a broken site--best-effort turns crashes into structured output.
  ○

Inside the eval-js sandbox, Math.random()becomes deterministic. That's it — no virtual clock, no hashed page output. Useful when you want to exercise code paths that touch randomness without having to mock them out. Signed receipts ride on a separate flag (--receipt PATH); see chapter 03 under Trust.

$ heso eval-js --seed 42 'Math.random()'
0.5140492957650241
 
$ heso eval-js --seed 42 'Math.random()'
0.5140492957650241
 
$ heso eval-js --seed 7 'Math.random()'
0.3712389501023784

Different seeds give different sequences. Drop the flag and you get system randomness back.

Most reproducibility wins come from pinning inputs, not from hashing outputs. Pin the URL, pin the seed where randomness matters, capture the JSON heso prints. That gives you a test fixture you can diff against future runs — without claiming properties the engine doesn't actually have today.

If you need page-level reproducibility, the closest thing heso ships is the content_hash on read — a fingerprint you can pass back as --since <hash> to get a structured delta of what changed between calls. That covers drift detection. For signed provenance, pair open / read with --receipt PATH — every call mints an Ed25519-signed receipt that heso receipt-verify checks against a trusted allowlist (per ADR 0005 + 0008).