hermai-cli

hermai-cli

English · 繁體中文 · 简体中文

Discover, contribute, and call structured website APIs from your terminal.

hermai is the open-source CLI for the Hermai registry — a community catalog of website API schemas for AI agents. Probe a site to document its endpoints, push the schema to the catalog, or pull an existing schema and call it — including authenticated writes with per-request signing.

Install

# macOS and Linux via Homebrew
brew install hermai-ai/hermai/hermai

# Anywhere Node is installed (no Go toolchain needed)
npm install -g hermai-cli      # or: npx hermai-cli --help

# Go developers
go install github.com/hermai-ai/hermai-cli/cmd/hermai@latest

# Prebuilt binaries for every OS × arch
# https://github.com/hermai-ai/hermai-cli/releases/latest

Already installed? Upgrade in place without re-running any of the above:

hermai update

Agent skill

Running in Claude Code, Codex, Cursor, or another agent? Install the Hermai skill so the agent knows how to use this CLI:

npx skills add hermai-ai/hermai-skills --skill hermai

One skill covers both audiences. When a user asks for data from a site, the agent pulls the schema and calls it. When a user wants to add a new site, the skill's contributor references (loaded on demand via progressive disclosure) walk the agent through discovery, schema authoring, and push.

Repo: hermai-ai/hermai-skills.

Call a site as an API

# Pull a schema (API key required, GitHub sign-in at hermai.ai/dashboard)
hermai registry login
hermai registry pull x.com --intent "drafting a post from my agent"

# Read endpoints: call them directly with curl / fetch / any HTTP client.
# Authenticated writes: `hermai action` handles sessions + signing for you.
hermai action x.com CreateDraftTweet --arg text="drafted by hermai"

hermai action loads the schema, resolves the user's session (cookies from disk, or pulled from an installed browser on first run), runs any schema-declared bootstrap JS to compute per-session state, runs any per-request signer JS, fires via a Chrome-TLS fingerprinted HTTP client, and rotates Set-Cookie back on 2xx responses. Works against sites that require per-request signing (X's x-client-transaction-id, TikTok's X-Bogus) without opening a browser.

Useful flags:

• --dry-run — print the fully-signed request, don't hit the network
• --schema <file> — use a local schema JSON instead of the registry cache
• --arg key=value — repeatable, fills {{var}} placeholders in the schema's URL/body templates

Registry

hermai registry login                         # GitHub OAuth, stores API key
hermai registry list                          # browse the catalog
hermai registry pull <site> --intent "..."    # download a schema
hermai registry push schema.json              # contribute a schema

Discovery toolkit

Deterministic subcommands for composing a new schema. No LLM key — each prints JSON the next step can consume.

hermai detect <url>                          # platform + anti-bot classification
hermai wellknown <domain>                    # robots, sitemap, RSS, GraphQL
hermai probe --body <url> | hermai extract   # 13 named embedded-data patterns plus
                                             # any <script type="application/json" id="X">
hermai probe --body <pdf-url> | hermai extract --state IL --url <pdf-url> --report-month 2026-02
hermai enforcement --state IL <root-url>     # discover Illinois IDFPR PDFs and emit cited actions
hermai intercept <url>                       # capture XHR in a browser
hermai introspect <graphql-url>              # GraphQL schema
hermai replay request.json                   # replay a captured request
hermai session bootstrap <site>              # warm a fresh browser session
hermai session import <site>                 # import cookies from your current browser

Capturing authenticated write endpoints

Most interesting APIs are gated behind cookies. To capture a write flow (add-to-cart, save-draft, submit-review) without logging in a second time, combine headful intercept with session injection:

# 1. Pull cookies from the browser you're already signed in with
hermai session import example.com

# 2. Open a visible Chrome, pre-loaded with those cookies, and capture what you click
hermai intercept https://example.com/product/123 \
  --headful --session example.com \
  --timeout 120s --wait 100s --ndjson > capture.ndjson

# 3. Grep/jq the captured JSON for the XHR of interest
grep -F 'CreateOrder' capture.ndjson | jq '.request.body'

The request body goes straight into your schema's body_template with {{var}} placeholders for user-varying fields. Capture, don't guess — inventing body fields is the #1 cause of rejected write schemas.

hermai introspect takes --header name=value (repeatable) for auth-gated GraphQL endpoints like Shopify Storefront or Estée Lauder's Stardust.

Import your existing browser session

When a schema requires login (post a tweet, add to cart, RSVP), you can use the session you already have in Chrome, Firefox, Safari, Edge, or Brave — no need to log in again:

hermai session import x.com
# Reads cookies scoped to x.com from your installed browsers,
# saves them to ~/.hermai/sessions/x.com/cookies.json

The first run surfaces an OS-level authorization prompt (macOS Keychain, Windows DPAPI, Linux libsecret) — Hermai can't read your cookies without your explicit consent at the OS level. Reads are always scoped to the single domain you name; we never touch cookies for other sites.

Use --dry-run to see the cookie names without writing values to disk:

hermai session import x.com --dry-run

Local cache

hermai catalog <url>                          # summarize cached endpoints for a URL
hermai schema <url>                           # show the cached schema JSON
hermai cache list                             # list cached domains
hermai init                                   # create ~/.hermai/config.yaml
hermai doctor                                 # verify your setup

hermai --help for the full command list.

Docs

• Concepts + schema spec — docs.hermai.ai
• Hosted registry + dashboard — hermai.ai
• Skill reference: hermai-ai/hermai-skills — architecture, runtime, CLI, contributing

License

AGPL-3.0. Running a modified version as a hosted service requires publishing your changes.