CLI Reference

Complete reference for all claudelint commands, options, and usage patterns.

Primary Commands
- check-all - Run all validators (main command)
- init - Initialize configuration
Config Management
- print-config - View resolved configuration
- resolve-config - Config for specific file
- validate-config - Validate config file
Rule Management
- list-rules - Browse available rules
- explain - Full documentation for a rule
Deprecation Management
- check-deprecated - Check for deprecated rules
- migrate - Migrate deprecated rules
Cache Management
- cache-clear - Clear validation cache
Individual Validators - Run specific validators
Formatting
- format - Format files
Development
- watch - Watch for changes and re-validate
- install-plugin - Plugin installation guide
Exit Codes

Primary Commands

check-all

Run all validators on your Claude Code project. This is the default command -- running claudelint with no arguments is equivalent to claudelint check-all.

Usage:

bash

# These are equivalent:
claudelint
claudelint check-all [options]

Options:

Option	Description	Default
`--cwd <path>`	Run as if claudelint was started in this directory	Current directory
`-v, --verbose`	Show detailed output including skipped validators and timing	`false`
`-q, --quiet`	Suppress warnings, show only errors	`false`
`--format <format>`	Output format: `stylish`, `json`, `compact`, `sarif`, or `github`	`stylish`
`--config <path>`	Path to custom config file	Auto-detect
`--no-config`	Disable configuration file loading	-
`--preset <name>`	Built-in preset when no config file: `recommended`, `strict`, or `all`	`recommended`
`--strict`	Exit with error on any issues (errors, warnings, or info)	`false`
`--max-warnings <number>`	Fail if warning count exceeds this limit	Unlimited
`--no-collapse`	Show all issues without collapsing repeated rules	`false`
`--warnings-as-errors`	Treat all warnings as errors	`false`
`--explain`	Show Why: and Fix: lines under each issue (Tier 2 progressive disclosure)	`false`
`--fix`	Automatically fix problems	`false`
`--fix-dry-run`	Preview fixes without applying them	`false`
`--fix-type <type>`	Fix `errors`, `warnings`, or `all`	`all`
`--cache`	Enable validation caching	`true`
`--no-cache`	Disable validation caching	-
`--cache-location <path>`	Cache directory location	`.claudelint-cache`
`--color`	Force color output	Auto-detect
`--no-color`	Disable color output	-
`--debug-config`	Show configuration loading debug info	`false`
`--show-docs-url`	Show documentation URLs for rules	`false`
`--fast`	Fast mode: skip expensive checks	`false`
`--no-deprecated-warnings`	Suppress warnings about deprecated rules	`false`
`--error-on-deprecated`	Treat usage of deprecated rules as errors	`false`
`--timing`	Show per-validator timing breakdown	`false`
`--allow-empty-input`	Exit 0 when no files are found to check	`false`
`-o, --output-file <path>`	Write results to file (in addition to stdout)	-
`--ignore-pattern <pattern>`	Additional pattern to ignore (repeatable)	-
`--no-ignore`	Disable ignore file and pattern processing	`false`
`--rule <rule:severity>`	Override rule severity from CLI (repeatable)	-
`--cache-strategy <strategy>`	Cache invalidation strategy: `metadata` or `content`	`metadata`
`--changed`	Only check files with uncommitted git changes	`false`
`--since <ref>`	Only check files changed since a git ref (branch, tag, or SHA)	-
`--stats`	Include per-rule statistics in output	`false`
`--stdin`	Read input from stdin instead of files	`false`
`--stdin-filename <path>`	Provide filename context for stdin input (e.g., `CLAUDE.md`)	-
`--workspace <name>`	Validate specific workspace package by name	-
`--workspaces`	Validate all workspace packages	`false`

Examples:

bash

# Basic validation
claudelint check-all

# Verbose with explanations and timing
claudelint check-all --verbose --explain --timing

# CI mode: JSON output, strict, fail on any warnings
claudelint check-all --format json --strict --max-warnings 0

# GitHub Actions annotations
claudelint check-all --format github

# Preview auto-fixes, then apply
claudelint check-all --fix-dry-run
claudelint check-all --fix

# Only check uncommitted changes
claudelint check-all --changed

# Only check files changed since a branch
claudelint check-all --since main

# Lint a different project
claudelint check-all --cwd /path/to/project

# Run all rules without a config file
claudelint check-all --preset all

# Override rule severity from CLI
claudelint check-all --rule skill-name:error --rule claude-md-size:off

# Pipe JSON to jq (status messages go to stderr)
claudelint check-all --format json | jq '.[] | select(.errorCount > 0)'

