Boozle Docs — Auto-Advance PDF Slideshows from the Command Line

Quick Start

Install Boozle (see the install guide), then run:

boozle slides.pdf --auto 30s

This opens your PDF fullscreen and advances every 30 seconds. Press q or Esc to quit.

boozle slides.pdf --auto 30s --loop --progress

Common Commands

Loop a PDF slideshow

boozle deck.pdf --auto 20s --loop

Show a progress overlay

boozle deck.pdf --auto 20s --loop --progress

Start from page 10

boozle deck.pdf --start 10

Present selected pages

boozle deck.pdf --auto 30s --pages 3-7,10

Use a second monitor

boozle deck.pdf --monitor 1

Play once and quit

boozle deck.pdf --auto 30s --autoquit

Custom background color

boozle deck.pdf --bg #1a1a2e

Use a sidecar config

boozle deck.pdf --config deck.toml

CLI Reference

All available flags for boozle:

Flag	Argument	Description
--auto	`<duration>`	Auto-advance interval. Accepts Go duration strings: `30s`, `2m`, `500ms`.
--loop		Loop back to the first slide after the last page.
--start	`<N>`	Start at page N (1-indexed).
--pages	`<range>`	Restrict playback to a page range. Supports comma-separated ranges: `1-5,8,10-12`.
--monitor	`<N>`	Open on display N. Display 0 is the primary screen.
--bg	`<hex>`	Background color behind slides (default: `#000000`).
--progress		Show a page-position and countdown HUD overlay.
--autoquit		Quit automatically after the last slide.
--no-fullscreen		Run in windowed mode instead of fullscreen.
--config	`<path>`	Load a specific TOML config file (default: same directory as the PDF).
--version		Print the Boozle version and exit.

Keyboard Shortcuts

Controls available during a presentation:

Key	Action
→ / Page Down / Space	Next slide
← / Page Up	Previous slide
Home	First slide
End	Last slide
0–9 + Enter	Jump to page number
p	Pause or resume auto-advance
b	Blackout screen (toggle)
w	Whiteout screen (toggle)
f	Toggle fullscreen
Tab	Open slide overview grid
q / Esc	Quit

Sidecar Config

Boozle automatically looks for a .toml file with the same base name as your PDF in the same directory. Place deck.toml next to deck.pdf and it loads automatically. Use --config to specify a different path.

Presentation settings that travel with your PDF.

# Global defaults apply to all slides
auto     = "30s"      # advance every 30 seconds
loop     = true       # restart after last slide
progress = true       # show countdown HUD
pages    = "1-5,8,10-12"  # optional page range
bg       = "#0a0a0a"  # background color
autoquit = false      # don't quit at end (looping)

# Override timing for specific slides
[[page]]
n    = 3
auto = "1m"    # complex diagram — hold for 1 minute

[[page]]
n    = 8
auto = "5s"    # transition slide — move quickly

Sidecar config keys

Key	Type	Description
auto	`string`	Default auto-advance duration (e.g. `"30s"`, `"2m"`)
loop	`bool`	Loop after the last slide
progress	`bool`	Show the countdown HUD overlay
pages	`string`	Page range to present (e.g. `"1-5,8,10-12"`)
bg	`string`	Background color hex (e.g. `"#000000"`)
autoquit	`bool`	Quit after the last slide
[[page]].n	`int`	Page number to override (1-indexed)
[[page]].auto	`string`	Duration override for that page

Platform Notes

macOS — Gatekeeper

If macOS Gatekeeper blocks the binary on first launch, right-click (or Control-click) the file in Finder and choose Open. Confirm in the dialog. Subsequent launches work normally. Alternatively, clear the quarantine attribute:

xattr -d com.apple.quarantine /usr/local/bin/boozle

Windows — SmartScreen

Windows SmartScreen may show a warning for unsigned binaries. Click More info then Run anyway if you trust the release source. Checksums are published alongside each release on GitHub Releases.

Linux — PATH setup

The shell script installer places the binary in ~/.local/bin. Make sure this is on your $PATH:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

Boozle documentation