# Quickstart

Record a task on a public site, build a spider from it, check the spider offline, then run it for real.

## Before you begin

- Node.js 24 or later
- Google Chrome
- A clone of the Graphdom repository

Graphdom has no runtime dependencies and no build step. Run it from the clone:

```sh
cd graphdom
alias graphdom="node $PWD/src/cli.ts"
graphdom --version
```

## 1. Record a session

```sh
graphdom record https://quotes.toscrape.com --task "search quotes"
```

Chrome opens on the site. Do the task as you normally would, then close the browser or press `Ctrl-C`. Graphdom prints the session directory:

```text
archive/sessions/2026-11-06T09-12-44-101Z-3f9a1c
```

Record the same task two or three more times with different inputs. More sessions give the spider more evidence to generalise from.

You can start from Studio instead: `graphdom studio` on an empty workspace walks you through adding the site, making a project and naming the task, then opens the task's page at *Record a session*, where **Record** opens the same Chrome window.

<aside class="callout" data-kind="tip">

To record in your own Chrome profile instead of a launched one, load the extension from `extension/` and run `graphdom relay`.

</aside>

## 2. Review it in Studio

```sh
graphdom studio --root archive
```

Studio opens in a Chrome app window on `127.0.0.1:7357`. Each session shows its actions, the requests they caused and the pages they led to. Once a recording is finished, its actions are grouped as the spider will perform them, so they are the same steps the task's Flow lines up across sessions. Anything the spider will not do, like a click that led nowhere, is tagged *not a spider step*.

## 3. Build the spider

```sh
graphdom build archive --task "search quotes"
```

The build derives a spider from the sessions and runs it against each one in its sandbox. It ships only when every session passes. The spider lands in `spiders/<task>/v1/`, and each later build in the next version beside it:

| File | Contents |
|---|---|
| `spider.json` | The spider in its intermediate form (IR) |
| `spider.ts`, `prelude.ts` | The same spider compiled to Playwright |
| `tests.json` | Each session's inputs and expected outcome |
| `report.json`, `evidence.json` | The test results the release is based on |

When `GOOGLE_CLOUD_PROJECT` is set, Gemini on your Vertex AI project (`gemini-3.5-flash`) repairs candidates that fail; otherwise a Claude model does, when `ANTHROPIC_API_KEY` is set. Pass `--model none` to derive only.

<aside class="callout" data-kind="note">

If no candidate passes, the build exits with `1`, prints the failing steps, and keeps the closest attempt as a draft you can open in Studio.

</aside>

In Studio, the task's page lists its versions, newest first: whether each passes, when it was built, and where it came from. A version built from the recordings says so. A repair names the version it repaired and counts what it changed, and that count opens the spider compared with that version, step by step.

## 4. Run it

Check the spider offline on Graphdom's runtime first:

```sh
graphdom runtime test spiders/<task>/v1/spider.json \
  --session archive/sessions/<id>
```

Then run it on the real site:

```sh
graphdom runtime run spiders/<task>/v1/spider.json --input query=love
```

The runtime asks on the terminal before every submit step. Pass `--yes` to skip the prompt. Outputs are printed as JSON on stdout.

## Next steps

- [How it works](/concepts/how-it-works/) explains each stage.
- [CLI reference](/reference/cli/) lists every flag, including secrets, files and sandbox levels.