GitHub - ricardo-foundry/terminal-quest-cli: A Zork-inspired text adventure game that runs entirely in your terminal. Cross-platform Node.js CLI, zero-config install via npm.

████████╗███████╗██████╗ ███╗   ███╗██╗███╗   ██╗ █████╗ ██╗
╚══██╔══╝██╔════╝██╔══██╗████╗ ████║██║████╗  ██║██╔══██╗██║
   ██║   █████╗  ██████╔╝██╔████╔██║██║██╔██╗ ██║███████║██║
   ██║   ██╔══╝  ██╔══██╗██║╚██╔╝██║██║██║╚██╗██║██╔══██║██║
   ██║   ███████╗██║  ██║██║ ╚═╝ ██║██║██║ ╚████║██║  ██║███████╗
   ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝╚═╝╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝
                          Q U E S T   C L I

An RPG that lives entirely in your terminal — bilingual, themeable, zero-config.

Animated terminal demo: boot, ls, cd /world/lab, talk engineer, decode cipher, level up.

Try it right now — no install needed

npx terminal-quest-cli

TL;DR A terminal-native RPG with hidden files, NPCs, day/night cycle, 8 minigames, multi-slot saves and a bilingual UI. One command, zero config, no GUI dependencies. Plays in any modern terminal on macOS, Linux and Windows.

What does it look like?

A live shot from a fresh npx terminal-quest-cli session — the full 40-line script lives in docs/session-transcript.md:

$ npx terminal-quest-cli

[BIOS v2.1 - KIMI-OS]
[ok] Memory check
[ok] Initializing AI core
[ok] Mounting virtual file system
System ready.

  > Core modules loaded
  > Type "help" to start your adventure

[🌅 06:00] [Lv.1] explorer@kimi-os:~$ scan
[scan] revealing hidden entries...
  .secret/    .keychain    .diary.bak

[🌅 08:00] [Lv.1] explorer@kimi-os:~$ cd /world/lab
[🌅 09:00] [Lv.1] explorer@kimi-os:/world/lab$ talk technician
technician (neutral): "If you came for the prototype, you'll need to behave."
  > [1] "I just want to look around."   (kindness +1)
  > [2] "Move aside."                    (ruthless +1)

[🌅 09:00] [Lv.1] explorer@kimi-os:/world/lab$ run morse
Morse decode — Decode the message (single word). Type q to quit.

  -.- .. -- ..

answer 1/3 (or 'hint'): KIMI
decoded!  +80 EXP

*** ACHIEVEMENT UNLOCKED ***
  +-------------------------+
  | 📡  Morse Master        |
  | Decode without hints    |
  +-------------------------+

[☀️ 12:00] [Lv.2] explorer@kimi-os:/world/lab$ cd /shadow/archive
The archive doors are sealed during daylight.
  tip: try `wait` to advance the day/night cycle.

[☀️ 12:00] [Lv.2] explorer@kimi-os:/world/lab$ wait 6
time advances... 19:00 (Night)
*** ACHIEVEMENT UNLOCKED ***  🦉  Night Owl

[🌙 19:00] [Lv.2] explorer@kimi-os:/shadow/archive$ share
share card written: ~/.terminal-quest/shares/card-explorer-2026-04-25T11-21-00Z.txt

Two asciinema casts ship with the repo, both are valid v2 JSON:

docs/demo.cast — hand-authored, polished demo that tells the "first 60 seconds of the game" story. Regenerate with node scripts/write-cast.js.

docs/demo-real.cast — captured live by driving bin/terminal-quest.js inside a child process. Regenerate with node scripts/record-real-cast.js. Use this one when you want proof of what the CLI actually emits, not a curated story.

Play either with asciinema play docs/demo.cast.

Why another text adventure?

There are dozens of text adventures on npm. Three things make this one worth the 30 seconds:

Truly zero-config — npx terminal-quest-cli and you're playing. No setup, no install prompts, no GUI dependency, no Electron. Three transitive deps (chalk, figlet, keypress), all popular and audited.
Bilingual + themeable from day one. English / 中文 switchable at runtime, three palettes (dark / light / retro amber-CRT). Other text adventures bolt i18n on later or never.
Multi-slot saves with schemaVersion migration + 6 unique minigames + NPC mood branching. Save schema is documented and versioned, so old saves keep loading after upgrades. Minigames go beyond guess the number — Wordle clone, logic-circuit SAT solver, morse decoder, reaction QTE, snake, pong, matrix rain.

Features


🏆 39 achievements in 6 categories	🌐 5 languages (en / zh / zh-tw / ja / es)	🎨 3 themes (dark / light / retro)
💾 Multi-slot saves with schema migration	🗣️ NPC affinity + gifts (5-mood ladder, per-NPC)	🎮 11 minigames (snake, wordle, logic, morse, sokobax, sliding, connect-3, …)
🌅 Day / night + 4 seasons (30 turns each, gates content)	📇 Shareable ASCII score cards	🪟 Runs on macOS / Linux / Windows
📜 Community quest format (8 packs ship by default)	🔖 Bookmarks + `goto` for fast travel	🎁 Gift system that raises affinity and unlocks lore
🏁 Local leaderboard (`top` / `top export`)	📝 Markdown war-story reports (`report`)	🎁 Polyglot / Night-Shift / Silent-Runner new in v2.7

