watch

Execute a program periodically, showing output fullscreen.

Description

Runs a command repeatedly at a configurable interval and displays its output in a fullscreen terminal view. Useful for monitoring changing system state. By default, the command is passed to sh -c for execution. The display is cleared and redrawn on each iteration, with an optional header showing the interval, command, and current time.

Inputs

External command execution via sh -c (default) or direct exec (with -x)
Terminal size via tcgetwinsize() syscall (rustix)

Arguments

Positional

Argument	Description
`command...` (required)	Command and arguments to execute. Passed to `sh -c` as a single string unless `-x` is used.

Timing options

Flag	Description
`-n, --interval SECS`	Update interval in seconds (default: 2.0, minimum: 0.1). Accepts fractional values.
`-p, --precise`	Attempt to run at precise intervals by compensating for command execution time

Display options

Flag	Description
`-t, --no-title`	Hide the header line showing interval, command, and current time
`-w, --no-wrap`	Truncate long lines at the terminal width instead of wrapping
`-c, --color`	Interpret and pass through ANSI color escape sequences
`-C, --no-color`	Strip ANSI color escape sequences from command output

Exit control options

Flag	Description
`-b, --beep`	Emit a BEL character when the command exits with a non-zero status
`-e, --errexit`	Freeze the display when the command exits with a non-zero status, wait for a keypress, then exit
`-g, --chgexit`	Exit when command output changes from the previous run
`-q, --equexit CYCLES`	Exit when command output remains unchanged for N consecutive cycles

Execution options

Flag	Description
`-x, --exec`	Pass the command directly to `exec()` instead of `sh -c`. Arguments are not interpreted by a shell.

Behavior

Main loop

Each iteration performs the following steps:

Query terminal dimensions.
Execute the command (via sh -c or direct exec with -x).
Clear the screen using ANSI escape sequences (ESC[2J ESC[H).
Print the header line (unless -t is specified): Every N.Ns: command left-aligned with the current time right-aligned.
Display the command output, truncated to the terminal height.
If -w is specified, truncate each line at the terminal width.
Sleep for the remaining interval time.

Precise mode (`-p`)

Without --precise, the interval is measured from the end of one execution to the start of the next. With --precise, the total cycle time (execution plus sleep) is kept as close to the requested interval as possible by subtracting the command’s execution time from the sleep duration. If the command takes longer than the interval, the next iteration starts immediately.

Exit conditions

Normal: runs indefinitely until interrupted (Ctrl-C).
--chgexit: exits with code 0 when the command output differs from the previous iteration.
--equexit N: exits with code 0 when the command output remains unchanged for N consecutive cycles.
--errexit: when the command exits non-zero, freezes the display with an error message, waits for a keypress, then exits with code 8.
--beep: sends a BEL character (\x07) when the command exits non-zero but continues running.

Exit codes

Code	Meaning
0	Success, or exit triggered by `--chgexit` / `--equexit`
4	Command could not be executed
8	Command error with `--errexit`

Keyboard shortcuts

procutils