Skip to main content

​
Introduction

The peon command-line interface provides complete control over PeonPing sounds, notifications, sound packs, and settings. All commands work across macOS, Linux, WSL2, and Windows.

​
Command Structure

peon <command> [subcommand] [arguments] [flags]
Example: 
peon packs use glados --install

​
Global Behavior

​
Configuration Location

Commands read and write to different config locations depending on install mode:
  • Global install: ~/.claude/hooks/peon-ping/config.json
  • Local install: ./.claude/hooks/peon-ping/config.json (project-specific)
Local config takes precedence when both exist.

​
State Persistence

All CLI changes persist immediately:
  • Volume changes apply to the next sound
  • Pack switching takes effect on the next session
  • Pause/resume state persists across terminal sessions

​
Tab Completion

PeonPing supports intelligent tab completion for bash and fish shells.

​
Enable Completion

Completion is automatically installed by install.sh / install.ps1. If you need to enable it manually: Bash: 
source ~/.claude/hooks/peon-ping/completions.bash
Fish: 
source ~/.claude/hooks/peon-ping/completions.fish

​
What Gets Completed

peon <TAB>                    # Lists all commands
peon packs use <TAB>           # Lists installed pack names
peon notifications <TAB>       # Lists notification subcommands
peon trainer <TAB>             # Lists trainer subcommands

​
Command Categories

Commands are organized into logical groups:
CategoryCommandsPurpose
Sound Controltoggle, pause, resume, volume, previewMute, adjust volume, test sounds
Pack Managementpacks list/install/use/next/bind/removeDownload, switch, and assign packs
Notificationsnotifications on/off/overlay/standard/position/templateConfigure desktop popups
Trainertrainer on/off/status/log/goalExercise reminder system
Relayrelay --daemon/--stop/--status/--portRemote audio server for SSH/containers
StatusstatusShow current configuration and state

​
Exit Codes

All commands follow standard POSIX exit codes:
  • 0 — Success
  • 1 — General error (invalid argument, file not found, etc.)
  • 2 — Misuse (wrong number of arguments)

​
Environment Variables

Some commands respect environment variables:
VariablePurposeExample
PEON_RELAY_PORTOverride relay portPEON_RELAY_PORT=12345
PEON_RELAY_HOSTOverride relay hostPEON_RELAY_HOST=192.168.1.100
CLAUDE_CONFIG_DIROverride config directoryCLAUDE_CONFIG_DIR=~/.myconfig

​
Getting Help

Most commands show usage when run without arguments: 
peon notifications
# Output: Usage: peon notifications <on|off|overlay|standard|position|template|test>

peon packs
# Output: Usage: peon packs <list|install|use|next|bind|remove>
For relay-specific help: 
peon relay --help

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us