# Terminal runner

`starlight-quiz` ships a small command-line tool that lets you **take the quizzes from your site in the terminal**,
without a browser. It is handy for quickly checking your own questions while writing them, reviewing a topic from the
command line, or running a quiz over a deployed site. The same manifest also powers [QTI export](/starlight-quiz/guides/qti-export/).

## The quiz manifest

The CLI never parses your MDX — it reads the rendered output. A single page is scraped straight from its HTML, while a
whole site is read from a **quiz manifest**: a `quiz-manifest.json` file listing every quiz on your site, with each
question, its answers and which are correct. The plugin writes the manifest by default, so there is usually nothing to
set up. (Opt out or rename it with the [`manifest`](/starlight-quiz/guides/configuration/#manifest) option.)

The manifest is built from your rendered pages, so it is available wherever the site runs:

- On a deployed site it sits at the root alongside your pages (e.g. `https://your-docs.example/quiz-manifest.json`), so
  the CLI can fetch it straight from the URL.
- The dev server serves it too, generated on the fly at the same path (e.g.
  `http://localhost:4321/quiz-manifest.json`), so you can point the CLI at your local dev site.
- A production build writes it to disk as a static file in your output directory.

## Take a quiz

Point `run` at the **full URL of a page** to take just that page's quizzes — scraped straight from the rendered HTML,
no manifest required:

```sh
npx starlight-quiz run https://ewels.github.io/starlight-quiz/guides/multiple-choice/
```

To take **every quiz on the site at once**, point it at the manifest instead — its URL, a local build directory, or the
JSON file directly:

```sh
npx starlight-quiz run https://ewels.github.io/starlight-quiz/quiz-manifest.json
npx starlight-quiz run ./dist
```

Each question is printed in turn; you type the number(s) of your choice (or the text for a fill-in-the-blank) and press
Enter. The runner grades each answer, reveals the correct one when you are wrong, and prints a final score with a tier
message:

```text title="npx starlight-quiz run https://ewels.github.io/starlight-quiz/guides/multiple-choice/"
Question 1
──────────
What is the capital of France?

1. London
2. Paris
3. Berlin

Your answer: 3
  Correct answer: Paris
  ✗ Incorrect.

Question 2
──────────
Which of these are even numbers?

1. 2
2. 3
3. 4
4. 5

Your answers (e.g. 1,3): 1,3
  ✓ Correct!

…

Score: 3/4 (75%)
Great job! You really know your stuff!
```

### Shuffling

Add `--shuffle` to randomise the quiz order and the answer order within each quiz, or `--shuffle-answers` to randomise
only the answers:

```sh
npx starlight-quiz run https://ewels.github.io/starlight-quiz/quiz-manifest.json --shuffle
```

## History

Every run is recorded to `~/.local/share/starlight-quiz/history.json` (honouring `XDG_DATA_HOME`). Review or clear it:

```sh
npx starlight-quiz history          # a table of past runs
npx starlight-quiz history --json   # the raw JSON
npx starlight-quiz history --yaml   # the same as YAML
npx starlight-quiz history --clear  # wipe it
```

```text title="npx starlight-quiz history"
Date                      Source                                  Result  Score
────────────────────────  ──────────────────────────────────────  ──────  ─────
2026-06-29T22:15:29.682Z  https://ewels.github.io/starlight-quiz  3/4     75%
```

## Options

| Command   | Argument / flag     | Description                                                     |
| --------- | ------------------- | -------------------------------------------------------------- |
| `run`     | `<source>`          | A page URL (scraped), a manifest URL or file, or a directory containing one. |
| `run`     | `--shuffle`         | Randomise quiz and answer order.                               |
| `run`     | `--shuffle-answers` | Randomise only the answer order within each quiz.              |
| `run`     | `--filename`        | Manifest filename for a local directory (default `quiz-manifest.json`). |
| `history` | `--json` · `--yaml` · `--clear` | Print past runs as JSON · as YAML · delete the saved history. |

To turn the same quizzes into an LMS import instead, see [QTI export](/starlight-quiz/guides/qti-export/).