io.github.hermai-ai/hermai-cli
Hermai MCP server — look up, submit, and classify website API schemas from any MCP client.
Open source Open in the app JSON README (API)
About
Hermai MCP server — look up, submit, and classify website API schemas from any MCP client.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- hermai-ai
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.3.0
- Stars
- 49
- Forks
- 6
- Last push
- 2026-08-18T22:19:10Z
- Repository state
- ativo
- Language
- Go
- License
- AGPL-3.0
- Added
- 2026-08-29 04:00:07
- Updated
- 2026-08-29 04:00:07
- Origin id
io.github.hermai-ai/hermai-cli
README
# hermai-cli
**English** · [繁體中文](./README.zh-Hant.md) · [简体中文](./README.zh-Hans.md)
> Discover, contribute, and call structured website APIs from your terminal.
`hermai` is the open-source CLI for the [Hermai registry](https://hermai.ai) — 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
```bash
# 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:
```bash
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:
```bash
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](https://github.com/hermai-ai/hermai-skills).
## Call a site as an API
```bash
# 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
```bash
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.
```bash
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:
```bash
# 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:
```bash
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:
```bash
hermai session import x.com --dry-run
```
## Local cache
```bash
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](https://docs.hermai.ai)
- Hosted registry + dashboard — [hermai.ai](https://hermai.ai)
- Skill reference: `hermai-ai/hermai-skills` — architecture, runtime, CLI, contributing
## License
[AGPL-3.0](LICENSE). Running a modified version as a hosted service requires publishing your changes.