🚂 sl — Steam Locomotive

You typed sl. You meant ls. The railroad thanks you for your patronage.

      ====        ________                ___________
  _D _|  |_______/        \__I_I_____===__|_________|
   |(_)---  |   H\________/ |   |        =|___ ___|
   /     |  |   H  |  |     |   |         ||_| |_||
  |      |  |   H  |__--------------------| [___] |
  | ________|___H__/__|_____/[][]~\_______|       |
  |/ |   |-----------I_____I [][] []  D   |=======|__
__/ =| o |=-~~\  /~~\  /~~\  /~~\ ____Y___________|__
 |/-=|___|=    ||    ||    ||    |_____/~\___/
  \_/      \O=====O=====O=====O_/      \_/

Every other command punishes a typo with an error message. sl rewards it with a steam locomotive. The entire point is maximal output for minimal input — two mistyped letters buy you a train, and you will watch it cross your terminal, because that is the punishment and the prize.

This is a single-file, zero-dependency Python train that takes the joke entirely too seriously: a flicker-free double-buffered renderer, wheels that actually turn, smoke that drifts and dissipates, coal cars, a whistle, and a crash mode that earns its flag.

🎲 No two typos look alike

A bare sl — the classic fumbled ls — rolls the dice on everything: locomotive type, coal-car count, color livery (four named themes plus fully random one-offs), and speed. Sometimes it whistles. Rarely, it flies. Very rarely, it does not make it across.

Event	Odds
📣 The train whistles	1 in 4
✈️ The train takes flight	1 in 10
💥 The train does not arrive at the station	1 in 20

Pass any flag and the dice are off — explicit options are fully deterministic, so your customizations always behave exactly as written.

✨ Features

• 🎲 Surprise mode — a bare sl randomizes the whole show, every run
• 🚂 Four locomotives — Classic, Small, D51, and C51 (-t)
• 🛞 Animated wheels — a 4-frame rotation cycle on every engine
• 💨 Particle smoke — drifts behind the train and dissipates, with grayscale shading on 256-color terminals
• 🚃 Coal cars — couple up to 8 tenders behind the engine (-n)
• ✈️ Flying mode — smoothstep climb with a stardust trail (-F)
• 💥 Accident mode — screen shake, a spark shower, and a proper BOOM (-a)
• 📣 Whistle — the train toots as it passes (-w)
• 🖥️ Flicker-free — double-buffered frames on the alternate screen; your terminal contents come back when the train has passed
• 🎨 Respectful of your eyes — honors NO_COLOR and --no-color; sl | cat prints a static train instead of escape-code soup
• 📐 Terminal-aware — live resize handling, clean Ctrl+C, monotonic frame pacing that doesn't drift
• 🪶 Zero dependencies — one file, pure Python standard library

📦 Installation

git clone https://github.com/developtheweb/slTrain.git
cd slTrain
sudo make install

That installs to /usr/local/bin/sl. Prefer to do it by hand?

sudo cp sl /usr/local/bin/ && sudo chmod +x /usr/local/bin/sl

Requirements: Python 3.6+, a Unix-like terminal with ANSI escape support, and a sense of humor. Nothing else — see requirements.txt, which is proudly empty.

Uninstall

sudo make uninstall

The train will remember this.

🚀 Usage

You don't use sl. You commit a typo, and sl happens to you:

$ sl              # 🎲 Surprise! Random train, livery, cars, and speed

But if you insist on driving:

$ sl -t classic   # The classic engine, no surprises
$ sl -l           # Long train: D51 pulling coal cars
$ sl -n 8         # Maximum coal. The economy is booming
$ sl -F           # Flight
$ sl -a           # Tragedy
$ sl -w -c        # A whistling C51
$ sl -s 2.0       # You have somewhere to be
$ sl -s 0.1       # You do not

Options