# Validate from stdin (editor integration)
cat CLAUDE.md | claudelint check-all --stdin --stdin-filename CLAUDE.md

See Exit Codes for return values.

init

Initialize claudelint configuration for your project. Interactive wizard that detects your project structure and generates appropriate config files.

Usage:

bash

claudelint init [options]

Options:

Option	Description
`-y, --yes`	Use default configuration without prompts (non-interactive mode)
`--force`	Overwrite existing configuration files
`--hooks`	Create a SessionStart validation hook for Claude Code
`--preset <name>`	Preset to use with `--yes`: `recommended`, `strict`, or `all` (default: `recommended`)

Examples:

bash

# Interactive setup (recommended)
claudelint init

# Non-interactive with defaults
claudelint init --yes

# Non-interactive with SessionStart hook
claudelint init --yes --hooks

# Non-interactive with strict preset
claudelint init --yes --preset strict --hooks

# Overwrite existing config
claudelint init --yes --force

What it creates:

.claudelintrc.json - Configuration file with rules
.claudelintignore - Patterns for files to ignore
.claude/hooks/hooks.json - SessionStart validation hook (with --hooks)
Optional: npm scripts in package.json

Config Management

print-config

Display the resolved configuration that claudelint is using. Useful for debugging config file loading and cascading.

Usage:

bash

claudelint print-config [options]

Options:

Option	Description	Default
`--format <format>`	Output format: `json` or `table`	`json`
`--config <path>`	Path to config file to print	Auto-detect

Examples:

bash

# Print config as JSON
claudelint print-config

# Print config as table
claudelint print-config --format table

# Print specific config file
claudelint print-config --config custom.json

resolve-config

Show the effective configuration for a specific file. Takes into account config file cascading, overrides, and file-specific rules.

Usage:

bash

claudelint resolve-config <file> [options]

Arguments:

<file> - Path to the file to resolve config for

Options:

Option	Description	Default
`--format <format>`	Output format: `json` or `table`	`json`
`--config <path>`	Path to config file	Auto-detect

Examples:

bash

# Resolve config for CLAUDE.md
claudelint resolve-config .claude/CLAUDE.md

# Resolve config for a skill
claudelint resolve-config .claude/skills/test/test.sh

# Table format
claudelint resolve-config .claude/CLAUDE.md --format table

validate-config

Validate a configuration file against the claudelint schema. Checks for unknown rules, invalid options, and schema violations.

Usage:

bash

claudelint validate-config [options]

Options:

Option	Description	Default
`--config <path>`	Path to config file to validate	Auto-detect

Examples:

bash

# Validate default config
claudelint validate-config

# Validate specific config
claudelint validate-config --config custom.json

Rule Management

list-rules

List all available validation rules with their metadata (severity, category, fixable status).

Usage:

bash

claudelint list-rules [options]

Options:

Option	Description	Default
`--category <category>`	Filter by category: `CLAUDE.md`, `Skills`, `Settings`, `Hooks`, `MCP`, `Plugin`	All
`--fixable`	Show only rules that support auto-fix	`false`
`--format <format>`	Output format: `table` or `json`	`table`

Examples:

bash

# List all rules
claudelint list-rules

# List only Skills rules
claudelint list-rules --category Skills

# List only fixable rules
claudelint list-rules --fixable

# Combine filters
claudelint list-rules --category Skills --fixable

# JSON output
claudelint list-rules --format json

Output includes:

Rule ID
Rule name
Description
Category
Severity (error, warning)
Fixable status

explain

Display the full documentation for a specific rule, including summary, details, examples, fix instructions, and metadata. This is Tier 3 of the progressive disclosure model.

Usage:

bash

claudelint explain <rule-id>

Arguments:

<rule-id> - The ID of the rule to explain (e.g., skill-name, claude-md-size)

Examples:

bash

# Show full docs for a rule
claudelint explain skill-frontmatter-unknown-keys

# Show docs for a CLAUDE.md rule
claudelint explain claude-md-import-missing

Output includes:

Rule title and summary
Detailed explanation
How to fix
Incorrect and correct examples
Metadata (severity, category, fixable, since version, docs URL)
When not to use (if applicable)
Related rules

Exit Codes:

0 - Rule found and documentation displayed
1 - Rule not found (shows available rule categories)

Progressive disclosure model:

Tier	Command	What it shows
1	`claudelint check-all`	Problem + rule ID (table format)
2	`claudelint check-all --explain`	Why: + Fix: lines per issue
3	`claudelint explain <rule-id>`	Full documentation page

Deprecation Management

check-deprecated

Check your configuration file for deprecated rules that need to be updated or removed.

Usage:

bash

claudelint check-deprecated [options]

Options:

