Practical guides · 03
When a command fails: read it, explain it, then fix it.
An error message is information. Read it first, ask for an explanation when it is unclear, and treat a suggested fix as a new command to review.
4 minute read
Commands fail all the time: a folder name is misspelled, a tool is not installed, a flag belongs to a different version. The quick reaction is to retype something slightly different and hope. A steadier habit takes about a minute and usually teaches you something you will use again.
1. Read the error before anything else.
Most failures say what went wrong in the last line or two. Look for three things: the command or file it complained about, the reason it gave, such as No such file or directory or command not found, and whether anything changed before it stopped.
That last point matters. A command that failed halfway may already have created, moved or deleted something. Check before you run a second attempt.
2. Ask what it means, without running anything.
In AITerm, type /explain in the input bar, or press ⌘⇧E. With no argument it explains your last command or its output. You can also give it a command or some text to explain instead, for example /explain tar -xzf archive.tar.gz.
/explain is read-only. It streams an explanation into a panel and never runs anything, so it is a safe first step when you are not sure what you are looking at.
3. Let /fix propose a correction, then review it.
Type /fix, or press ⌘⇧F. It reads your last failed command, its exit code and the surrounding context, and proposes an edited command in the input bar.
That proposal is an ordinary editable suggestion. Nothing runs until you press Return or click Run, and the exact text in the bar passes through the same security gate as any other command. If the AI asks a clarifying question, answer it with a short follow-up after /fix.
Read the suggestion the way you would read a colleague’s: does it address the error you saw, does it start in the folder you meant, and is its risk badge what you expect? Edit it if not. A suggested fix is a good guess, not a guarantee.
4. Remember what the fix can see.
A fix is only as good as the context behind it. With a cloud model, the How much the AI sees setting in Settings ▸ Privacy limits the session context that is sent, and the default sends recent commands and exit codes without their output. A local model receives the full session context. If a suggestion seems to miss the point, the model may not have seen the output that explains the failure. Our guide to what your AI terminal sends covers this in detail.
A two-minute practice run.
- Open a new tab in a folder with nothing private in it.
- Run a command that fails harmlessly, such as
ls folder-that-does-not-exist. - Read the error and say in your own words what went wrong.
- Type
/explainand compare its explanation with yours. - Type
/fix, read the proposed command, and decide whether you would run it. Press Escape to discard it if you would not.
Try it in AITerm.
/fix and /explain are part of the free core app, along with AI command suggestions, tabs, split panes, saved workspaces, Ollama and supported bring-your-own-key connections. AITerm runs on Apple Silicon Macs with macOS 13 or later. Cloud provider charges are separate.
Keep learning.
Prepared with AI assistance from the current AITerm documentation. The steps follow the handbook; this is not a recorded app demonstration.