Plus: shell-style alias / unalias / history / !!, tab-completion helper, in-game tree / find / grep, hidden easter-egg commands, verbose --dev log mode, and a CI matrix on Node 18 / 20 / 22 across all three OSes.

Install

# Try once, no install (recommended for first-timers)
npx terminal-quest-cli@latest

# Install globally so `terminal-quest`, `tq`, `adventure` are on your PATH
npm install -g terminal-quest-cli
terminal-quest                 # or: tq / adventure

# Hack on the source
git clone https://github.com/ricardo-foundry/terminal-quest-cli.git
cd terminal-quest-cli
npm install && npm test
npm start

npx terminal-quest-cli@latest always runs the freshest published version — handy for grabbing fixes without a global re-install.

Usage

Once the game starts, explore with familiar Unix-style commands. The full reference is in docs/COMMANDS.md; this is the cheat sheet:

Category	Commands
Navigation	`ls`, `ls -a`, `cd <dir>`, `pwd`, `tree`, `map`
Inspect	`cat <file>`, `scan`, `find <name>`, `grep <text>`, `analyze`
Progress	`status`, `inventory`, `quests`, `achievements`, `share`
Interact	`talk <npc> [choice]`, `gift <item> to <npc>`, `use <item>`, `decode <file>`, `unlock master`
Play	`run snake / guess / matrix / pong / wordle / qte / logic / morse / sokobax / sliding / connect3`
Time	`wait [n]`, `sleep`, `season`, `time`, `look`
Travel	`bookmark <name>`, `bookmarks`, `goto <name>`
Shell	`alias name=val`, `unalias`, `history`, `!!`, `!<n>`, `complete <prefix>`
Stats	`top`, `top <n>`, `top export`, `top import <file>`, `report [slot]`
Meta	`save [slot]`, `load <slot>`, `saves`, `lang en\|zh\|zh-tw\|ja\|es`, `theme dark\|light\|retro`, `help`, `exit` (also accepts `:` prefix, e.g. `:save`)
Fun	`matrix`, `love`, `coffee`, `42`, `hello`, `sudo`, `easteregg`

CLI flags

Flag	Description	Example
`--slot <name>`	Load or create a named save slot on startup.	`terminal-quest --slot alice`
`--lang <en\|zh\|zh-tw\|ja\|es>`	Force a UI language. Auto-detects from `LANG`.	`terminal-quest --lang es`
`--theme <name>`	Pick a theme: `dark`, `light`, `retro`.	`terminal-quest --theme retro`
`--no-boot`	Skip the BIOS animation.	`terminal-quest --no-boot`
`--dev`	Enable verbose dev logging.	`terminal-quest --dev`
`--version`	Print the package version and exit.	`terminal-quest --version`
`--help`	Show CLI help.	`terminal-quest --help`
`--list-quests`	List every quest in `./quests/*/quest.json`.	`terminal-quest --list-quests`
`--validate-quest <path>`	Validate one quest file and exit.	`terminal-quest --validate-quest quests/starter-lab/quest.json`
`--validate-quest=new --interactive`	Step-by-step quest builder; writes a schema-valid `quest.json` to stdout (or to a path).	`terminal-quest --validate-quest=new --interactive > q.json`

Save locations

~/.terminal-quest/
├── saves/
│   ├── default.json
│   ├── alice.json
│   └── speedrun.json
└── shares/
    └── card-<handle>-<timestamp>.txt

Saves are plain JSON wrapped in { schemaVersion, slot, savedAt, state } — see docs/SAVE_FORMAT.md. The loader auto-migrates the legacy ~/.terminal-quest-save.json single-file save, so upgrading never nukes progress.

Cross-platform notes

macOS / Linux — works in any modern terminal (Terminal, iTerm2, Alacritty, Kitty, gnome-terminal, kitten).
Windows — works in Windows Terminal and PowerShell. cmd.exe works too, but ANSI 24-bit hex colours fall back to the nearest 16 colours via chalk's autodetect; the retro CRT palette will look amber-ish rather than spot-on #FFB000.
CI / piped stdout — boot animation, spinners, progress bars and scan effect all detect non-TTY and degrade to a single static line.

i18n

Code	Language	Coverage
`en`	English	100 %
`zh`	中文 (Simplified)	100 %
`zh-tw`	中文 (Traditional)	100 %
`ja`	日本語	100 %
`es`	Español	100 %

Switch with lang en / lang zh / lang zh-tw / lang ja / lang es in-game, or --lang on startup. The locale is also auto-detected from LANG / LC_ALL / LC_MESSAGES — LANG=zh_TW.UTF-8 and LANG=es_ES.UTF-8 will pick the right pack on launch. New language packs only need to implement the keys in src/i18n.js — see docs/I18N_COVERAGE.md for the contributor checklist.

Themes

Bundled palettes live in src/themes.js:

dark (default) — green / cyan / magenta on black
light — same hues, darker shades for white-on-light terminals
retro — amber monochrome, classic CRT vibes

