A terminal file manager that teaches shell commands as you work. Every action explained. Every mistake a lesson. Zero risk to your files.
You know how to manage files in Finder. ShellGuide uses that knowledge as a bridge to the command line.
You already manage files every day. Creating folders, moving things around, finding documents — you do it all with a mouse.
Every shell command maps to something you already do. ShellGuide shows the connection, explains the why, and lets you practice safely.
A three-panel file manager you can actually use. Navigate directories, create files, copy, move, delete — and every action logs the equivalent shell command with a plain-English explanation.
Guided lessons where you type real shell commands into a sandboxed filesystem. Each challenge validates your input, catches common mistakes, and explains what happened and why.
Teach mode runs inside ~/shellguide_sandbox/ —
an isolated directory that resets before each challenge. Only a curated set of safe commands
can execute. Path arguments are validated to prevent sandbox escape. Your actual files are never touched.
Every design decision in ShellGuide is about building intuition, not just teaching syntax.
Not just "use -r for directories" — but why cp refuses without it,
what could go wrong, and how the safety feature protects you.
Practice on project structures that feel real: cloned repos, monorepos,
build artifacts, config files. Not abstract file1.txt exercises.
ShellGuide recognizes common errors and explains what your command would have done, then suggests the right approach.
Every command is mapped to its GUI counterpart. ls = opening a Finder window.
cp = Option+drag. Bridges what you know to what you're learning.
As you master commands, they're added to a personal cheat sheet grouped by topic. Toggle it anytime while learning.
Start with single commands, progress to chained workflows with &&.
Lessons unlock sequentially so you always have the foundation.
ls to real workflows
Explore a freshly cloned GitHub project
Navigate a team monorepo
Build a portfolio site structure
Reorganize a messy project
Make backups before a refactor
Sprint cleanup of build artifacts
Debug a server crash from logs
Navigate an inherited codebase
Chain commands with &&
Multi-step development tasks
ShellGuide is a Python package. One command to install.
Launch the file manager. Use it normally — every action is a lesson.
Switch to teach mode for structured lessons with hands-on challenges.
Requires Python 3.10 or later. Works on macOS out of the box.
ShellGuide teaches the terminal the way it should be taught — through doing, with context, and with a safety net.