ZSCROLL(1)

📦 version 2.0.1, in nixos 26.05

💅 ZSCROLL(1) — the zscroll man page, but make it cute

okay so bestie, welcome to zscroll(1) — the man page for zscroll, aka your new favorite little terminal text scroller. no cap, this thing is iconic.

✨ NAME ✨

zscroll — a text scroller for panels or terminals 🌀

🎀 SYNOPSIS 🎀

zscroll [OPTIONS] [scroll-text or shell command]

that's it. that's the whole vibe. ✨

🦋 DESCRIPTION 🦋

okay so here's the tea ☕ — zscroll makes continuously scrolling text, like for a panel or whatever. the text you wanna scroll can be piped into zscroll, or you can just hand it over as a positional argument. either way slays. 💖

and here's the part that's genuinely so good: zscroll lets you dynamically update what text is being scrolled without having to kill it and start a whole new zscroll instance. no restart, no drama, just vibes. periodt. 👑

🌸 BOOLEAN VALUES 🌸

booleans here are super chill — you can write them in all the common ways, upper, lower, or mixed case (do NOT stress about capitalization, she does not care 💅):

  • truthy: true, t, yes, y, and 1 ✅
  • falsy: false, f, no, n, and 0 ❌

💅 OPTIONS 💅

  • -h, --help — prints the help text. the classic "help me understand" button 🫶
  • -l LENGTH, --length=LENGTH — sets the character length for the text being scrolled. if the text you give is shorter than this length, zscroll will not scroll it — it'll just print it in place, sitting pretty. (default: 40)
  • -r BOOL, --reverse=BOOL — whether the text scrolls in reverse order (so, from left to right instead of the usual way). (default: false)
  • -b PADDING, --before-text=PADDING — static padding text that is always displayed to the left of the scrolling section. it just lives there. rent free. (default: "")
  • -a PADDING, --after-text=PADDING — static padding text that is always displayed to the right of the scrolling section. (default: "")
  • -p PADDING, --scroll-padding=PADDING — padding text displayed in between the start and the end of the displayed text — and ONLY while it's actively scrolling. so if it's just chillin' in place, no padding. (default: " - ") ⭐
  • -s BOOL, --scroll=BOOL — whether the text should scroll at all. if false, the text will never scroll even if it's long enough to. this one is mostly meant to be used together with -m. (default: true)
  • -m REGEXP OPTIONS, --match-text REGEXP OPTIONS — this is the main character option fr 👑 give it a regexp search term to look for in the output of the matching --match-command. when it's found, the settings get changed. using this flag you can specify any option (except -m and -M, which get ignored) and optionally the positional scroll-text argument — and you can do it multiple times. any setting you don't specify defaults to the values you specified outside of --match-text, or to the base defaults (when those options weren't set by you at all). (default: none)
  • -M COMMAND, --match-command=COMMAND — a command whose output gets searched. this is required for -m to work, no exceptions bestie. you can either give one -M for all your -m searches, or an equal number of both. (default: none)
  • -d TIME, --delay=TIME — the delay between scroll steps. (default: 0.4)
  • -u BOOL, --update-check=BOOL — says that the positional argument is actually a command that should be run to get the text to scroll. whenever that command's output changes, the text updates accordingly. (default: false)
  • -U TIME, --update-interval=TIME — time in seconds to wait in between running update-checking commands. this applies to the positional argument when -u/--update-check is specified, and to commands given with -M/--match-command. super useful if your scrolling text only needs updating every so often, or if continuously running the update-checking command(s) is resource intensive. (default: 0)
  • -e BOOL, --eval-in-shell=BOOL — executes -M/--match-command and the positional argument in the shell (-u/--update-check must be true too). this unlocks environment variables (e.g. "$PWD"), subshells (e.g. 'echo "$(/path/to/script)"'), piping, and all that good stuff.
⚠️ bestie, watch out — quote your commands right, or you're opening the door to unwanted command injection 😭. see https://docs.python.org/3/library/subprocess.html#security-considerations for more shell security info. (default: false)
  • -n BOOL, --newline=BOOL — adds a newline after every update/step (may be necessary for use with panels). takes no argument. (default: true)
  • -t TIME, --timeout=TIME — time in seconds to run before closing. an argument of zero means infinite duration, i.e. she runs forever 💫. (default: 0)

🌈 EXAMPLES 🌈

these examples are meant for testing in the terminal — just remove the -n false if you're using them with panels. 💖

scroll the currently playing mpd song with mpc:

$ zscroll -n false -b "playing: " "$(mpc current)"

continually update the playing song:

$ zscroll -n false -u true -b "playing: " "mpc current"

you can also pipe into zscroll, which is honestly so clean:

$ xtitle | zscroll -l 60

full shell instructions can be passed too:

$ zscroll -u true -e true 'echo Unix Time: "$(date +%s)"'

an example that'll stop scrolling the song when it's paused, and change the before-padding text depending on the state of the song:

$ zscroll -n f -u t -b "x" -d 0.3 -M "mpc status" -m "playing" \
     "-b 'playing: '" -m "paused" "-b 'paused: ' -s f" "mpc current" &
🫶 note that settings specified with an -m will only apply if that text was just matched. in this case, the default -s is not altered, but the default -b is. iykyk.

🔥 SEE ALSO 🔥

lemonbar(1), polybar(1)

💀 BUGS 💀

if you encounter any bugs, please make an issue on the online repository's bug tracker. be nice about it, devs are people too 🙈

🧚 AUTHOR 🧚

Fox Kiester <noct@posteo.net> Source: https://github.com/noctuid/zscroll

and that's the whole page, bestie 🎀 this was zscroll 2.0.1, dated 11 MARCH 2015 — go forth and scroll something iconic. 🦋✨👑

📦 where this page comes from