CLI Reference

Complete documentation for all Claudio commands and options.

claudio install

Installs Claudio hooks into Claude Code settings to enable audio feedback.

Usage

claudio install [flags]

Flags

–scope, -s string (default: “user”)
Installation scope for hooks
Options: user, project
user: Install in personal Claude Code settings (affects all sessions)
project: Install in current project’s Claude Code settings (project-specific)
–dry-run, -d boolean (default: false)
Show what would be done without making changes (simulation mode)
Useful for testing installation before committing changes
–quiet, -q boolean (default: false)
Suppress output (no progress messages)
Shows only essential information and errors
–print, -p boolean (default: false)
Print configuration that would be written
Shows installation details without performing installation

Examples

Basic installation:

claudio install

Test what would be installed:

claudio install --dry-run

Standard installation (overwrites existing Claudio hooks):

claudio install --scope user

Project-specific installation:

claudio install --scope project

Silent installation:

claudio install --quiet --scope user

Show configuration details:

claudio install --print --scope user

Installation Process

The install command performs these steps:

  1. Find Claude Code settings - Locates settings file for specified scope
  2. Read existing settings - Safely reads current configuration with file locking
  3. Generate Claudio hooks - Creates hooks for PreToolUse, PostToolUse, UserPromptSubmit
  4. Merge configurations - Combines Claudio hooks with existing settings
  5. Write updated settings - Saves merged configuration with file locking
  6. Verify installation - Confirms all hooks were installed correctly

claudio analyze

Analyze sound usage patterns and identify missing sounds from tracking database.

claudio analyze usage

Show actual sound playback statistics and patterns.

claudio analyze usage [flags]

Flags

–days int (default: 7)
Number of days to analyze (0 = all time)
–preset string
Date range preset: today, yesterday, last-week, this-month, all-time
–tool string
Filter by specific tool name (e.g., Edit, Bash)
–category string
Filter by sound category: success, error, loading, interactive
–limit int (default: 20)
Maximum results to show
–show-summary
Display usage summary statistics
–show-fallbacks
Show fallback level distribution (sound coverage quality)

Examples

# Recent usage overview
claudio analyze usage

# Detailed analysis with fallback stats
claudio analyze usage --show-summary --show-fallbacks

# Check Edit tool performance last week
claudio analyze usage --tool Edit --preset last-week

# Error sound usage this month
claudio analyze usage --category error --preset this-month

claudio analyze missing

Show sounds that were requested but not found in soundpack.

claudio analyze missing [flags]

Flags

–days int (default: 7)
Number of days to analyze (0 = all time)
–preset string
Date range preset: today, yesterday, last-week, this-month, all-time
–tool string
Filter by specific tool name
–category string
Filter by sound category
–limit int (default: 20)
Maximum results to show

Examples

# Find missing sounds from last week
claudio analyze missing --preset last-week

# Missing error sounds for Bash tool
claudio analyze missing --tool Bash --category error

# All missing sounds ever
claudio analyze missing --preset all-time --limit 50

claudio uninstall

Removes Claudio hooks from Claude Code settings to disable audio feedback.

Usage

claudio uninstall [flags]

Flags

–scope, -s string (default: “user”)
Uninstall scope for hook removal
Options: user, project
user: Remove from personal Claude Code settings
project: Remove from current project’s Claude Code settings
–dry-run, -d boolean (default: false)
Show what would be removed without making changes (simulation mode)
Lists hooks that would be removed
–quiet, -q boolean (default: false)
Suppress output (no progress messages)
Shows only essential information and errors
–print, -p boolean (default: false)
Print hooks that would be removed
Shows uninstall details without performing removal

Examples

Basic uninstall:

claudio uninstall --scope user

Test what would be removed:

claudio uninstall --dry-run --scope user

Standard removal:

claudio uninstall --scope user

Project-specific removal:

claudio uninstall --scope project

Show what hooks would be removed:

claudio uninstall --print --scope user

Uninstall Process

The uninstall command performs these steps:

  1. Find Claude Code settings - Locates settings file for specified scope
  2. Read existing settings - Safely reads current configuration
  3. Detect Claudio hooks - Identifies which hooks belong to Claudio
  4. Remove Claudio hooks - Removes only Claudio-specific hook entries
  5. Write updated settings - Saves configuration with Claudio hooks removed
  6. Verify removal - Confirms all Claudio hooks were successfully removed

claudio (hook execution)

Claudio can also be called directly as a hook processor (this is what Claude Code calls automatically).

Usage

echo '{"hook_event_name":"PostToolUse",...}' | claudio [flags]

Hook Execution Flags

–volume float (default: from config)
Audio playback volume (0.0 to 1.0)
Overrides configuration file volume setting
–silent boolean (default: false)
Run in silent mode (no audio output)
Useful for testing without sound
–soundpack string (default: from config)
Soundpack to use for audio
Overrides configuration file soundpack setting

Environment Variables

Claudio respects these environment variables:

CLAUDIO_VOLUME
Sets audio volume (0.0 to 1.0)
Example: export CLAUDIO_VOLUME=0.7
CLAUDIO_ENABLED
Enable/disable Claudio entirely
Example: export CLAUDIO_ENABLED=false
CLAUDIO_SOUNDPACK
Default soundpack to use
Example: export CLAUDIO_SOUNDPACK=custom
CLAUDIO_LOG_LEVEL
Logging verbosity
Options: debug, info, warn, error
Example: export CLAUDIO_LOG_LEVEL=debug

Global Options

These options work with all commands:

–help, -h
Show help for the command
–version
Show Claudio version information

Exit Codes

Settings File Locations

Claudio automatically discovers Claude Code settings:

User Scope:

Project Scope:

Hook Events

Claudio responds to these Claude Code hook events:

PreToolUse
Triggered before Claude Code runs a tool
Plays “thinking” or “loading” sounds
PostToolUse
Triggered after Claude Code completes a tool
Plays “success” or “error” sounds based on tool result
UserPromptSubmit
Triggered when you send a message to Claude Code
Plays “interactive” or “message-sent” sounds

See Also