PROGRAM_STATUS(1)

NAME

program_status - report what a program is doing to the terminal.

SYNOPSIS

program_status [-a app] [-i id] [-k kind] [-p percent] [-t title] state [message ...]

program_status writes one Program Status Protocol report (OSC 7501) to standard output. Terminals that support the protocol use it to show whether work is running, waiting on the user, finished, or failed, for example in tab headers or session lists. Terminals without support ignore it.

The message words are joined with spaces into one human-readable line. Rush handles the protocol encoding, including base64 for text values. It rejects invalid reports with a diagnostic instead of writing something the terminal would discard.

Each report replaces the terminal's record for its id completely. A key missing from a report is missing from the record afterwards. To keep -a or -t on a record, repeat them in every report.

Like printf, program_status writes to standard output whether or not it is a terminal. Redirect it, for example program_status working >/dev/tty, when standard output is captured.

STATES

idle: At rest, waiting for the user's next instruction. Report this when the user cancels work.
working: Running. Accepts -p. The terminal drops it when the process exits or the next shell prompt starts.
blocked: Cannot continue until the user acts. Accepts -k and -p. Dropped like working.
done: Finished, with a result the user has not seen yet. Survives process exit and the next prompt.
error: Failed and stopped. Survives like done.
clear: Removes the record and every record beneath it. Without -i, removes every record on the terminal. Accepts only -i.

OPTIONS

-a app: Stable machine-readable program name, such as cargo: 1 to 32 characters from A-Z a-z 0-9 _ . + -. Child records without an app inherit the nearest ancestor's.
-i id: Record to address instead of the root record, as up to 8 slash-separated segments: for example build/test is a child of build. Each segment uses the same characters as app.
-k kind: What a blocked program waits for: permission, question, or auth.
-p percent: Progress from 0 to 100 for working and blocked.
-t title: Short label for the record, up to 192 bytes, for scripts that report several records.

Messages may be up to 2048 bytes. Messages and titles must be UTF-8 without control characters. Option values may also be attached, as in -p40. Use -- before a state when the arguments that follow might begin with -.

EXIT STATUS

Zero when the report was written, one when writing failed, and two for usage errors and invalid reports.

EXAMPLES

program_status -a rsync working "Syncing photos"
if rsync -a ~/Photos backup:/photos; then
  program_status -a rsync done "Photos synced"
else
  program_status -a rsync error "rsync failed"
fi

program_status -a deploy -k permission blocked "Approve deploy to production?"
program_status -i deploy/eu-west -t "EU West" -p 40 working "Pushing image"
program_status -i deploy clear