CLI reference

All commands and flags

On this page

Overview
Global flags
init
validate
backup
doctor
audit
update
version
completion

Overview

klaudiush is invoked as a Claude Code hook. It reads JSON from stdin, validates the operation, and writes JSON to stdout. The CLI also has commands for config management and diagnostics.

Global flags

These flags apply to the root command and affect all operations.

klaudiush --hook-type PreToolUse    # Required: hook event type
klaudiush --debug                   # Enable debug logging
klaudiush --trace                   # Enable trace logging
klaudiush --config ./custom.toml    # Custom project config path
klaudiush --global-config ~/.config/klaudiush.toml
klaudiush --disable commit,markdown # Disable specific validators
klaudiush --no-color                # Disable colored output

Flag	Description
`--hook-type`	Hook event type: PreToolUse, PostToolUse, Notification
`--debug`	Enable debug logging to dispatcher.log
`--trace`	Enable verbose trace logging
`--config`	Custom project config path
`--global-config`	Custom global config path
`--disable`	Comma-separated list of validators to disable
`--no-color`	Disable colored output

init

Create a configuration file with interactive prompts. Detects your git author info and sets up defaults. Project configs are automatically added to .git/info/exclude.

# Initialize project config (interactive)
klaudiush init

# Initialize global config
klaudiush init --global

# Overwrite existing config (creates backup first)
klaudiush init --force

# Non-interactive mode
klaudiush init --no-tui

Flag	Description
`--global, -g`	Create global config at $XDG_CONFIG_HOME/klaudiush/config.toml
`--force, -f`	Overwrite existing config (creates backup first)
`--no-tui`	Non-interactive mode with defaults

validate

The root command with --hook-type runs validation. This is what Claude Code calls via the hook. You can test it manually by piping JSON to stdin.

# Validate via hook (normal usage - called by Claude Code)
echo '{"tool_name":"Bash","command":"git commit -m fix"}' | klaudiush --hook-type PreToolUse

backup

Manage configuration backups. Automatic backups are created on config changes. Manual backups can be tagged for easy identification.

klaudiush backup list                      # List all backups
klaudiush backup list --global             # Global config backups only
klaudiush backup list --json               # JSON output
klaudiush backup create --tag "pre-refactor"  # Manual backup
klaudiush backup restore abc123 --dry-run  # Preview restore
klaudiush backup restore abc123            # Restore snapshot
klaudiush backup delete abc123             # Delete snapshot
klaudiush backup prune                     # Remove old backups
klaudiush backup status                    # Show backup system status

doctor

Run diagnostic checks on your setup. Checks binary availability, hook registration, config validity, backup health, and tool dependencies.

klaudiush doctor                    # Run all checks
klaudiush doctor --verbose          # Detailed output
klaudiush doctor --fix              # Auto-fix issues
klaudiush doctor --category config  # Check specific category

audit

Manage the exception audit log. View entries, filter by error code or outcome, and clean up old data.

klaudiush audit list                       # List all entries
klaudiush audit list --error-code GIT019   # Filter by code
klaudiush audit list --outcome allowed     # Filter by outcome
klaudiush audit list --json                # JSON output
klaudiush audit stats                      # Show statistics
klaudiush audit cleanup                    # Remove old entries

update

Update klaudiush to the latest (or a specific) version from GitHub Releases. Downloads the release archive, verifies the SHA256 checksum, and atomically replaces the current binary. Resolves symlinks, so it works with Homebrew installs too.

klaudiush update                    # Update to latest version
klaudiush update --to v1.18.0       # Update to specific version
klaudiush update --check            # Check for updates without installing
klaudiush update --to v1.18.0 --check  # Check if specific version exists

Flag	Description
`--to`	Target version (e.g. v1.18.0). Omit to get latest
`--check`	Only check for updates, don't install

Set GH_TOKEN or GITHUB_TOKEN to avoid GitHub API rate limits. Falls back to gh auth token if available. Times out after 5 minutes.

version

Print version info including commit hash, build date, Go version, and platform.

$ klaudiush version
klaudiush v1.20.0
  commit:  a1b2c3d
  built:   2026-02-20T10:00:00Z
  go:      go1.24.0
  os/arch: darwin/arm64

completion

Generate shell completion scripts. Supports bash, zsh, fish, and PowerShell.

klaudiush completion bash        # Generate bash completions
klaudiush completion zsh         # Generate zsh completions
klaudiush completion fish        # Generate fish completions
klaudiush completion powershell  # Generate PowerShell completions