#Troubleshooting

When a command misbehaves, the Shell already holds every clue you need — the live output, the session context, and a durable receipt of exactly what ran.

#Overview

Most problems in the Shell are not mysteries. The Shell streams everything it does, keeps a full session history, and saves a durable receipt of every run — so when a command misbehaves, you can see precisely what happened rather than guess. The answer is almost always already on your screen.

This page is a practical checklist for reading those signals: how to find what went wrong, how to stop something that is stuck, and how to tell the difference between a real failure and a session that is simply waiting for your approval. Work through it in order, and you will resolve the common cases quickly.

#What you can do

When a command does not behave as expected, you have a few reliable moves:

  • Read the live output. The Shell streams every line as a command runs, so the actual error or stall is usually visible right there — not hidden behind a summary.
  • Review the session context. Pull up the recent history of the session to see the steps that led here, in order.
  • Stop a stuck command. End a command that is hanging or running too long without ending the whole session.
  • Check whether a permission level is holding the action. A lower permission level may be pausing for your approval — which can look like a stall but is the Shell working as you set it.
  • Review the durable receipt. Every session keeps a durable record of what it did, so you can review exactly what ran even after closing the window or restarting your machine.
  • Confirm where the work is running. Knowing whether a session is working locally on your machine or in a secure, isolated environment helps explain what it can and cannot reach.

#How to use it

Work the checklist top to bottom. Each step rules out a common cause, so you rarely need all of them.

  1. Look at the live output first. Read the most recent lines streaming into the session. A failed command usually says what went wrong right where it happened. This is the fastest answer and resolves most cases on its own.
  2. Decide: is it stuck, or is it waiting? A command that produces no new output may be genuinely hung — or it may be paused for your approval. If your session is at Plan first or Ask before acting, the Shell is holding for your permission, not failing. Approve the action (or change the level) to let it continue.
  3. Review the session context. If the latest output is not enough, pull up the recent context of the session to see the steps that led to this point. Reading the sequence in order often makes the cause obvious — a missing input earlier, a command that did not finish, a turn you did not expect.
  4. Stop a stuck command with kill. If a command is genuinely hung or running far longer than it should, stop it. This ends the running command but leaves the session intact, so you keep your history and can try again.
  5. Check the permission level and where work runs. Confirm the session's permission level — a higher level lets work flow without pausing; a lower level keeps you in the loop for each change. Confirm whether the session is working locally on your machine or in a secure, isolated environment, since that determines what it has access to.
  6. Consult the durable receipt. If you need the full picture — including across a closed window or a restart — open the session's durable receipt to review exactly what ran, step by step.
  7. Try again with more specifics. Once you know the cause, re-run the command or restate your request with the missing detail, the right constraint, or a permission level that fits the task.
Tip

Stopping always works immediately, at every permission level. If something is running away from you, you never have to wait it out — stop the command, or stop the whole task, and the Shell halts at once.

Note

A long-running job keeps going in the background and nothing is lost if you step away. If a command seems to have "disappeared," it may simply be running in the background — you are told when it finishes, and you can re-attach to a running session to watch its live output again.

#Examples

text
That command has been running for two minutes with no output — is it stuck?

You see the recent live output and session context surfaced together. The session is at Ask before acting, and the Shell is paused waiting for your approval on the next change — not hung. You approve it, and the work continues streaming.

text
Stop whatever is running and show me what happened

The running command stops immediately, and the Shell shows you the session's recent steps so you can see exactly where it got stuck and why.

text
Why did the last build fail?

You see the failure in the live output where it occurred, with the surrounding context from the session, so the cause — and the line that produced it — is right in front of you rather than buried in a final summary.

#Tips

  • Read before you restart. The error you need is usually already in the live output. Reading it first saves you from re-running a command that will fail the same way.
  • Treat a silent session as "waiting" until proven "stuck." At lower permission levels, no new output often means the Shell is holding for your approval. Check the level before assuming a failure.
  • Use kill for one bad command, close to end the whole session. kill stops just the running command and keeps your history; close is a clean stop for the entire session, and the durable receipt remains either way.
  • Lean on the durable receipt for the hard cases. When a window closed or your machine restarted, the receipt is the source of truth for what actually ran — nothing is lost.