Skip to main content

​
toggle

Toggle sounds on/off. The opposite of the current state. 
peon toggle
Output: 
peon-ping: sounds resumed
Output (when paused): 
peon-ping: sounds paused (run 'peon toggle' to unpause)
Behavior:
  • Creates .paused marker file when pausing
  • Removes .paused marker file when resuming
  • State persists across sessions
  • Desktop notifications continue when paused (controlled separately via peon notifications off)

​
pause / mute

Mute all sounds. Alias: mute. 
peon pause
peon mute    # Same as pause
Output: 
peon-ping: sounds paused (run 'peon toggle' to unpause)
What Gets Muted:
  • Voice lines for all CESP categories
  • Audio playback during hook events
What Continues:
  • Desktop notifications (controlled by desktop_notifications config key)
  • Mobile push notifications
  • Terminal tab title updates

​
resume / unmute

Unmute sounds. Alias: unmute. 
peon resume
peon unmute  # Same as resume
Output: 
peon-ping: sounds resumed

​
status

Check if peon-ping is paused or active, and show current configuration. 
peon status
Output (when active): 
peon-ping: active
peon-ping: desktop notifications on
peon-ping: notification style overlay
peon-ping: notification position top-center
peon-ping: dismiss time 4s
peon-ping: volume 0.5
peon-ping: pack peon (5 sounds loaded)
peon-ping: rotation mode random
Output (when paused): 
peon-ping: paused
peon-ping: desktop notifications on
peon-ping: notification style overlay
peon-ping: notification position top-center
peon-ping: dismiss time 4s
peon-ping: volume 0.5
peon-ping: pack peon (5 sounds loaded)
peon-ping: rotation mode random
Verbose Mode: 
peon status --verbose
Shows additional details:
  • Headphones detection status
  • Mobile notification configuration
  • Notification templates
  • Project name overrides
  • Trainer status

​
update

Update peon-ping to the latest version and refresh all sound packs. 
peon update
What it does:
  • Migrates config keys if needed (active_pack → default_pack)
  • Re-runs the installer to update peon.sh and all scripts
  • Preserves your configuration and installed packs
  • Updates pack manifests from the registry
Output: 
Updating peon-ping...
peon-ping: config migrated (active_pack → default_pack, agentskill → session_override)
Fetching latest version...
Successfully updated to v2.12.0
This command requires curl and internet access to fetch the latest installer from GitHub.

​
help

Show the complete CLI help with all available commands. 
peon help
peon --help
peon -h
Displays:
  • All top-level commands with descriptions
  • Pack management subcommands
  • Mobile notification setup
  • Trainer commands
  • Relay server options

​
volume

Get or set volume level (0.0–1.0).

​
Get Current Volume

peon volume
Output: 
peon-ping: volume 0.5

​
Set Volume

peon volume 0.7
Output: 
peon-ping: volume set to 0.7
Valid Range:
  • Minimum: 0.0 (silent)
  • Maximum: 1.0 (full volume)
  • Values are rounded to 2 decimal places
Error Handling: 
peon volume 1.5
# Output: peon-ping: volume must be between 0.0 and 1.0

peon volume abc
# Output: peon-ping: invalid volume "abc" — use a number between 0.0 and 1.0
Platform Behavior: Volume scaling varies by audio backend:
PlatformBackendVolume Interpretation
macOSafplay0.0–1.0 (native)
Linux (PipeWire)pw-play0.0–1.0 (native)
Linux (PulseAudio)paplayConverted to 0–65536
Linux (FFmpeg)ffplayConverted to 0–100
WSL2PowerShell MediaPlayer0.0–1.0 (native)
WindowsPowerShell MediaPlayer0.0–1.0 (native)

​
preview

Play all sounds from a specific category or list available categories.

​
Preview a Category

peon preview session.start
Behavior:
  • Plays all sounds in the category sequentially
  • Uses the currently active pack
  • Respects current volume setting
  • No delay between sounds

​
List Categories

peon preview --list
Output: 
Available categories in peon pack:
  session.start
  task.acknowledge
  task.complete
  task.error
  input.required
  resource.limit
  user.spam

​
Preview All Sounds in Active Pack

peon preview
Behavior:
  • Defaults to session.start category
  • Useful for testing after switching packs
Available Categories:
CategoryWhen It PlaysExample Sounds
session.startAgent session begins”Ready to work?”, “Yes?”
task.acknowledgeAgent acknowledges task”On it.”, “I read you.”
task.completeTask finishes successfully”Work, work.”, “Job’s done!”
task.errorTool or command fails”I can’t do that.”, “Son of a bitch!”
input.requiredAgent needs permission”Something need doing?”, “Hmm?”
resource.limitRate/token limit hit”Zug zug.”
user.spam3+ prompts in 10 seconds”Me busy, leave me alone!”
Extended Categories (defined in CESP spec, not currently triggered):
  • session.end — Session ends
  • task.progress — Long-running task progress update

​
Examples

​
Quick Mute for a Meeting

peon pause
# ... meeting happens ...
peon resume

​
Test New Pack After Install

peon packs install glados
peon packs use glados
peon preview session.start

​
Adjust Volume for Open Office

peon volume 0.3
peon preview task.complete

​
Check All Sounds in a Pack

peon packs use sc_kerrigan
peon preview --list
peon preview session.start
peon preview task.complete
peon preview input.required

​
Related Commands

  • peon status — Shows current volume and pause state
  • peon packs use <name> — Switch packs before previewing
  • peon notifications test — Test desktop notifications (separate from sounds)

Build docs developers (and LLMs) love

Get started for freeTalk to us