Switch with theme retro in-game or --theme retro on startup. Custom themes are just an object of chalk color names / hex values.

Known limitations

A few honest constraints to set expectations:

Save format is JSON, not encrypted. The save lives at ~/.terminal-quest/saves/<slot>.json and a determined player can edit it by hand. Treat this as a feature for modders; treat it as a caveat for "no-cheat" runs.
Save grows linearly with play time. Replay buffer is capped at 500 events and command history at 50, but commandHistory, inventory, and npcAffinity accumulate forever. The CLI prints a one-time warning past 1 MiB.
Alias chains expand at most 8 times per command. Deeper chains are silently truncated rather than rejected. Cycles (a=b, b=a) are guarded — they will not hang the REPL.
Time advance is clamped to one in-game year per call (120 turns). A wait/sleep past that is bounded; players who want to skip further must call again. This is defensive against malformed community quests with large custom-predicate jumps.
fs.watch recursive mode is best-effort. On Linux without inotify-recursive support, the --dev hot-reloader silently no-ops. Use :reload-quests (TODO) or restart the CLI.
TTS is opt-in and host-dependent. Without --tts it is a no-op. With --tts it shells out to say (macOS), espeak/festival (Linux), or powershell (Windows); if none are installed it stays silent.
Community quest predicate evaluator is sandboxed. Only the tokens level, exp, alignment, gamesPlayed, keyFragments, turn are allowed; everything else returns false. Authors needing more expressive triggers should compose multiple step entries.
Folder name must equal id. quests/foo/quest.json with "id": "bar" is skipped at load time with a clear error in --list-quests.

Roadmap

Contributing

Issues, PRs and new quest ideas are warmly welcome. Brand-new contributors: start with the 5-minute quickstart — it walks you from a fresh clone to a merged PR in five steps and points you at the new interactive quest builder (--validate-quest=new --interactive).

For deeper context, read CONTRIBUTING.md; this project follows the Contributor Covenant.

For security issues, please see SECURITY.md and do not open a public GitHub issue.

For maintainers cutting a release: docs/RELEASING.md.

License

Stars over time

中文速览

一款完全跑在终端里的 RPG 冒险游戏。中英双语、多槽位存档、可切换主题、 8 个小游戏、34 个成就、12 条主线任务、昼夜循环 + NPC 心情分支对话。

一行启动

npx terminal-quest-cli

安装

# 全局安装
npm install -g terminal-quest-cli
terminal-quest      # 或 tq / adventure

# 源码
git clone https://github.com/ricardo-foundry/terminal-quest-cli.git
cd terminal-quest-cli && npm install && npm start

常用命令

探索：ls / ls -a / cd <目录> / tree / scan / find <名字> / grep <文本>
角色：status / inventory / quests / achievements / share
互动：talk <npc> [选项] / use <物品> / decode <文件> / unlock master
小游戏：run snake|guess|matrix|pong|wordle|qte|logic|morse
时间：wait [n] / sleep / time / look
Shell：alias name=val / unalias / history / !! / !<n> / complete <prefix>
系统：save [槽位] / load <槽位> / saves / lang / theme / help / exit

存档位置

新格式：~/.terminal-quest/saves/<slot>.json
分享卡：~/.terminal-quest/shares/
旧版单文件存档会自动迁移到 default 槽位。

通关目标

找到 3 块密钥碎片（AW4K3、_TH3_、4I），合成主密钥 AW4K3_TH3_4I，输入 unlock master 解锁最终秘密。

Sister Projects

If you like Terminal Quest, you may also enjoy:

vampire-survivors-cli — keyboard-only auto-attack roguelite rendered in box-drawing characters. npx vampire-survivors-cli
openhand — open-source virtual hand-controller that maps gamepads / MIDI / accessibility input to stdin, so you can play TUI games (including this one) with anything. npx openhand --target terminal-quest

See docs/CROSSPROMO.md for the full cross-promo policy.

Name		Name	Last commit message	Last commit date
Latest commit History 23 Commits
.github		.github
bin		bin
docs		docs
quests		quests
scripts		scripts
src		src
test		test
.editorconfig		.editorconfig
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.npmignore		.npmignore
.prettierrc.json		.prettierrc.json
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
PUBLISH.md		PUBLISH.md
README.md		README.md
SECURITY.md		SECURITY.md
install.sh		install.sh
package-lock.json		package-lock.json
package.json		package.json

Navigation Menu

Uh oh!

Repository files navigation

Try it right now — no install needed

What does it look like?

Why another text adventure?

Features

Install

Usage

CLI flags

Save locations

Cross-platform notes

i18n

Themes

Known limitations

Roadmap

Contributing

License

Stars over time

中文速览

一行启动

安装

常用命令

存档位置

通关目标

Sister Projects

About

Releases

Packages

Contributors

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Try it right now — no install needed

What does it look like?

Why another text adventure?

Features

Install

Usage

CLI flags

Save locations

Cross-platform notes

i18n

Themes

Known limitations

Roadmap

Contributing

License

Stars over time

中文速览

一行启动

安装

常用命令

存档位置

通关目标

Sister Projects

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages