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.

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 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:

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:

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:

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:

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:

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

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.