🔍 Quiz shell for creating & playing quizzes using the macOS Terminal.



QSH is the interactive shell for playing quizzes through the macOS Terminal.

It is built on top of SwiftQuiz which provides the core functionality for making and playing quizzes in Swift. QSH provides the UI for accessing all of that functionality using the macOS Terminal.

QSH screenshot

⚠️ Work In Progress

This package is considered work in progress until reaching version 1.0.0.

Table of contents:


To play an example quiz:

qsh --url https://github.com/rwbutler/QSH/raw/master/examples/example-playable-quiz.quiz --key A%D*F-JaNdRgUkXp2s5v8y/B?E(H+KbP


qsh --url https://github.com/rwbutler/QSH/raw/master/examples/example-playable-quiz2.quiz --key A%D*F-JaNdRgUkXp2s5v8y/B?E(H+KbP

Note: Accepts both HTTP and file URLs which must be proceeded by file:// e.g. qsh --url file:///Users/username/Documents/example-playable-quiz.quiz.

To package an example quiz:

 qsh package-quiz --input "https://raw.githubusercontent.com/rwbutler/QSH/master/examples/example-quiz-input.json" --encrypt-package --key "A%D*F-JaNdRgUkXp2s5v8y/B?E(H+KbP" --output "file://<output path>"

Note: Accepts both HTTP and file URLs which must be proceeded by file:// e.g. qsh package-quiz --url file:///Users/username/Documents/quiz-input.json.


Supported Features

  • Package quizzes for distribution
  • Short answer questions, multiple answer questions and multiple choice questions
  • Picture rounds
  • Encrypts quiz packages making it harder to cheat.
  • Manual marking via sending answers to Slack via a web hook URL
  • Automatic marking

Upcoming Features

  • Keep participants in sync without the need for a server



To install via Homebrew run the following command from the Terminal:

brew install rwbutler/tools/qsh


To install using Mint run the following command:

mint install rwbutler/qsh 

Swift Package Manager

Build using Swift Package Manager as follows:

swift build -c release --disable-sandbox 

Then run using:

swift run qsh --help 


Packaging a Quiz

qsh package-quiz --input file://<path to quiz JSON> --encrypt-package --key <encryption key> --output file://<path to quiz package>

Note: To generate an AES-256 encryption key use a site such as this one.

Encrypted / Unencrypted Quiz Packages

QSH allows quizzes to be encrypted so that the answers contained within the quiz package cannot be readily be accessed preventing cheating. Use of this feature is optional as quiz packages may be encrypted or unencrypted. In order to encrypt a quiz during packaging, supply a AES-256 key generated using a site such as the one here using the --key parameter. If the --key parameter is omitted then an unencrypted quiz package will be generated.

Picture Rounds

To include a picture round as part of a quiz, include the parameter image as part of a short answer, multiple choice or multiple answer question. The value of the image parameter should be the URL (either a file URL or HTTP URL) of the image file. When the quiz is packaged, the image data will be included as part of the quiz package so that the images do not need to be downloaded separately at runtime.

Automatic Marking

In order to enable automatic marking for a quiz, add the following to your quiz JSON file:

"marking-occurs": "at-end",

Take a look here for an example.

Alternatively, if you want to mark the old-fashioned way by swapping answers then simply set the marking-occurs property to never:

"marking-occurs": "never",

Play a Quiz

qsh play-quiz --url <quiz package URL> --key <encryption key>  

Note: The key parameter is only required for encrypted packages.


qsh --help

Or to get help on a specific subcommand:

qsh package-quiz --help
qsh play-quiz --help

Developing a Quiz Client

The core functionality for packaging and playing quizzes is implemented by the Swift Quiz package with QSH providing the UI for the macOS Terminal. Should you wish to build your own client for playing quizzes e.g. using Linux, in theory you could do so using Swift Quiz.


Ross Butler

Additional Software




  • Cheats - Retro cheat codes for modern iOS apps.
  • Connectivity - Improves on Reachability for determining Internet connectivity in your iOS application.
  • FeatureFlags - Allows developers to configure feature flags, run multiple A/B or MVT tests using a bundled / remotely-hosted JSON configuration file.
  • FlexibleRowHeightGridLayout - A UICollectionView grid layout designed to support Dynamic Type by allowing the height of each row to size to fit content.
  • Hyperconnectivity - Modern replacement for Apple's Reachability written in Swift and made elegant using Combine. An offshoot of the Connectivity framework.
  • Skylark - Fully Swift BDD testing framework for writing Cucumber scenarios using Gherkin syntax.
  • TailorSwift - A collection of useful Swift Core Library / Foundation framework extensions.
  • TypographyKit - Consistent & accessible visual styling on iOS with Dynamic Type support.
  • Updates - Automatically detects app updates and gently prompts users to update.
Cheats Connectivity FeatureFlags Hyperconnectivity Skylark TypographyKit Updates
Cheats Connectivity FeatureFlags Hyperconnectivity Skylark TypographyKit Updates


  • Clear DerivedData - Utility to quickly clear your DerivedData directory simply by typing cdd from the Terminal.
  • Config Validator - Config Validator validates & uploads your configuration files and cache clears your CDN as part of your CI process.
  • IPA Uploader - Uploads your apps to TestFlight & App Store.
  • Palette - Makes your TypographyKit color palette available in Xcode Interface Builder.
Config Validator IPA Uploader Palette
Config Validator IPA Uploader Palette


  • Swift Tools 5.1.0
View More Packages from this Author


Last updated: Thu Mar 16 2023 16:43:13 GMT-0500 (GMT-05:00)