Substage Predicts...

I might have gone a bit overboard on this one: I built a Terminal command prediction engine for Substage, and to make it work, I ended up creating my own simulator for bash.

Before any command gets run, Substage now parses and simulates it, then shows you a visual representation of what’s about to happen to your files (and more). It's literally running the command in my own bash implementation, and seeing what the files would be changed as a result of running it for real:

If you know anything about the command line, you know how easy it is for small mistakes to cause headaches. After hearing from a few users who ran commands in Substage that err... didn’t quite do what they expected, it seemed worth putting some additional visualisation in to see what Substage is about to do. So yes, I ended up writing my own little version of bash (and a handful of standard commands) just to work out what a command will do before it actually does anything.

For example, if you’re about to batch rename a folder full of files, Substage will show exactly which filenames would change, if any files would get overwritten, and whether any new files would be created or deleted. I wanted it to be as visually clear as a GUI app for git, such as the excellent Fork. I also keep track of any side effects - such as changing system settings. Here's an example of requesting a video to be converted, and explicitly asking it to delete the original:

So how does it work? Substage fully parses the most common syntax you're likely to find in one-liner commands and also attempts to evaluate it as fully as reasonably possible. When it gets down to the individual command level, not every command is treated the same way. For simple, “harmless” commands, like checking a file’s metadata or listing files, can be run directly, since they don’t modify anything on disk. But for commands that could change or delete files, or do anything risky or long-running, Substage tries to model the effects without touching your real files.

What’s interesting is that the hardest commands to simulate aren’t always the ones you’d expect. Tools like ffmpeg look intimidating, but their input/output structure is actually quite predictable. Meanwhile, seemingly simple commands like cp (the copy command) have a huge number of options and edge cases, making them much trickier to handle. Most Substage workflows tend to use a fairly small set of tools (ffmpeg, sips, mv, etc.), so Substage mostly focuses on supporting those especially well.

It's not necessary to perfectly cover every single command for it to be useful. Most real-world usage in Substage relies on a relatively small set of common tools and patterns, so even partial coverage already catches a lot of issues and gives valuable visibility. Over time, I can keep expanding and improving Substage's understanding, adding support for more commands and edge cases as they come up. Since the vast majority of use cases are covered by the commands we support, Substage shows a strong warning when running an unrecognised command, making it clear to the user when they’re in less-charted territory. But let me know, either on Featurebase, via email or Discord if there's a command missing that you'd like to see supported!

Another benefit of this approach is that we can be a lot more precise about evaluating the risk of a command and allowing you to choose what commands can be run automatically without confirmation being necessary, so we have this new settings page:

For me, Substage is about making powerful tools more accessible, without losing any of the flexibility or control that makes the command line so useful. I’ve always preferred visual tools to the command line (hence Substage generally, and I use GUI git apps for similar reasons). I want Substage to be accessible for beginners but still efficient for power users. By simulating commands and visualising their effects, Substage helps take away a lot of the guesswork with understanding the effects of a generated bash command, especially when a rogue rename can cause data loss. But it’s not just about safety; it’s about understanding what’s going to happen, and feeling more in control.

Building this (even a partial) bash simulator was one of the most ambitious things I’ve done for Substage. The update is out now - give it a try in the latest Substage release!