CERTAMEN

A Terminal User Interface Quiz Game Engine written entirely in C++.

Made with love by trintlermint.

Read my blog documenting the development process for this project.

Author Quizzes and seamlessly "test" yourself in a full-screen TUI; host the game over SSH for you and your friends to play!

This way, you get to make fun of their... incredibly (lacking) haskell knowledge for example!

Releases

Notes

Version Control

One might ask: I'm passing everything, why do I need this?

Charlie Brown aces his tests with this!

Table of Contents

• Building
  • Releases
    • AUR
    • Nix
  • Dependencies
  • CMake
  • macOS and Windows
• Usage
  • Offline user mode
  • SSH server mode
  • CLI mode
• Setup
  • Quiz Format
  • Templates
• Troubleshooting
• Credits
• License

---

Building

Releases

I have now setup Github Releases through Actions, if you want to skip the headache of building the program, feel free to head over to releases.

Warning

This repository has just been moved from Github to Codeberg due to concerns regarding licensing, ownership of code, and ethics. Please wait for me to fix the current CI/CD, packages, etc to be written for codeberg. Thank you!

AUR

To download Certamen from the ArchLinux User Repository, do the following:

sudo pacman -S certamen

Or any equivalent command using your AUR package helper.

Nix

To install this package imperatively, run the following: (make sure to have experimental features enabled)

nix profile add github:trintlermint#certamen

Or add it to your config with the following

# flake.nix

{
    inputs.certamen.url = "github:trintlermint/certamen";
}

# ...
# somewhere else in your config

{inputs, ...}: {
    environment.systemPackages = [inputs.certamen.packages."x86_64-linux".default];
}

Dependencies

Certamen uses these predominant three libraries:

Library	Version	Install
FTXUI	v6.1.9	Fetched automatically by CMake via FetchContent
yaml-cpp	>= 0.7	System package required
libssh	>= 0.9	System package required

You also need a C++17 compiler (GCC >= 8 or Clang >= 7) and CMake >= 3.14.

CMake

Ubuntu / Debian:

sudo apt-get install build-essential cmake libyaml-cpp-dev libssh-dev

Fedora / RHEL:

sudo dnf install gcc-c++ cmake yaml-cpp-devel libssh-devel

Arch Linux (AUR):

sudo pacman -S base-devel cmake yaml-cpp libssh

Or any other equivalent function to install these packages on your UNIX machine.

Next, clone and build:

git clone https://github.com/trintlermint/certamen.git
cd certamen
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

The binary compiles into an executable, stored at build/bin/certamen. Run:

./build/bin/certamen ./templates/example_quiz.yaml

Without arguments it looks for ./quiz.yaml in the current working directory being run from.

macOS and Windows

Homebrew:

brew install cmake yaml-cpp libssh
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

Windows (using vcpkg + MSVC):

cmake --preset release
cmake --build --preset release

Warning

I am NOT a macOS OR Windows user; Manuals told me this should work, if it does or doesn't please inform me on Github Issues! See CONTRIBUTING.md

---

Usage

Offline User Mode

certamen quiz.yaml

The TUI (when opened using certamen) presents a menu with keyboard (j/k), (up/down/left/right) and number-key navigation:

1. Take Quiz; answer questions (bool: randomiser), get scored at the end
2. Add Question; compose a question with choices, optional code snippet, and explanation
3. Remove Question; delete a question
4. Change Answer; update the correct answer for an existing question
5. Edit Choice; update the text contents of a selected question's choice.
6. List Questions; browse all questions with toggleable answers, code, and explanations
7. Set Author and Name; set metadata describing the author/name.
8. Save; Save all changes and view diffs.
9. Load Quiz File; (Un)load quiz .yaml files into the current session.

There are a few more functionalities:

• Press r on the main menu to toggle randomized question and answer order.
• Press q anywhere to QUIT the program.

Furthermore, if you wish, you can import more than one .yaml file, you do this by executing: certamen 1.yaml 2.yaml ... n.yaml for any n number of yaml files you desire. This will then be loaded into the session, to manipulate them such as loading, unloading them, go to the "Load Quiz File" option. Here, you can Load new files, or get rid of them in the current session.

SSH server mode

Host a quiz for others to connect to with any SSH client:

certamen serve quiz.yaml                                  # default
certamen serve --password mysecret --port 2222 quiz.yaml  # port and pass
certamen serve --port 3000 algebra.yaml history.yaml      # port, max client

Players connect with ssh -p <port> <name>@<host> and get the same TUI in an isolated "quiz" session. The server logs scores per player.

Flag	Default	Desc
--port <N>	2222	TCP listen port
--password <pw>	(open)	Require password authentication
--key <path>	certamen_host_rsa	RSA host key (auto gen on first run)
--max-clients <N>	8	Concurrent connection limit

Important

Full server shell documentation: SERVING.md. Also, password is currently having issues currently.

CLI mode

The certamen executable bundles a plain-text CLI alongside the TUI:

./build/bin/certamen --cli quiz.yaml
./build/bin/certamen --cli [a.yaml ... n.yaml]

---

Setup

Below is information regarding how to ideally setup certamen and its corresponding quiz files locally.

Quiz format

Quizzes are YAML files. Each question is a map in a top-to-down sequence which is nested inside questions:

name: Certamen DEMO
author: trintlermint
questions:
  - question: Which of the Haskell functions below can calculate the Euclidean norm sqrt(a^2 + b^2)?
    code: |
      nrm1 :: Double -> Double -> Double
      nrm1 a b = sqrt (a^2 + b^2)

      nrm2 :: (Double, Double) -> Double
      nrm2 (a, b) = sqrt (a^2 + b^2)

    explain: |
      Both definitions compute sqrt (a^2 + b^2), one by separate arguments and one by a tuple, using only sqrt and (^).

    choices:
      - Only nrm1 is a correct implementation.
      - Only nrm2 is a correct implementation.
      - nrm1 and nrm2 are both correct implementations.
      - nrm1 and nrm2 are both incorrect implementations.
    answer: 2
  - question: Is the else part in a Haskell if expression mandatory?
    explain: |
      Haskell's if is an expression and requires both then and else branches.
    ...

• question, choices >= 2, and answer are required. code and explain are optional.
• answer is a 0-based index into choices. The TUI displays 1-based numbering to the player.
• name, author are optional and are metadata only at the start of the file
• language is an optional field for syntax highlight hinting (e.g. language: haskell) (see syntax.cpp for what has been implemented thus far).

See ./templates/example_quiz.yaml for a working template and helping me stop writing stuff (for more see below.)

Templates

As is understandable, it is very helpful to look at premade quizzes which arent just the template example_quiz.yaml, and for this reason, in the directory templates/ you will be able to find various community made quizzes to help you take some quizzes without needing to make it all by yourself! Try them out! and if you find errors, you can always send us an issue!

So far, they are just some university practice exams of mine! ( O - O)

---

Troubleshooting

This project was made rather fast by my standards due to this thing called "Computer Addiction and writing in Helix." Due to these factors, the code is bound to break. I would lovingly accept any Contributions, see CONTRIBUTING.md, or even a trivial github issue.

Anyway,

Missing yaml-cpp headers

Install the development package for your distribution:

• Debian/Ubuntu: sudo apt-get install libyaml-cpp-dev
• Fedora/RHEL: sudo dnf install yaml-cpp-devel
• Arch: sudo pacman -S yaml-cpp

Missing libssh headers

• Debian/Ubuntu: sudo apt-get install libssh-dev
• Fedora/RHEL: sudo dnf install libssh-devel
• Arch: sudo pacman -S libssh

Permission denied when saving

Certamen needs write access to the YAML file and its parent directory. Check ownership and permissions (varies based on OS).

YAML parse errors

The file must be a YAML sequence of maps. Required keys per entry: question, choices, answer. Optional: code, explain, language. See `example_quiz.yaml` for more details.

---

Credits

Written by trintlermint.

Certamen is built on:

• FTXUI by Arthur Sonzogni, terminal UI framework
• yaml-cpp by Jesse Beder, YAML parser
• libssh, SSH protocol implementation (THANK YOU DOCUMENTATION)

A big thank you to all frameworks used, and my friends for emotional support and motivation, specifically @valyntyler

The name Certamen is Latin for "contest" so I thought "yeah! this works!" thank you Wikipedia.

---

License

MIT; See [LICENSE.md](LICENSE). Copyright 2026 Niladri Adhikary.