Cookbook

Small recipes that stitch together the pieces from the other guides.

GitHub credentials

github_* fetchers need a token with read access to the resources they query. splashboard reads GH_TOKEN first, then falls back to GITHUB_TOKEN.

The recommended place is $HOME/.splashboard/secrets.toml — a flat TOML map of KEY = "value" pairs that splashboard exports as process env at startup. No shell rc edit, no leakage into other tools.

# $HOME/.splashboard/secrets.toml
GH_TOKEN      = "ghp_..."
TODOIST_TOKEN = "..."          # any fetcher that reads an env var works the same way

splashboard install git-ignores this file under $HOME/.splashboard/.gitignore so dotfiles-in-git users don't commit it by accident. Shell env always wins, so an ad-hoc GH_TOKEN=... splashboard ... override still works. See the secrets.toml reference for the denylist and full rules.

If you'd rather keep the token in your shell rc — e.g. because other tools also read it — that still works. Export before the splashboard init snippet:

# ~/.zshrc / ~/.bashrc
export GH_TOKEN="ghp_..."
# or, if you have the `gh` CLI configured:
export GH_TOKEN="$(gh auth token 2>/dev/null)"

No token? The github_* widgets render a "GH_TOKEN / GITHUB_TOKEN not set" error instead of breaking the rest of the splash.

A different splash per repo

The killer feature. Ship a per-dir dashboard with any repo:

your-repo/
├── .git/
├── .splashboard/
│   └── dashboard.toml      # renders when `cd your-repo`
├── src/
└── ...

Or a single-file variant: your-repo/.splashboard.toml.

The per-dir dashboard only activates at the repo root itself — cd your-repo/src/ falls back to the home dashboard, so you don't see the project splash repaint on every sub-cd.

If the repo ships no .splashboard/, splashboard still recognises the context: at a git repo root, it loads $HOME/.splashboard/project.dashboard.toml instead of the home one. Drop widgets in there to get a single "every repo root" splash without each repo carrying a config.

Network widgets in a per-dir dashboard stay gated behind splashboard trust — see the trust guide.

Custom widgets without code

Use ReadStore — write a payload file, pair it with a renderer, splashboard draws it. No code, no subprocess. Good for habit trackers, goal progress, and anything you can shell-script to a file.

Making your own theme

Start from a preset that's close, then override the tokens that don't fit.

settings.toml

[theme]
preset = "tokyo_night"

# Repaint the panel titles with a warm coral, keep everything else.
panel_title = "#f7768e"

# Swap the series palette for a two-colour cycle (nice for on/off charts).
palette_series = ["#7aa2f7", "#565f89"]

Every renderer declares the tokens it reads on its reference page, so you can work backward: "I want this widget to pop more" → open the widget's page → see which token it uses → override that.

Light-terminal setup

splashboard presets are tuned for dark terminals. On a light terminal, fall back to the terminal's own background and foreground with "reset":

[theme]
preset = "default"
bg = "reset"
bg_subtle = "reset"
text = "reset"
text_secondary = "reset"
panel_border = "reset"

Accent tokens (panel_title, status_*, palettes) stay from the preset, so the splash keeps its identity without the heavy background paint.

Opting out

The splash skips rendering when stdout isn't a terminal, TERM=dumb, or any of CI, SPLASHBOARD_SILENT, or NO_SPLASHBOARD is set. Also skipped below 40×16.

To mute just the current shell:

export SPLASHBOARD_SILENT=1

Disable the auto-display selectively

Two [general] toggles in settings.toml carve up the auto-display behaviour without killing it entirely:

[general]
# Skip the home dashboard at shell startup. The cd-hook still paints the
# project splash when you enter a project directory.
auto_home = false

# Skip every cd-hook repaint. Shell startup still renders.
auto_on_cd = false

Both default to true. Set both to false and splashboard only renders when you invoke it explicitly.

Remove the install line entirely

For the simplest opt-out, delete the marker block that splashboard install wrote into your shell rc:

# >>> splashboard >>>
# Added by `splashboard install`. Safe to remove.
eval "$(splashboard init zsh)"
# <<< splashboard <<<

Drop those lines from ~/.zshrc / ~/.bashrc / ~/.config/fish/config.fish and no startup or cd-hook fires. The splashboard binary still works on demand; only the auto-display is gone.

Slower paint, fresher data

To trade snappiness for freshness (block the initial paint until every widget has fetched):

splashboard --wait

Or persistently in settings:

[general]
wait_for_fresh = true