# GameShell: a shell game that teaches real bash on Linux, macOS and BSD

> GameShell turns a standard bash session into a series of checked missions, so students learn Unix commands by playing rather than by reading. It is a teaching tool for classrooms, not a general shell replacement.

**phyver/GameShell** — a game to learn (or teach) how to use standard commands in a Unix shell

- Repository: https://github.com/phyver/GameShell
- Stars: 3,329 · Forks: 204
- Language: Shell
- License: GPL-3.0
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/phyver-gameshell

## What GameShell solves, and for whom

Teaching a first-year university student or a high schooler to use a Unix shell is, in the project's own words, "not always the easiest or most entertaining of tasks". GameShell was built at Université Savoie Mont Blanc to address that, and its target user is explicit: a student sitting in front of a real shell, or an instructor who wants to put one there. The original idea is credited to Rodolphe Lepigre, and it was to run a standard bash session with a configuration file that defines missions, which are then checked so the player progresses.

The design consequence is that nothing is simulated. The player is not typing into a mock terminal that pattern-matches strings. They are in bash, and the missions are evaluated against the state of that session. That matters for anyone who has watched a student pass a shell quiz and then freeze at a prompt. The game is available in English, French and Italian, which is a smaller language set than most teaching tools ship with, and the README invites new missions through issues and pull requests.

## How the missions and the shell session fit together

The repository layout tells most of the story. There is a missions/ directory, a lib/ directory holding gsh.sh, bashrc, zshrc and gshrc, a scripts/ directory, an i18n/ directory of .po files, and a Makefile that drives translation extraction. The README states the mechanism plainly: a standard bash session runs with an appropriate configuration file that defines missions, and those missions are checked in order to progress.