Option	Long Form	Description
-a	--accident	An accident occurs partway through
-F	--fly	Make the train fly through the sky
-l	--long	Use a longer train (D51 pulling coal cars)
-c	--C51	Use the C51 train type
-t	--type	Locomotive type: classic, small, d51, c51 (overrides -l/-c)
-n	--cars	Number of coal cars to pull, up to 8 (default: 0)
-w	--whistle	Sound the whistle as the train passes
-s	--speed	Animation speed multiplier, 0.1–20 (default: 1.0)
	--no-color	Disable colors (NO_COLOR is also honored)
-v	--version	Show version information
-h	--help	Show help message

Any flag disables surprise mode. The dice only roll for a naked typo.

🔧 How it works

For a joke, it's built like it matters:

• Double-buffered rendering. Each frame is composed into an off-screen cell buffer and emitted as a single write — no clear-screen between frames, so nothing flickers, ever.
• The alternate screen. The animation runs on the terminal's alternate buffer, the same trick vim and less use. When the train is gone, your scrollback is exactly as you left it. Like it never happened. It happened.
• A particle system. Smoke, crash sparks, and stardust are particles with velocity, drag, and gravity, aging through character ramps (@ → O → o → * → .) as they dissipate.
• Monotonic pacing. Frame timing is anchored to a monotonic clock, so the train's speed doesn't drift with render cost or system load.
• An honest fallback. If stdout isn't a terminal, you get a static train in plain text. sl | cat is a train. sl > file.txt is a train. There is no escaping the train, only escape codes, and those are omitted.

🤔 Why does this exist?

We've all done it — typed sl when we meant ls. Instead of command not found, why not a gentle reminder in the form of a steam locomotive chugging across your terminal?

• 📚 Typing discipline through consequences — muscle memory training, enforced by rail
• 😄 Whimsy in the command line — terminals can be fun too
• 🎭 Coworker delight — watch confusion turn to joy, then back to confusion when it crashes
• 🧘 Mandatory micro-breaks — the train cannot be skipped, only awaited

❓ FAQ

Can I stop the train? Ctrl+C works and exits cleanly. Learning to type ls also works, but nobody has ever managed it.

The train crashed. Is that a bug? If you passed -a, that's a feature. If you didn't, that's a 1-in-20 roll of surprise mode, and honestly, it's a little bit on you for typing sl.

Why would a train fly? 1-in-10 odds say you'll find out.

Is this compatible with the original sl? The spirit, the D51/C51 art heritage, and the -a/-F/-l/-c flags are all honored. The renderer, particles, and surprise mode are new.

🤝 Contributing

Contributions are welcome — new locomotives, new liveries, new disasters. See the Contributing Guidelines.

git clone https://github.com/YOUR_USERNAME/slTrain.git
cd slTrain
git checkout -b feature/amazing-feature
./sl -F                  # test your changes
git commit -m "Add amazing feature"
git push origin feature/amazing-feature

💖 Support the Project

• ⭐ Star this repository — it helps others discover the train
• 🐛 Report bugs — open an issue
• 💡 Suggest features — new train types, animations, or calamities
• 🌐 Visit my website — StevenMilanese.com
• ☕ Buy me a coffee — buymeacoffee.com/strangequark

📝 License

MIT — see LICENSE. The train is free. The train has always been free.

👨‍💻 Author

Reverend Steven Milanese

• 🌐 Website: StevenMilanese.com
• 📧 Email: contact@stevenmilanese.com
• 🐙 GitHub: @developtheweb
• 💼 LinkedIn: Connect with me

🙏 Acknowledgments

• Inspired by the original sl by Toyoda Masashi (1993), who understood that the punishment for a typo should be beautiful
• The coal car art is adapted from the original sl
• Thanks to all contributors
• Special thanks to the first stargazer who inspired this update ⭐

📊 Project Stats

---

It's not a bug, it's a locomotive. 🚂

Made with ❤️ by Reverend Steven Milanese
Visit StevenMilanese.com for more projects