> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hermai.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# How Hermai works

> What runs locally, what the registry stores, and when hosted fetch runs.

## The pieces

Hermai has three pieces:

1. **The CLI** ([hermai-cli](https://github.com/hermai-ai/hermai-cli), open source) runs on your machine. Contributors use it to inspect a site, write a schema, and push that schema to the registry.

2. **The registry** (`api.hermai.ai`) stores and serves schemas that contributors have pushed. Callers query it at runtime to get endpoint names, parameters, URL templates, and response shapes.

3. **Hosted fetch** (`POST /v1/fetch`) executes a registered endpoint through Hermai and returns the result. Use it when you want Hermai to run the request.

```
Contributor                        Platform                         Agent
    │                                  │                               │
    │  discovery toolkit (local)       │                               │
    │  hermai registry push            │                               │
    │──────────────────────────────>   │                               │
    │                                  │   GET /v1/catalog/{domain}    │
    │                                  │ <────────────────────────────│
    │                                  │   { endpoints, actions }      │
    │                                  │ ────────────────────────────> │
    │                                  │                               │
    │                                  │   POST /v1/fetch              │
    │                                  │ <────────────────────────────│
    │                                  │   structured result           │
    │                                  │ ────────────────────────────> │
```

## What the CLI does

The CLI ships deterministic commands. Each subcommand does one job and emits JSON the next step can consume:

* **`hermai detect`** classifies the site's platform (Shopify, WordPress, Next.js, etc.) and detects anti-bot systems.
* **`hermai wellknown`** probes `robots.txt`, sitemaps, RSS feeds, and GraphQL endpoints.
* **`hermai probe --body | hermai extract`** pulls embedded data from a page. It recognizes 13 SSR/hydration patterns (`__NEXT_DATA__`, `ytInitialData`, `__APOLLO_STATE__`, `SIGI_STATE`, and more).
* **`hermai intercept`** launches a browser and captures real XHR traffic for dynamic features such as search, cart, and filters.
* **`hermai introspect`** fetches a GraphQL schema.
* **`hermai session bootstrap`** warms a browser session for anti-bot sites.

The contributor composes a schema JSON file from what they find and pushes it with `hermai registry push`. No LLM key or managed service is required.

## What the platform does

The platform exposes both lookup and hosted execution:

* **`GET /v1/catalog/{domain}`** returns all endpoints and actions for a domain. This is the main runtime lookup endpoint. It requires an [intent](/concepts/catalog#intent) describing why you need it.
* **`GET /v1/schemas`** browses and searches the full registry.
* **`POST /v1/fetch`** executes a registered endpoint through Hermai. It requires an API key.
* **`POST /v1/schemas`** pushes a new schema. The registry validates it against the [intent taxonomy](/concepts/catalog#intent-taxonomy) and publishes it immediately.

You can still use Hermai as a registry only: pull the schema package, then execute the upstream request from your own infrastructure. Hosted fetch is the managed path when you want Hermai to run a registered endpoint.

## Why this split?

Discovery is expensive (browser + LLM + time). Lookup is cheap (database read). By separating them:

* **Contributors** do discovery once, locally, on their own machine
* **Later callers** reuse the schema instead of repeating discovery
* **The registry** keeps discovery separate from runtime execution
* **No vendor lock-in** because the CLI is open source (AGPL-3.0) and works offline