So the game is a layer over the shell the user already has, not a separate interpreter. The Makefile confirms the shape of that layer: xgettext extracts translatable strings from start.sh, scripts/*, lib/gsh.sh, lib/bashrc, lib/zshrc and lib/gshrc, plus an awk file, scripts/_gsh_stat.awk. That awk script is the piece that computes statistics, and the Makefile's check target exercises it by running fifty automated rounds with gsh auto --abort and then calling gsh stat. The presence of both bashrc and zshrc in the shipped files indicates the configuration is adapted per shell rather than assuming bash everywhere, even though the README frames the core as a bash session.

Missions can be skipped. The README says some missions have additional dependencies and that those missions will be skipped if the dependencies are not met. That is a sensible fallback for a classroom where machines differ, but it also means two students on two machines may not see the same sequence.

## Installing GameShell and running the first mission

On Debian or Ubuntu, the README lists the dependencies and gives one apt command that covers the game plus the mission dependencies. The packages named are gettext, man-db, procps, psmisc, nano, tree, ncal, x11-apps and wget, with bash required as well and awk generally present by default.

```bash
sudo apt install gettext man-db procps psmisc nano tree ncal x11-apps wget
```

The README notes that gettext-base and awk are the only dependencies beyond bash, and that the rest belong to specific missions. The user manual in doc/user_manual.md covers other systems, including macOS and BSD.

With dependencies in place, the README gives a two-command start. The first downloads the latest release as a self-extracting archive, the second initialises and runs the game from that archive.

```bash
wget https://github.com/phyver/GameShell/releases/download/latest/gameshell.sh
bash gameshell.sh
```

Instructions on how to play are provided inside the game itself, so there is no separate command to memorise before the first mission appears. When the player quits, with control-d or with gsh exit, progression is written to a new archive named gameshell-save.sh. Running that archive resumes where the session stopped.

If running a downloaded shell script is not acceptable, the README offers a Docker path. It downloads the Dockerfile from the same release, builds an image tagged gsh, and runs it interactively.

```bash
docker build -t gsh .
docker run -it gsh
```

The README states two limits on this route: the game will not be saved when you exit, and extra flags are needed to run X programs from inside the container. The user manual section doc/deps.md covers those flags. For a GitHub Codespace or a local VS Code Dev Container, the repository ships a .devcontainer configuration and a start.sh entry point.

```bash
bash start.sh -L it
```

The -L option selects a language, and the README uses Italian as the example.

## Where GameShell is the wrong tool

The Docker instructions are the clearest limitation. The README says the game will not be saved when you exit, which means a containerised classroom loses every student's progress at the end of each session unless they use the archive route instead. For a one-off workshop that is fine. For a semester-long course it is a problem the README does not solve.

The self-extracting archive route has the opposite shape: progress persists, but the student is running a shell script fetched from a release URL. The README acknowledges this directly by offering the Docker alternative to people who prefer not running foreign shell scripts on their computer. There is no signed-package path described, and no package repository is mentioned.

Dependency skipping is a second failure mode. Because missions with unmet dependencies are skipped rather than failed, a student on a machine without x11-apps or ncal will silently receive a shorter game. The README does not describe a warning at the point of skipping, so an instructor cannot tell from the game alone whether a missing mission was skipped or never existed.

Finally, GameShell teaches shell commands. It is not a general-purpose sandbox, not a security training environment, and not a substitute for a container or virtual machine when the goal is to let someone run arbitrary commands without risk to the host. The README describes no isolation on the archive route.

## GameShell compared with a shell tutorial or a sandboxed playground

The obvious alternative is a written tutorial or an interactive web playground where commands are typed into a browser terminal. The difference is where the evaluation happens. A web playground intercepts input and decides whether the answer matched; GameShell runs a real bash session with a configuration file and checks the state of that session. A student who learns in GameShell has already used the shell they will use later, including its own quirks, rather than a reimplementation of it.

The cost of that choice is portability. A browser playground needs nothing installed. GameShell needs bash plus gettext-base and awk at minimum, and a longer apt list if the instructor wants every mission available. It also needs either permission to run a downloaded script or a working Docker installation.

A second alternative is simply assigning exercises and grading by hand. That scales worse but has no dependency surface and no skipped missions. GameShell's advantage there is the automatic checking and the progression archive, which is what makes it usable without an instructor present for every step. The repository's own check target, which runs fifty automated rounds and then reports gsh stat, suggests the maintainers treat that checking machinery as something to verify rather than assume.

## Maintenance, licence and what a class costs to keep running

The last push to the repository was on 2026-09-21, three days before this writing, and the repository is not archived. The most recent release is tagged latest, dated 2025-05-27, and the last versioned release before it is v0.6.0 from 2024-11-18. The gap between the versioned releases is roughly eight months, which is worth knowing if you plan to pin a version for a course.

GameShell is released under GPLv3. For a university or school running it locally, that is unlikely to raise questions. For anyone embedding the missions or the checking code into a different product, the copyleft terms apply, and the README asks that you link to the repository if you use GameShell. That is a request, not a licence condition. None of this is legal advice, and the LICENSE file at the repository root is the authoritative text.

Upgrade cost is low if you use the latest archive, since the README's install downloads whatever the latest release points to. It is higher if you pin a version for reproducibility, because you then own the decision of when to move. The Makefile's translation pipeline is the part most likely to need attention from a contributor: adding a language means generating i18n/template.pot and then creating a new .po file, and the make new target prompts for a language code and refuses to overwrite an existing file.

## Conclusion

GameShell fits instructors and self-learners who want practice with real shell commands and are willing to run a downloaded bash script or build the Docker image. It is the wrong tool for anyone who needs a persistent, sandboxed environment by default, since the Docker route does not save progress on exit. Before adopting it for a class, confirm the platform-specific dependency list in doc/user_manual.md and test the mission skipping behaviour for tools your machines do not have.

## FAQ

### How do I install GameShell?

On Debian or Ubuntu, install the dependencies with apt, then download the latest release archive with wget and run it with bash gameshell.sh. The README also documents a Docker build and a GitHub Codespaces route.

### What is a game shell?

In this project, GameShell is a game built on a standard bash session configured with missions that are checked so the player can progress. It is meant to teach standard Unix shell commands to students.

### Is there an alternative to GameShell for learning the shell?

The README does not name alternatives. The practical distinction is that GameShell checks missions inside a real bash session rather than inside a simulated terminal, which is what makes it usable without an instructor at every step.

## Sources

- [Issues](https://github.com/phyver/GameShell/issues)
- [License: GPL-3.0](https://github.com/phyver/GameShell/blob/master/LICENSE)
- [phyver/GameShell on GitHub](https://github.com/phyver/GameShell)
- [README](https://github.com/phyver/GameShell/blob/master/README.md)
- [Releases](https://github.com/phyver/GameShell/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/phyver-gameshell