pihello

Your Pi-hole at a glance, every time you open a terminal.

Install · Quick start · Presets · Themes · Templates · Docs

pihello prints a short, colorful summary of your Pi-hole: whether ad blocking is on, how many queries were blocked today, versions and pending updates, and whatever else you want to see. Put it in your shell's startup file, a MOTD or a tmux status bar, or run it as a live dashboard. It's a pure-Python package of about 160 KB (1.2 MB installed) with no dependencies (only tomli on Python 3.10), made for Pi-hole v6.

_{Timings: median of 15 runs of the installed package, Python 3.14 on a Ryzen 5 7500F, against a Pi-hole 2026.10.0 container on the same machine. About 35 ms of that is Pi-hole checking the password at login, which takes longer on a Raspberry Pi. Against a real Pi-hole (FTL v6.7.1 in Docker on an x86 mini PC) behind a Caddy HTTPS proxy on the same LAN, the default greeting took 0.18 s, with the reverse-proxy fix.}

Install

pipx install pihello        # or: uv tool install pihello

You need Python 3.10 or newer and Pi-hole v6.0 or newer. pip install --user pihello works too, except where the system pip refuses it (Debian, Ubuntu and Raspberry Pi OS). For Pi-hole v5, use pihello==0.3.0.

Quick start

1. Create an app password in the Pi-hole web interface: Settings → Web interface / API → Configure app password. App passwords also work with two-factor authentication; your normal password works too if 2FA is off.
2. Run pihello init: five steps for the address, password, preset, theme and saving. It tests the connection, writes the config and offers to add the greeting to your shell.
3. Open a new terminal. There's your Pi-hole.

No Pi-hole at hand? pihello --demo shows everything with built-in sample data.

A few of the looks

--preset dashboard: PADD-style, with bars and 24 h sparklines	--preset fetch: neofetch-style, with the Pi-hole logo
--preset box: a framed MOTD	--preset top: top domains, blocked domains and clients

There's also default, compact, minimal, status for status bars, plain for logs, classic for the exact pihello 1.x greeting, and more. Pick the colors with --theme: nord, dracula, gruvbox, catppuccin, solarized, tokyonight, monokai, pihole, classic16 or mono.

→ See them all in the preset gallery and the theme gallery, or in your own terminal with pihello presets and pihello themes.

Shell greeting

pihello init prints the snippet for your shell and can add it for you. Use -q, so an unreachable Pi-hole never puts error messages into a new shell.

# Pi-hole greeting (pihello)
if [[ $- == *i* ]] && command -v pihello >/dev/null 2>&1; then
    pihello -q
fi

# Pi-hole greeting (pihello)
if [[ -o interactive ]] && (( $+commands[pihello] )); then
    pihello -q
fi

# Pi-hole greeting (pihello): replaces fish's default greeting
function fish_greeting
    type -q pihello; and pihello -q
end

# Pi-hole greeting (pihello)
if (Get-Command pihello -ErrorAction SilentlyContinue) { pihello -q }

# /etc/profile.d/pihello.sh
case $- in
    *i*) command -v pihello >/dev/null 2>&1 && pihello -q ;;
esac

# ~/.tmux.conf
set -g status-interval 30
set -g status-right '#(pihello -q --preset status --color never --cache 30) '

Integrations has more: starship, waybar, polybar, Debian's update-motd.d, scripts and cron.

Customising

Templates are plain text with [style tags] and {expressions}. Start from a copy of a preset:

pihello presets default --source -o ~/.config/pihello/greeting.txt

Or write one from scratch:

[@title]Pi-hole {version.core.local.version}[@muted] · [{blocking|map(enabled=@good, _=@bad)}]● {blocking}
[@label]Blocked [@highlight]{queries.blocked|number}[@muted] of {queries.total|number} ({queries.percent_blocked|percent})
[@label]Top ad  [@highlight]{top_blocked.0.domain|default("none")}
[@label]24h     [@accent]{history|pluck(total)|spark(30)}

Try it with pihello --demo -f ~/.config/pihello/greeting.txt, then replace the preset line in the config file with template = "~/.config/pihello/greeting.txt". The template guide covers the language, and the references list every filter and every variable you can show.

Commands

Every command has --help, and Commands has examples and every option.

Configuration

pihello init writes ~/.config/pihello/config.toml (%APPDATA%\pihello\config.toml on Windows):

# ~/.config/pihello/config.toml
url = "https://pi.hole"
password_file = "~/.config/pihello/password"
verify_tls = "tls_ca.crt"
preset = "default"
theme = "nord"
cache_ttl = 30

[profiles.backup]          # pihello -P backup
url = "http://192.168.1.3"
password_command = "pass show pihole-backup"

Command-line options and PIHELLO_* environment variables override the file. Configuration describes every setting, the password options, profiles, style overrides, HTTPS certificates and caching.

Troubleshooting

Run pihello doctor first. It checks every step from the config file to the API session and says what to do about each problem.

Troubleshooting has the details and more error messages. Still stuck? Open an issue with the output of pihello doctor (it never contains your password).

Upgrading from 1.x

Your pihello ADDR PASSWORD -f FILE … command and template files keep working, and the classic preset is the exact 1.x look. Running pihello init once moves the password out of your shell history. Upgrading from 1.x lists every change.

Documentation

Development

Contributions are welcome. Contributing explains the setup (uv sync), the checks and the tests.