timeout: Usage, Options & Common CI Errors
timeout bounds how long a command may run, terminating it if it exceeds the limit.
timeout keeps a hung command from stalling a whole job. Its key signals are exit 124 (the command was timed out) and the -k grace window for processes that ignore SIGTERM.
What it does
timeout starts a command and sends it a signal (SIGTERM by default) if it is still running after the given duration. With -k it follows up with SIGKILL after a grace period for stubborn processes.
Common usage
timeout 30 ./flaky-test.sh
timeout 5m npm run e2e # m=min, h=hr, s=sec, d=day
timeout -k 10 60 ./server # SIGTERM at 60s, SIGKILL 10s later
timeout -s KILL 30 ./hang
timeout 30 curl -fsS https://slow/api || echo "timed out"Options
| Flag | What it does |
|---|---|
| DURATION | Number + optional s/m/h/d suffix |
| -s / --signal | Signal to send on timeout (default TERM) |
| -k / --kill-after | Send SIGKILL this long after if still alive |
| --preserve-status | Exit with the command's status, not 124 |
| --foreground | Allow killing non-leader foreground processes |
Common errors in CI
A timed-out command makes timeout exit 124 - scripts should treat that as "took too long", distinct from the command's own failure. Exit 137 means it had to be SIGKILLed (after -k). If the command traps and ignores SIGTERM it will not die at the limit unless you add -k or use -s KILL. "timeout: command not found" on macOS - it ships as gtimeout via coreutils, or is absent.