quizmd 2.4.3rc7

Run markdown quizzes in the terminal

quizmd

quizmd is a terminal quiz app for:

• Markdown MCQs (single/multiple)
• Imposter quizzes (spot misleading options)
• Chaos quizzes (branch + recovery scenarios)
• Essay quizzes (AI rubric scoring)
• Online room modes (compete/collaborate)
• Terminal game modes (Alien Attack)

Install

Recommended:

pip install quizmd

Update to latest:

pip install -U quizmd

From GitHub (latest repo state):

pip install "git+https://github.com/steliosot/quizmd.git"

Check install:

quizmd --version

Quick Start

Create starter files:

quizmd init

This creates:

• hello-quiz.md (single + multiple MCQ)
• hello-imposter.md (imposter mode)
• hello-chaos.md (branching scenario mode)
• hello-essay.md (essay mode)
• QUIZ_GUIDE.md (quick commands)

Run starters:

quizmd --validate hello-quiz.md
quizmd hello-quiz.md

quizmd --validate hello-imposter.md
quizmd hello-imposter.md

quizmd --validate hello-chaos.md
quizmd hello-chaos.md

quizmd --validate hello-essay.md
export GEMINI_API_KEY="your_key_here"  # or OPENAI_API_KEY / ANTHROPIC_API_KEY
quizmd hello-essay.md

Modes (What + How to Start)

1) Classic MCQ (Local)

• What: single/multiple-choice timed quiz.
• Start: quizmd hello-quiz.md

2) Imposter (Local)

• What: select correct answers and flag misleading options.
• Start: quizmd hello-imposter.md

3) Debug (Local)

• What: fix broken Python code with line-aware scoring.
• Start: quizmd hello-debug.md

4) Challenge (Local)

• What: category board + risk levels (stars scoring).
• Start: quizmd hello-challenge.md

5) Reverse (Local)

• What: infer code behavior/output in reverse-engineering style MCQs.
• Start: quizmd hello-reverse.md

6) Millionaire (Local)

• What: 15-question ladder with lifelines and safety nets.
• Start: quizmd hello-millionaire.md

7) Chaos (Local)

• What: branch + recovery scenario that rejoins at final decision.
• Start: quizmd hello-chaos.md

8) Essay (Local + AI)

• What: write a short response and get rubric feedback.
• Start: quizmd hello-essay.md

9) Room: Compete (Online)

• What: fastest correct answers win points.
• Start room: quizmd room --create --mode compete --quiz hello-quiz.md

10) Room: Collaborate (Online)

• What: discussion + voting phase, team consensus scoring.
• Start room: quizmd room --create --mode collaborate --quiz hello-quiz.md

11) Game: Alien Attack (Terminal)

• What: arcade shooter mini-game.
• Start: quizmd alien-attack

Join any room:

quizmd room --join <room-name> [--token <room-token>]

Room quiz requirement:

• In online room modes, each question Time/time_limit must be 5 seconds or higher.
• For JSON room quizzes, optional discussion_time (seconds) controls collaborate chat phase per question.

quizmd init Coverage

Yes, quizmd init covers all mode types:

• MCQ single/multiple via hello-quiz.md
• Imposter via hello-imposter.md
• Chaos via hello-chaos.md
• Essay via hello-essay.md
• Room modes by using hello-quiz.md with --mode compete|collaborate

Essay Keys (Essay Mode Only)

MCQ quizzes do not require API keys.

Supported keys:

• GEMINI_API_KEY
• OPENAI_API_KEY
• ANTHROPIC_API_KEY

Auto provider order:

1. Gemini
2. OpenAI
3. Anthropic

Mac/Linux example:

export GEMINI_API_KEY="your_key_here"

Windows PowerShell example:

$env:GEMINI_API_KEY="your_key_here"

Validate Any Quiz

quizmd --validate quizzes/harry-potter-quiz.md

Theme

quizmd --theme auto quizzes/harry-potter-quiz.md
quizmd --theme light quizzes/harry-potter-quiz.md
quizmd --theme dark quizzes/harry-potter-quiz.md

Notes

• Local question modes support Q for graceful quit with summary.
• Press Ctrl+C at any time to exit.
• Each multiple-choice question must have at least 2 non-empty options.
• If your question text includes markdown bullet lines, add an Options: line before answer choices to disambiguate parsing.

Development

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m unittest discover -s tests -q

Multiplayer server local dev note:

• Use Python 3.13 in multiplayer/server (python3.13 -m venv .venv), since Python 3.14 may fail dependency builds (pydantic-core).

Community

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md
• LICENSE