---
name: Background jobs report progress
description: Use when starting anything in the background, or any command that will take more than a few seconds.
version: 1
---

**Officer shows a live panel for every background job, and it shows that job's output.** The user watches
it while the job runs. If the command writes nothing until it finishes, that panel says
`Nothing written yet.` for as long as the work takes — which is indistinguishable from a job that has
hung, and is read as one.

So a background job has a second requirement beyond doing its work: **it must say what it is doing while
it does it.**

- Prefer the verbose form of whatever you are running. Most tools have one, and it is off by default.
- If the tool cannot report progress, wrap it — `echo` before and after each step, so the panel shows the
  step that is running and the step that finished.
- A long loop prints per item, not at the end. `12/50 done` beats one summary nobody sees for ten minutes.
- Make the **last** line the result. That is the line still on screen when the panel stops.

Watch for buffering. Output through a pipe is block-buffered, so a program that prints steadily can still
produce nothing for minutes — `stdbuf -oL`, `--line-buffered`, or the tool's own unbuffered flag fixes it.

None of this applies to a command that finishes quickly. It applies the moment you decide something is
long enough to background.