brief

Overview ¶

Command brief runs a command, shows the end of what it said, and keeps its exit status.

It exists because `cmd | head` and `cmd | tail` throw the status away, and no amount of knowing that has stopped it happening. A pipeline's status is its LAST command's, and head always succeeds:

$ false | head -3 ; echo $?
0

That is not a quirk of one shell. POSIX says it, in XCU 2.9.2 Pipelines: the status of a pipeline "shall be the exit status of the last command that is executed in the list". The same section notes that an implementation MAY provide a way to derive the status "from the exit statuses of all of the commands in the pipeline, not just the last" -- which is what bash's PIPESTATUS and `set -o pipefail` are, and the word is *may*. So `pipefail` is an extension to lean on only where the shell is known, and this works wherever the binary runs.

That has cost real answers here. Three times in one day a version tag was pushed onto a commit that did not contain the merge, because the chain was `ghmerge 21 | tail -2 && git tag …`: the refusal printed, the status vanished, the tag went onto the wrong commit, and a published tag does not move. On 2026-10-11 it happened three more times in one session while reading tools' exit statuses, including twice on this fleet's own binaries -- once reporting "exit 0" for a usage error that in fact exits 2, and once reading "actionlint is not installed" from a run where actionlint had worked and reported.

So this is not a convenience. It is the convenient path made correct:

brief -- go test ./...          # the last 10 lines, and `exit: N` on stderr
brief -n 3 -- gh pr view 42     # three lines
brief -head -n 5 -- mutsweep …  # the FIRST five, for a tool that leads

⛔ IT EXITS WITH THE CHILD'S STATUS, which is the half a display wrapper would forget. `brief -- false && next` does not run next, where `false | head && next` does. A tool that fixed only the printing would leave every `&&` chain as wrong as it was.

⛔ THE STATUS GOES TO STDERR, and the command's own output to stdout, so a caller may still capture the output without the status line landing in it.

⛔ A SIGNAL IS NOT A NUMBER. A command killed by SIGKILL has no exit status, and reporting one -- 137, the shell's convention -- invites arithmetic on something that is not a count. It is named instead: `killed by signal: killed`.