CLI Reference

conclaude provides a command-line interface for initializing configuration, validating settings, and handling Claude Code lifecycle hooks.

Global Options

These options apply to all commands:

Option	Description
--version	Print version information
--help	Print help information

Commands

init

Initialize conclaude configuration and Claude Code hooks in the current directory.

conclaude init [OPTIONS]

Options:

Option	Description
--config-path <PATH>	Custom path for .conclaude.yaml file
--claude-path <PATH>	Custom path for .claude directory
-f, --force	Overwrite existing configuration files
--schema-url <URL>	Custom schema URL for YAML language server header

Examples:

# Initialize with defaults
conclaude init

# Force overwrite existing config
conclaude init --force

# Custom configuration path
conclaude init --config-path ./config/conclaude.yaml

Created Files:

• .conclaude.yaml — Project configuration with YAML language server support
• .claude/settings.json — Claude Code hook configuration (created or updated)

---

validate

Validate conclaude configuration file syntax and schema compliance.

conclaude validate [OPTIONS]

Options:

Option	Description
--config-path <PATH>	Path to configuration file or directory to validate

Examples:

# Validate default configuration
conclaude validate

# Validate specific file
conclaude validate --config-path ./production.yaml

# Use in CI scripts
conclaude validate && echo "Config valid" || exit 1

Exit Codes:

Code	Meaning
0	Configuration is valid
1	Validation failed (syntax error, schema violation, file not found)

---

visualize

Display file and directory protection settings from configuration.

conclaude visualize [OPTIONS]

Options:

Option	Description
-r, --rule <RULE>	Specific rule to visualize
--show-matches	Show files that match the rule patterns

Available Rules:

• uneditableFiles — Files protected from editing
• preventRootAdditions — Root directory protection status
• toolUsageValidation — Tool-specific validation rules

Examples:

# Show all rules overview
conclaude visualize

# Show specific rule details
conclaude visualize --rule uneditableFiles

# Show matching files
conclaude visualize --rule uneditableFiles --show-matches

---

Hook Commands

These commands are called by Claude Code during session lifecycle events. They read JSON payloads from stdin and output results.

PreToolUse

Fired before Claude uses any tool (Write, Bash, Read, etc.).

echo '{"session_id":"...","tool_name":"Write",...}' | conclaude PreToolUse

Use Cases:

• Block file creation at project root
• Protect files from editing
• Validate tool inputs

---

PostToolUse

Fired after a tool operation completes.

echo '{"session_id":"...","tool_name":"Write",...}' | conclaude PostToolUse

Use Cases:

• Audit logging
• Performance monitoring
• Post-processing validation

---

Stop

Fired when Claude finishes a task and the session is about to end.

echo '{"session_id":"...","stop_hook_active":true,...}' | conclaude Stop

Use Cases:

• Run linting and formatting checks
• Execute test suites
• Verify build succeeds
• Continuous validation (infinite mode)

---

SessionStart

Fired when a Claude Code session begins.

echo '{"session_id":"...",...}' | conclaude SessionStart

Use Cases:

• Initialize session logging
• Set up monitoring
• Prepare workspace

---

UserPromptSubmit

Fired when the user submits input to Claude.

echo '{"session_id":"...","prompt":"...",...}' | conclaude UserPromptSubmit

Use Cases:

• Log user prompts
• Pre-process input

---

SubagentStart

Fired when a Claude subagent (coder, tester, etc.) begins work.

echo '{"session_id":"...","agent_id":"coder",...}' | conclaude SubagentStart

Use Cases:

• Track subagent initialization
• Resource allocation
• Monitoring setup

---

SubagentStop

Fired when a Claude subagent completes its work.

echo '{"session_id":"...","agent_id":"coder",...}' | conclaude SubagentStop

Use Cases:

• Log subagent completion
• Cleanup operations
• Metrics collection

---

Notification

Fired for system notifications.

echo '{"session_id":"...",...}' | conclaude Notification

---

PreCompact

Fired before transcript compaction.

echo '{"session_id":"...",...}' | conclaude PreCompact

---

PermissionRequest

Fired when a tool requests permission.

echo '{"session_id":"...",...}' | conclaude PermissionRequest

---

SessionEnd

Fired when a session terminates.

echo '{"session_id":"...",...}' | conclaude SessionEnd

---

Exit Codes

All hook commands use consistent exit codes:

Code	Meaning
0	Success — operation allowed to proceed
1	Error — validation failure, parsing error, or handler crash
2	Blocked — hook explicitly blocked the operation

Environment Variables

Configuration

Variable	Description
CONCLAUDE_LOG_LEVEL	Log level: debug, info, warn, error
CONCLAUDE_DISABLE_FILE_LOGGING	Disable logging to temporary files

Hook Context

Available to commands executed by hooks:

Variable	Description
CONCLAUDE_SESSION_ID	Unique session identifier
CONCLAUDE_TRANSCRIPT_PATH	Path to session transcript file
CONCLAUDE_CWD	Current working directory
CONCLAUDE_HOOK_EVENT	Name of executing hook
CONCLAUDE_CONFIG_DIR	Directory containing config file

Subagent Hooks

Additional variables for SubagentStart and SubagentStop:

Variable	Description
CONCLAUDE_AGENT_ID	Raw agent identifier (e.g., “adb0a8b”)
CONCLAUDE_AGENT_NAME	Semantic agent name (e.g., “coder”, “tester”, “stuck”) extracted from main transcript. Falls back to CONCLAUDE_AGENT_ID if extraction fails. (SubagentStop only)
CONCLAUDE_SUBAGENT_TYPE	Subagent type (e.g., “implementation”) (SubagentStart only)
CONCLAUDE_AGENT_TRANSCRIPT_PATH	Path to subagent transcript
CONCLAUDE_PERMISSION_MODE	Permission mode (SubagentStart only)