---
title: Cookbook
description: Recipes for common customizations — credentials, per-repo splashes, custom widgets, theming.
---
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.
```toml
# $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](/guides/configuration/#secretstoml) 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:
```bash
# ~/.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](/guides/trust/).
## Custom widgets without code
Use [ReadStore](/guides/read-store/) — 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.
```toml
# 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](/reference/matrix/), 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"`:
```toml
[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:
```bash
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:
```toml
[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:
```text
# >>> 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):
```bash
splashboard --wait
```
Or persistently in settings:
```toml
[general]
wait_for_fresh = true
```