CLI Reference

Complete reference for the han command-line tool.

The han command-line tool is the primary interface for managing plugins, running hooks, and interacting with Han's features outside of Claude Code sessions.

Installation

Install the CLI via Homebrew or curl:

# Homebrew
brew install thebushidocollective/tap/han

# Or via curl
curl -fsSL https://han.guru/install.sh | bash

Alternatively, the CLI is automatically installed to ~/.claude/bin/han when you start a Claude Code session with the core plugin.

Command Categories

Plugin Commands

Manage Han plugins: install, list, uninstall, and search.

han plugin install <plugin-name>
han plugin list
han plugin uninstall <plugin-name>

Hook Commands

Run and manage validation hooks.

han hook run <plugin> <hook>
han hook list

Other Commands

Version, help, and update commands.

han --version
han --help
han update

Global Options

All commands support these global options:

OptionDescription
--helpShow help for the command
-V, --versionShow Han version

Environment Variables

Han respects these environment variables:

VariableDescription
HAN_DISABLE_HOOKSSet to 1 or true to disable all hooks
HAN_HOOK_RUN_VERBOSESet to 1 or true to enable verbose hook output
HAN_NO_CACHESet to 1 to disable smart caching (force hooks to run)
HAN_NO_FAIL_FASTSet to 1 to continue running hooks even after failures
HAN_NO_CHECKPOINTSSet to 1 to disable checkpoint-based filtering
HAN_CHECKPOINT_TYPECheckpoint type for filtering (session or agent)
HAN_CHECKPOINT_IDCheckpoint ID for filtering hooks
CLAUDE_CODE_ENABLE_TELEMETRYSet to 1 to enable OpenTelemetry export
OTEL_EXPORTER_OTLP_ENDPOINTOpenTelemetry collector endpoint

Note: Environment variables override han.yml settings at runtime.

See OpenTelemetry for more telemetry variables.

Exit Codes

CodeMeaning
0Success
1General error
2Invalid command or arguments

Learn More