pihello

pihello is a simple and configurable command-line tool used to display statistics of your Pi-hole.
No additional dependencies required.

What's this used for?

You frequently work in the terminal or ssh into your pi-hole host? Wouldn't it be nice to have a useful greeting message?

Just install and add the pihello <your.pihole.address> <your.pihole.app-password> command to your shell's startup script (.bash_profile, .zshenv, fish_greeting.fish, etc.). Next time you open the terminal you'll be greeted by the default (or your own) fancy message!

Installation

Requirements

• A running pi-hole v6+ instance (for Pi-hole v5, use pihello==0.3.0)
• Python >=3.8

Authentication uses a Pi-hole app password: create one in the Pi-hole web interface under Settings → Web interface / API → Configure app password.

Quickstart

Install:

pip install pihello

Run a preconfigured display (as seen above):

pihello <your.pihole.address> <your.pihole.app-password>

Usage

Examples

To run from the command line for standard HTTP Pi-hole installs:

pihello <your.pihole.address> <your.pihole.app-password>

To run from the command line with a custom configuration file:

pihello <your.pihole.address> <your.pihole.app-password> -f /path/to/config.txt

To run from the command line for HTTPS Pi-hole installs:

pihello <your.pihole.address> <your.pihole.app-password> -p

To run from the command line for HTTPS Pi-hole installs with a self-signed certificate (skips TLS certificate verification):

pihello <your.pihole.address> <your.pihole.app-password> -p -k

Full command options:

$ pihello -h
usage: pihello [-h] [-v] [-i INDENT] [-f FILE] [-c] [-W WIDTH] [-H HEIGHT]
               [-ts [TIMESTAMP]] [-p] [-k]
               addr password

positional arguments:
  addr                  the address of your Pi-hole
  password              your Pi-hole app password from settings

options:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
  -i, --indent INDENT   set the indentation step (default: 4)
  -f, --file FILE       specify path to the output config file
  -c, --clip            set whether overflowing text will be discarded or
                        added to the next line
  -W, --width WIDTH     set the screen width (0 = no limit). (default: 80)
  -H, --height HEIGHT   set the screen height (0 = no limit). (default: 25)
  -ts, --timestamp [TIMESTAMP]
                        add a timestamp as the first line. Pass optional
                        strftime format string. Example "%H:%M - %a %d/%m/%y"
  -p, --proto           use HTTPS instead of HTTP.
  -k, --insecure        skip TLS certificate verification (for self-signed Pi-
                        hole certs)

Configuration

Create a configuration text file anywhere in your userspace.

example.txt

More example configurations can be found in docs/SHOWCASE.md.

[cyan2]─────────────────────────────────────────────────────[]
[white]PiHole[] ([green4]{blocking}[]) [lightgreen]{version.core.local.version}[white], Web [lightgreen]{version.web.local.version}[white], FTL [lightgreen]{version.ftl.local.version}
[cyan2]─────────────────────────────────────────────────────[]
Blocking [darkcyan]{gravity.domains_being_blocked}[] domains for [steelblue]{clients.active}[] clients
Blocked [fuchsia]{queries.blocked}[] out of [lightgreen]{queries.total}[] queries [underline]today[] ([steelblue]{queries.percent_blocked}%[])
[grey37]Gravity last updated [bold grey50]{gravity.relative.days}[grey37] days [bold grey50]{gravity.relative.hours}[grey37] hours and [bold grey50]{gravity.relative.minutes}[grey37] minutes ago

Run pihello with the -f flag pointing to the configuration file:

pihello <your.pihole.address> <your.pihole.app-password> -f /home/username/path_to/example.txt

Variable injection

PiHole API's variables can be easily injected by using curly braces { }.

Syntax: {variable_name}

Example: "PiHole {version.core.local.version} (FTL: {version.ftl.local.version})"

Notes:

• Variable names are case-sensitive
• Open curly brace, which is not part of a variable injection, should be escaped like so \{

Styling

• Text styling is done by inserting style tags [ ]
• Color prepended by a semicolon : indicates a background color
• Color prepended by an underline _ indicates an underlined color AFAIK, only supported in Kitty, VTE, mintty and iTerm2.

Syntax: [<style> <foreground_color> :<background_color> _<underline_color>]

Example: "[italic navy]Hello [underline maroon :green]World[bold]!"

Notes:

• Open square bracket, which is not part of a style, must be escaped like so \[
• Empty square brackets, [], can be used to reset the style
• Order of the parameters does not matter
• Extra whitespace and letter's case is ignored

Colors

There is a number of ways to define a color:

Development

PRs welcome!

Showcase your configuration! Submit a PR with your configuration and a screenshot.

Installation

1. Install Poetry
2. Clone or fork the repo
3. Install the dependencies poetry install This creates a virtual environment and installs the project into it.
4. Activate the virtual environment poetry shell
5. Run the project pihello ...

TODO-list

In no particular order

• Authentication for access to more variables
• Start accessing more variables
• Justification styling similar to Python's ljust() and rjust()
• Use the screen width and height to break up the text
• Add actual support for indentation
• Conditional formatting/styling
• Periodic updates (as if using watch command) but with working colors
• Structured config using .yaml or some other type

Changelog

Changelog can be found in CHANGELOG.md

Licence

MIT Licence