Skip to content

User Manual

This document describes the user documentation.

Administration

Before configuring and using Peep, you should ensure that everything is installed and updated according to the Administrator Manual.

Basic usage

Running peep interactively can be done with a simple command:

$ peep
 Peep - System Overview
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 User                 some_user
 Hostname             someones-machine
 Description          A development system
 Environment          Development
 Operating System     Darwin 24.4.0
 Load Average         2.92, 2.57, 2.58
 IP Address           192.168.1.57
 Time                 17:39:24
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Help

Peep supports a couple of options, that can be checked with the -h option.

$ peep -h
Peep - minimalist system info for cozy shells.
Usage: peep [options]
Options:
-h                   Show this help message and exit
-v                   Show version information and exit
-c <file>            Use a custom configuration file
-l                   List configuration files and exit
-g <file>            Generate a default configuration file at the specified path

Configuration

Peep uses a layered configuration approach:

  1. Defaults are always loaded.
  2. If a custom config is provided with -c <file>, it is loaded and overrides defaults (home/system configs are ignored).
  3. If no custom config, but a user config exists at ~/.config/peep/peep.cfg, it is loaded and overrides defaults.
  4. If no custom or user config, but a system config exists at /etc/peep/peep.cfg, it is loaded and overrides defaults.
  5. If none of the above, only defaults are used.

You can view the config file locations with:

$ peep -l
Custom Configuration File:
User Configuration File: /home/some_user/.config/peep/peep.cfg
System Configuration File: /etc/peep/peep.cfg

Example Configuration (peep.cfg)

You can override any setting in your config file. Here’s an example:

SHOW_HEADER="true"
HEADER_TEXT="Welcome to my system!"
SHOW_USER="true"
SHOW_HOSTNAME="true"
SHOW_DESCRIPTION="true"
DESCRIPTION_TEXT="My awesome workstation"
SHOW_ENVIRONMENT="true"
ENVIRONMENT_TEXT="Production"
SHOW_TIME="true"
TIME_FORMAT="%Y-%m-%d %H:%M:%S"
SHOW_IP_ADDRESS="true"
SHOW_SHELL="true"
SHOW_LOAD_AVERAGE="true"
SHOW_FREE_MEMORY="true"
SHOW_OS_VERSION="true"

Prepared Configurations

Peep comes with some example configuration files located in the config/ folder of the repository. These can help you get started quickly or serve as templates for your own setup.

prepared configurations

  1. Browse the configs: Visit the config/ folder in the Peep repository to see available example configs.

  2. Copy a config: Download or copy the desired configuration file to your preferred location, for example:

    shell cp config/minimal.cfg ~/.config/peep/peep.cfg

    Or, to use it as a custom config:

    shell peep -c config/minimal.cfg

  3. Customize as needed: Edit the copied file to match your preferences.

These prepared configs are a great way to explore different Peep setups or quickly apply a configuration that fits your workflow.

Disk Usage

If you like, you can add disk usage to your output. This might be useful for systems that are prone to be filled or require certain space on disks, like file servers.

 Disk Usage
  /          free: 237Gi

You need to add the following to your configuration.

SHOW_DISK_USAGE="true"
DISK_USAGE_MOUNTS=("/" "/home")

Services

If enabled, Peep can show the status of selected services (Linux only):

  • Green: Service is running/enabled
  • Red: Service is stopped/disabled

Example output:

 Services
   nginx:     running enabled
   sshd:      stopped disabled

To do so, you need to add the following line to your configuration:

SHOW_SERVICE="true"
SERVICE_ITEMS=("sshd" "mysql")

Start Peep Automatically

To have Peep run every time you open a new terminal, add the following line to your shell’s configuration file:

Bash

Add this to your ~/.bashrc:

peep

Tip: If you only want Peep to run for interactive terminals (not for scripts), you can wrap it like this in Bash:

if [[ $- == *i* ]]; then
  peep
fi

Zsh

Add this to your ~/.zshrc:

peep

Tip: If you only want Peep to run for interactive terminals (not for scripts), you can wrap it like this in Zsh:

if [[ $- == *i* ]]; then
  peep
fi

Fish

Add this to your ~/.config/fish/config.fish:

peep

Tip: If you only want Peep to run for interactive terminals (not for scripts), you can wrap it like this in Fish:

if status is-interactive
  peep
end

Troubleshooting

  • If you see "not found" or "Unable to determine", your OS may not be supported.
  • Service status is only available on Linux systems with systemctl.

Further Information

  • For advanced configuration, see the comments in your config file or the Administrator Manual.
  • For bug reports or feature requests, visit the repository.

Enjoy your cozy shell!