Option	Description	Default
`--config <path>`	Path to config file	Auto-detect
`--format <format>`	Output format: `table` or `json`	`table`

Examples:

bash

# Check current config for deprecated rules
claudelint check-deprecated

# Check specific config file
claudelint check-deprecated --config .claudelintrc.json

# JSON output for CI/CD
claudelint check-deprecated --format json

Output includes:

Rule ID
Deprecation reason
Replacement rule(s)
Deprecated since version
Removal version (if scheduled)
Migration guide URL (if available)

Exit codes:

0 - No deprecated rules found
1 - Deprecated rules found (needs attention)
2 - Error (invalid config, file not found, etc.)

migrate

Automatically migrate deprecated rules in your configuration file. Auto-replaces 1:1 rule renames, warns when manual intervention is needed (1:many splits or removals).

Usage:

bash

claudelint migrate [options]

Options:

Option	Description	Default
`--config <path>`	Path to config file	Auto-detect
`--dry-run`	Preview changes without writing to file	`false`
`--format <format>`	Output format: `table` or `json`	`table`

Examples:

bash

# Preview what would change
claudelint migrate --dry-run

# Apply migrations
claudelint migrate

Exit codes:

0 - Successfully migrated (or no deprecated rules found)
1 - Manual intervention needed (multiple replacements)
2 - Error (invalid config, file not found, etc.)

Cache Management

cache-clear

Clear the validation cache. Use this if you're seeing stale validation results or after upgrading claudelint.

Usage:

bash

claudelint cache-clear [options]

Options:

Option	Description	Default
`--cache-location <path>`	Cache directory to clear	`.claudelint-cache`

Examples:

bash

# Clear default cache
claudelint cache-clear

# Clear custom cache location
claudelint cache-clear --cache-location /tmp/my-cache

When to use:

After upgrading claudelint
After changing rules or config
If seeing stale validation results
Before CI/CD runs (optional)

Individual Validators

Run a specific validator instead of all at once. Usage: claudelint validate-<type> [options]

Shared Options (available on all validators):

Option	Description	Default
`--path <path>`	Custom path to the target file or directory	Auto-detect
`-v, --verbose`	Verbose output	`false`
`--warnings-as-errors`	Treat warnings as errors	`false`
`-c, --config <path>`	Path to configuration file	Auto-detect
`--no-config`	Disable configuration file loading	-
`--max-warnings <number>`	Fail if warning count exceeds this limit	Unlimited
`--no-collapse`	Show all issues without collapsing repeated rules	`false`

Available validators:

Command	Validates
`validate-claude-md`	CLAUDE.md files (supports `--explain`)
`validate-skills`	Skill structure and frontmatter (supports `--skill <name>`)
`validate-agents`	Agent structure and frontmatter
`validate-hooks`	hooks.json files
`validate-mcp`	MCP server configuration
`validate-settings`	settings.json files
`validate-plugin`	Plugin manifest files
`validate-lsp`	LSP configuration
`validate-output-styles`	Output style structure and frontmatter
`validate-commands`	Deprecated commands (suggests migration to skills)

Examples:

bash

# Validate CLAUDE.md with explanations
claudelint validate-claude-md --verbose --explain

# Validate a specific skill
claudelint validate-skills --skill my-skill

# Validate hooks with custom path
claudelint validate-hooks --path ./config/hooks.json

# Any validator with shared options
claudelint validate-mcp --warnings-as-errors --max-warnings 0

Formatting

format

Format Claude Code files using a three-tier formatting pipeline:

markdownlint - CLAUDE.md and skill markdown files
prettier - Markdown, JSON, and YAML files
shellcheck - Shell scripts (optional, requires system install)

Usage:

bash

claudelint format [options]

Options:

Option	Description	Default
`--check`	Check formatting without making changes	`false`
`--fix`	Apply formatting fixes	`true`
`--fix-dry-run`	Preview what would be fixed without writing	`false`
`-v, --verbose`	Show detailed output per file	`false`

Modes:

Default (no flags): Apply fixes and write corrected files
--check: Report pass/fail without modifying files
--fix-dry-run: Report which files would change, without writing

Examples:

bash

# Check formatting (no changes)
claudelint format --check

# Preview what would be fixed
claudelint format --fix-dry-run

# Apply formatting fixes
claudelint format --fix

# Verbose output to see per-file results
claudelint format --verbose

See File Discovery for the full list of file patterns discovered by claudelint.

Development

watch

Watch for file changes and automatically re-validate. Runs an initial full validation, then monitors the working directory and triggers only the relevant validators when files change.

Usage:

bash

claudelint watch [options]

Options:

