SNOOZE(1)

📦
version 0.5.1 · 2 versions
, in alpine 3.24, nixos 26.05, nixpkgs unstable

💅 SNOOZE(1) — like, the general commands manual bestie ✨

okay so picture this: it's a manual page, right, and it's called snooze, and it lives in the General Commands Manual section (section 1, obviously 🎀). she's a lil scheduling icon and she's about to eat 💅

🌸 NAME 🌸

snooze — run a command at a particular time ⏰✨

🦋 SYNOPSIS 🦋

snooze [-nv] [-t timefile] [-T timewait] [-R randdelay] [-J jitter]
       [-s slack] [-d day] [-m mon] [-w wday] [-D yday] [-W yweek]
       [-H hour] [-M min] [-S sec] command ...

no cap, that's the whole vibe up there 👆

✨ DESCRIPTION ✨

snooze waits until a particular time and then runs a command. that's it, that's the girl 🫶 together with a service supervision system like runsv(8), you can literally use her to replace cron(8). main character energy fr fr 👑

the options are as follows, bestie, and there are a LOT of them so buckle up:

  • -n — dry run 🏃‍♀️ she prints the next 5 times the command would run and then exits. no actual running, just vibes.
  • -v — verbose 🗣️ prints scheduled (and rescheduled) times. she's a talker.
  • -t, -T — see below, in “TIMEFILES” 💖
  • -R — delays the determination of the scheduled time randomly up to randdelay seconds later 🎲 (so even she doesn't know when she's picking it)
  • -J — delays execution randomly up to jitter seconds later than the scheduled time 🫧
  • -s — commands are executed even if they're slack (default: 60) seconds late ⏱️ caveat, listen up: this will not result in immediate execution unless “TIMEFILES” are used 🙈

the durations randdelay and slack and timewait are parsed as seconds, unless you slap a postfix on there: m for minutes, h for hours, or d for days ⏳ iykyk

🎀 the remaining arguments are patterns for the time fields 🎀

  • -d — day of month
  • -m — month
  • -w — weekday (0-7, sunday is 0 and 7 — she contains multitudes ✨)
  • -D — day of year (1..366)
  • -W — ISO week of year (1..53)
  • -H — hour
  • -M — minute
  • -S — second

🌈 the syntax for these options, bestie 🌈

  • -d 3 — exact match: run on the 3rd 🎯
  • -d 3,10,27 — alternation: run on 3rd, 10th, 27th 🍓
  • -d 1-5 — range: run on 1st, 2nd, 3rd, 4th, 5th 🧚
  • -d * — star: run every day ⭐
  • -d /5 — repetition: run on 5th, 10th, 15th, 20th, 25th, 30th day 🔁
  • -d 2/5 — shifted repetition: run on 7th, 12th, 17th, 22nd, 27th day 🌀

and combinations of those, e.g. -d 1-10,15/5,28 💫 she's flexible like that.

the defaults are -d* -m* -w* -D* -W* -H0 -M0 -S0, that is, every midnight 🌙 like clockwork, literally.

⚠️ note note note: all patterns need to match — this is contrary to cron(8) where either day of month or day of week matches. so -w5 -d13 only runs on Friday the 13th 💀 spooky but correct. no cap.

if snooze receives a SIGALRM signal, the command is immediately executed ⚡ like immediate immediate.

💖 TIMEFILES 💖

optionally (and honestly, kind of optionally-iconically), you can keep track of runs in time files, using -t 🗂️

  • when -T is passed, execution will not start earlier than the mtime of timefile plus timewait seconds ⏲️
  • when -T is not passed, snooze will start finding the first matching time starting from the mtime of timefile, and taking slack into account 🧠 (e.g. -H0 -s 1d -t timefile will start an instant execution when timefile has not been touched today, whereas without -t this would always wait until next midnight 🌙)

if timefile does not exist, it will be assumed outdated enough to ensure earliest execution 🌱

🚨 big one, don't skip: snooze does not update the timefiles — your job needs to do that! only mtime is looked at, so touch(1) is good 🫶

👑 EXIT STATUS 👑

the snooze utility exits 0 on success, and >0 if an error occurs ✅

the command is run using exec, so its exit status gets propagated to the parent 🔗

if no command was given, snooze just returns with status 0 🫡 she's polite like that.

🦋 SEE ALSO 🦋

runwhen(1), sleep(1), uschedule(1), cron(8) ✨ go read them, bestie, they're all in the group chat.

🌸 AUTHORS 🌸

Leah Neukirchen <leah@vuxu.org> 🫶 icon behaviour.

💜 LICENSE 💜

snooze is in the public domain 🎉

To the extent possible under law, the creator of this work has waived all copyright and related or neighboring rights to this work 🌍✨

http://creativecommons.org/publicdomain/zero/1.0/

okay that's the whole page, periodt 💅 this Debian build is dated August 26, 2023 and yes she's serving General Commands Manual realness, mwah 😘🎀

📦 where this page comes from