# Dromad docs

Dromad is a set of GEO research tools built for coding agents. It asks ChatGPT, Claude and Gemini the questions your customers ask, with each engine's web search on, and records what each one answered and which sources it showed and cited. It counts those citations across runs, generates the questions worth asking, and audits the pages involved. Everything is available from a CLI and an HTTP API, and every result is a durable object with an ID you can come back to.

Dromad records evidence and counts it. It does not explain why an engine cited a page, write copy, or score your site: that reasoning belongs to you or your agent. If you are an agent, start with the [agent guide](https://dromad.dev/docs/agents.md).

## Quickstart

1. **Create an account** at [https://dromad.dev/signup](https://dromad.dev/signup). Anyone can sign up, and the account works at once.
2. **Install the CLI** (Python 3.12 or newer):

   ```sh
   pip install dromad
   ```

3. **Sign in.** This opens the browser; approve the code it shows. The CLI is signed in to whichever account that browser is signed in to, and `whoami` says which: with several browser profiles, `dromad login --email you@example.com` refuses any other.

   ```sh
   dromad login
   dromad whoami
   ```

   Without a browser (CI, containers, agents), create an API key at Account › API keys and set `DROMAD_API_KEY` instead.

4. **Start a project** in the directory you are working in. Work is filed under a project, and the directory stays linked to it:

   ```sh
   dromad init
   ```

5. **Ask the engines a question:**

   ```sh
   dromad prompt "best search APIs for AI agents"
   ```

   You get each engine's answer, every source it showed, and which of them it cited, as three runs (`dr_…`) in one batch (`rq_…`).

6. **Go further:** see what engines search for a prompt with `dromad fanout "best search APIs for AI agents" --runs 3`, generate questions with `dromad questions "AI search API"`, count what a set of runs cited with `dromad citations rq_… rq_…`, and audit a page with `dromad audit https://…`. The [CLI reference](https://dromad.dev/docs/cli) covers every command.

## In the browser

Signed in, the [toolkit](https://dromad.dev/toolkit) runs a prompt, generates questions or audits a page from a form, creating the same runs and analyses the CLI does. [Runs](https://dromad.dev/runs) and [Analyses](https://dromad.dev/analyses) list everything you have made from any client, and each finished one has a Sharing section to create, rotate or stop a public link. Citation analyses start from the CLI or the API.

## What Dromad records

| ID | Object | Created by |
|---|---|---|
| `ws_…` | A **workspace**: who you are working with. It owns the credit, the API keys, the projects and the work. | sign-up (your own), [Workspaces › New](https://dromad.dev/workspaces/new) |
| `pr_…` | A **project**: what you are working on. Everything below is filed under one. | `dromad init` |
| `dr_…` | A **run**: one engine's answer to one prompt, one page audit, or the generation call behind a set of questions. | `dromad prompt`, `dromad fanout`, `dromad audit`, `dromad questions` |
| `rq_…` | A **batch**: the runs one prompt request started, one per engine. | `dromad prompt` |
| `fo_…` | A **fanout**: prompts run on engines, several times, and the search queries each run issued. | `dromad fanout` |
| `fa_…` | A **questions analysis**: generated questions for a topic, clustered by intent. | `dromad questions` |
| `ca_…` | A **citation analysis**: counts over a set of prompt runs. | `dromad citations` |
| `sh_…` | A **share**: a read-only public link to a finished run or analysis. | `dromad share` |

Everyone in a workspace sees all of its projects and work; [Teams](https://dromad.dev/docs/teams) explains who sees what and who pays.

A few rules hold everywhere:

- **Finished objects never change.** A completed run is the record of what an engine said at that moment; look it up again instead of re-running it.
- **Unknown is not false.** Some providers do not say whether an answer cited a source. Dromad records that as unknown (`null`), never as "not cited", and analyses report unknowns separately.
- **Raw evidence is kept.** Each run stores the provider's full response next to what Dromad extracted from it, and each audit keeps the page it fetched.
- **Findings state their evidence.** Audit findings are labelled deterministic, supported, suggestive or experimental. [Research](https://dromad.dev/research) explains why.

## What it costs

Work is paid for from prepaid credit, and $1 bought is $1 of credit. A prompt costs $0.05 on ChatGPT, $0.20 on Claude and $0.07 on Gemini, so $0.32 on all three; a fanout is its prompt runs (prompts × engines × runs) and shows an estimate before it starts; question generation, $0.002 for each question; a page audit, $0.01. Citation analyses and sharing are included. You pay for work that completes: a run that fails costs nothing. A new account starts with a little promotional credit, and `dromad balance` shows what is left. [Billing](https://dromad.dev/docs/billing) has the details.

An account can have only so many runs queued or running at once. A request past that is refused with `rate_limited`, and one the account's credit does not cover with `insufficient_credit`; either message gives the numbers.

## Next

- [CLI](https://dromad.dev/docs/cli) — every command, with real output.
- [API](https://dromad.dev/docs/api) — authentication, errors, waiting, and the full reference.
- [For agents](https://dromad.dev/docs/agents) — which command when, and how they compose.
- [Research](https://dromad.dev/research) — the studies behind the checks.

Every docs page is also available as markdown: add `.md` to its address, or start from [`/llms.txt`](https://dromad.dev/llms.txt).