Option	Description	Default
`-v, --verbose`	Verbose output	`false`
`--warnings-as-errors`	Treat warnings as errors	`false`
`-c, --config <path>`	Path to configuration file	Auto-detect
`--no-config`	Disable configuration file loading	-
`--debounce <ms>`	Debounce interval in milliseconds	`300`

File triggers:

Changes to specific files trigger only the relevant validator:

File Pattern	Validator Triggered
`CLAUDE.md`	CLAUDE.md validator
`SKILL.md`, `*.sh`	Skills validator
`settings.json`	Settings validator
`hooks.json`	Hooks validator
`.mcp.json`	MCP validator
`plugin.json`	Plugin validator

Changes to other .md, .json, or .sh files trigger all validators. Files in node_modules/ and .claudelint-cache/ are ignored.

Examples:

bash

# Start watching with defaults
claudelint watch

# Custom debounce for slower file systems
claudelint watch --debounce 500

# Watch with specific config
claudelint watch --config strict.json

# Watch with warnings treated as errors
claudelint watch --warnings-as-errors

Press Ctrl+C to stop watching.

install-plugin

Show instructions for installing claudelint as a Claude Code plugin. Auto-detects whether claudelint is installed locally in node_modules and shows the appropriate installation command.

Usage:

bash

claudelint install-plugin

No options. This is an informational command that prints installation instructions.

Output varies based on context:

Shows claude --plugin-dir ./node_modules/claude-code-lint for local loading
Shows marketplace install syntax for distribution

See the Claude Code Plugin Guide for detailed setup instructions.

Output Streams

claudelint separates data output from status messages for clean piping:

stdout: Lint results (formatted output from --format json, --format sarif, --format github)
stderr: Status messages, progress indicators, timing info, "Using config file: ..."

This enables piping to other tools:

bash

# Pipe JSON to jq
claudelint check-all --format json | jq '.[] | select(.errorCount > 0)'

# Save SARIF while still seeing progress
claudelint check-all --format sarif > results.sarif

# GitHub annotations to stdout, progress to stderr
claudelint check-all --format github

Environment Variables

Variable	Description
`NO_COLOR`	Disable color output (respected per no-color.org standard)
`FORCE_COLOR`	Force color output even when not a TTY
`CI`	Suppress update notifications when running in CI environments
`NO_UPDATE_NOTIFIER`	Suppress update notifications explicitly

Color is auto-detected based on TTY status. The --color and --no-color flags override environment variables.

claudelint checks the npm registry for newer versions once every 24 hours and displays a notification if an update is available. Set CI=true or NO_UPDATE_NOTIFIER=1 to suppress this behavior.

Exit Codes

claudelint uses standard POSIX exit codes:

Exit Code	Meaning	When It Happens
`0`	Success	No issues found, all checks passed
`1`	Issues found	Errors or warnings detected (depending on flags)
`2`	Fatal error	Invalid config, command failure, or internal error
`130`	Interrupted	Process terminated by SIGINT (Ctrl+C) or SIGTERM

Exit code 1 is returned when:

Any errors are found (always)
Warnings are found AND --warnings-as-errors is set
Any issues are found AND --strict is set
Warning count exceeds --max-warnings threshold

Exit code 0 is returned when:

No errors or warnings found
Only warnings found (without --warnings-as-errors or --strict)
Warnings found but under --max-warnings threshold

Exit code 2 is returned when:

Config file is invalid or cannot be loaded
Command syntax is incorrect
Internal error or exception occurs

CLI Reference

Table of Contents

Primary Commands

check-all

init

Config Management

print-config

resolve-config

validate-config

Rule Management

list-rules

explain

Deprecation Management

check-deprecated

migrate

Cache Management

cache-clear

Individual Validators

Formatting

format

Development

watch

install-plugin

Output Streams

Environment Variables

Exit Codes

See Also

CLI Reference ​

Table of Contents ​

Primary Commands ​

check-all ​

init ​

Config Management ​

print-config ​

resolve-config ​

validate-config ​

Rule Management ​

list-rules ​

explain ​

Deprecation Management ​

check-deprecated ​

migrate ​

Cache Management ​

cache-clear ​

Individual Validators ​

Formatting ​

format ​

Development ​

watch ​

install-plugin ​

Output Streams ​

Environment Variables ​

Exit Codes ​

See Also ​

CLI Reference

Table of Contents

Primary Commands

check-all

init

Config Management

print-config

resolve-config

validate-config

Rule Management

list-rules

explain

Deprecation Management

check-deprecated

migrate

Cache Management

cache-clear

Individual Validators

Formatting

format

Development

watch

install-plugin

Output Streams

Environment Variables

Exit Codes

See Also