CLI Reference¶

Complete reference for all linthis commands and options.

Main Command¶

linthis [OPTIONS] [COMMAND]

Global Options¶

Short	Long	Description	Example
`-i`	`--include`	Files/directories to check	`-i src -i lib`
`-e`	`--exclude`	Patterns to exclude	`-e "*.test.js"`
`-c`	`--check-only`	Check only, no formatting	`-c`
`-f`	`--format-only`	Format only, no checking	`-f`
`-s`	`--staged`	Check Git staged files only	`-s`
`-m`	`--modified`	Check all locally modified files (staged + unstaged)	`-m`
	`--checks`	Checks to run (comma-separated)	`--checks lint,security`
`-l`	`--lang`	Languages (comma-separated)	`-l python,rust`
`-o`	`--output`	Output format	`-o json`
`-v`	`--verbose`	Verbose output	`-v`
`-q`	`--quiet`	Quiet mode (errors only)	`-q`
	`--config`	Config file path	`--config custom.toml`
	`--preset`	Format preset	`--preset google`
	`--no-default-excludes`	Disable default excludes
	`--no-gitignore`	Disable .gitignore rules
	`--no-plugin`	Skip loading plugins

Output Formats¶

human - Human-readable (default)
json - JSON format
github-actions - GitHub Actions annotations

init¶

Initialize configuration files.

linthis init [OPTIONS]

Option	Description
`-g, --global`	Create global config
`--with-hook`	Also install git hook
`--force`	Force overwrite existing

Examples:

linthis init                    # Create .linthis.toml
linthis init -g                 # Create ~/.linthis/config.toml
linthis init --with-hook        # Init config and install hook

hook¶

Manage Git hooks.

hook add¶

linthis hook add [OPTIONS]

Alias: linthis hook install (hidden, kept for backward compatibility)

Option	Description
`--type`	Hook type: `git` (default), `git-with-agent`, `agent`, `prek`, `prek-with-agent`
`--event`	Hook event: `pre-commit` (default), `pre-push`, `commit-msg`
`--args`	Extra arguments for the linthis command in hook script (default: `-c -f`, check + format)
`-g, --global`	Add globally: agent type → user home dir; others → `~/.config/git/hooks/` + `core.hooksPath`
`--provider`	AI provider: `claude`, `codex`, `gemini`, `cursor`, `droid`, `auggie`, `codebuddy`. Supports `provider/model` syntax (e.g. `claude/opus`). For `--type agent`: installs rules/settings files. For `*-with-agent`: uses headless CLI to auto-fix.
`--provider-args`	Extra arguments passed to the AI agent CLI (e.g. `"--model opus"`). Merged with model from `provider/model` syntax if both specified.
`--force`	Force overwrite existing
`-y, --yes`	Non-interactive mode

Examples:

# Project-level hooks
linthis hook add                                           # Default git hook (check + format)
linthis hook add --event pre-push                         # Pre-push hook
linthis hook add --event commit-msg                       # Commit message format hook
linthis hook add --args "-c"                              # Check-only hook
linthis hook add --type git-with-agent --provider claude  # git hook + AI auto-fix on failure
linthis hook add --type agent --provider claude           # Agent integration

# Global hooks (apply to all repos on this machine)
linthis hook add --global                                 # Global git pre-commit
linthis hook add --global --event commit-msg              # Global commit-msg hook
linthis hook add --global --type git-with-agent --provider claude  # Global + AI auto-fix
linthis hook add --type agent --provider claude --global  # AI agent rules (user home)

hook remove¶

linthis hook remove [OPTIONS]

Alias: linthis hook uninstall (hidden, kept for backward compatibility)

Option	Description
`--event`	Hook event to remove
`-g, --global`	Remove global hook
`--all`	Remove all hooks
`-y, --yes`	Non-interactive mode

Examples:

linthis hook remove                  # Remove project pre-commit hook
linthis hook remove --global         # Remove global pre-commit hook
linthis hook remove --global --all   # Remove all global hooks

hook status¶

linthis hook status

hook check¶

linthis hook check

plugin¶

Manage plugins.

plugin add¶

linthis plugin add <ALIAS> <URL> [OPTIONS]

Option	Description
`-g, --global`	Add to global config
`--ref`	Git reference (branch/tag/commit)

Examples:

linthis plugin add myconfig https://github.com/user/config.git
linthis plugin add -g company https://github.com/company/standards.git
linthis plugin add myconfig https://github.com/user/config.git --ref v1.0.0

plugin remove¶

linthis plugin remove <ALIAS> [OPTIONS]

Option	Description
`-g, --global`	Remove from global config

plugin list¶

linthis plugin list [OPTIONS]

Option	Description
`-g, --global`	List global plugins
`-v, --verbose`	Show detailed info

plugin sync¶

linthis plugin sync [OPTIONS]

Option	Description
`--global`	Sync global plugins

plugin init¶

linthis plugin init <NAME>

plugin validate¶

linthis plugin validate <PATH>

plugin clean¶

linthis plugin clean [OPTIONS]

Option	Description
`--all`	Clean all caches

ignore¶

Manage the .linthisignore file. Supports two entry types: file glob patterns (exclude files from linting) and rule codes (suppress specific rules).

See Ignore Rules for full documentation.

ignore add¶

linthis ignore add <PATTERN>

Appends a pattern to .linthisignore. Use the rule: prefix to disable a rule by code.

Examples:

linthis ignore add "vendor/**"                    # Exclude a directory
linthis ignore add "*.generated.go"               # Exclude generated files
linthis ignore add "rule:E501"                    # Disable a lint rule
linthis ignore add "rule:clippy::too_many_arguments"
linthis ignore add "rule:linthis-complexity"      # Disable complexity checks

ignore remove¶

linthis ignore remove <PATTERN>

Removes an entry from .linthisignore (exact match).

Examples:

linthis ignore remove "vendor/**"
linthis ignore remove "rule:E501"

ignore list¶

linthis ignore list

Lists all current entries in .linthisignore, grouped by type (path patterns and disabled rules).

config¶

Manage configuration.

config add¶

linthis config add <FIELD> <VALUE> [OPTIONS]

Supported fields: includes, excludes, languages

Option	Description
`-g, --global`	Add to global config

config remove¶

linthis config remove <FIELD> <VALUE> [OPTIONS]

config clear¶

linthis config clear <FIELD> [OPTIONS]

config set¶

linthis config set <FIELD> <VALUE> [OPTIONS]

Supported fields: max_complexity, preset, verbose

config unset¶

linthis config unset <FIELD> [OPTIONS]

config get¶

linthis config get <FIELD> [OPTIONS]

config list¶

linthis config list [OPTIONS]

Option	Description
`-g, --global`	List global config
`-v, --verbose`	Show all fields

config migrate¶

linthis config migrate [OPTIONS]

Option	Description
`--from`	Migrate specific tool
`--dry-run`	Preview changes
`--backup`	Create backup
`-v, --verbose`	Verbose output

fix¶

Interactive fix mode with optional AI assistance.

linthis --fix [OPTIONS]
linthis fix [OPTIONS]

Fix Options¶

Option	Description	Example
`--fix`	Enter fix mode after check/format	`--fix`
`--ai`	Use AI for fix suggestions (requires `--fix`)	`--fix --ai`
`--provider`	AI provider (requires `--ai`)	`--provider claude`
`-y`	Auto-accept all fixes (requires `--fix`)	`--fix -y`

AI Providers¶

Provider	Description
`claude`	Anthropic Claude API (default)
`claude-cli`	Claude CLI (`claude -p` command)
`codebuddy`	CodeBuddy API
`codebuddy-cli`	CodeBuddy CLI
`openai`	OpenAI API
`local`	Local LLM (Ollama, etc.)
`mock`	Mock provider for testing

Provider Priority¶

Command line (--provider)
Environment variable (LINTHIS_AI_PROVIDER)
Config file ([ai] section)
Default: claude

Examples:

# Interactive fix mode (manual review)
linthis -i src/ --fix

# AI-powered fix with interactive review
linthis -i src/ --fix --ai

# AI fix with specific provider
linthis --fix --ai --provider claude
linthis --fix --ai --provider claude-cli

# Auto-accept all AI fixes (for CI/automation)
linthis --auto-fix
linthis --auto-fix --provider claude-cli

# Fix only staged files with AI
linthis -s --auto-fix --provider claude-cli

# Fix specific language
linthis -l python --fix --ai --provider claude

See AI-Powered Fix for detailed documentation.

cmsg¶

Validate commit message format (Conventional Commits).

linthis cmsg <MSG_OR_FILE> [OPTIONS]

Argument	Description
`MSG_OR_FILE`	Path to a commit message file (e.g. `.git/COMMIT_EDITMSG`), or the commit message string directly

Option	Description
`--auto-fix`	Automatically rewrite invalid commit messages using AI
`--provider`	AI provider for auto-fix (requires `--auto-fix`)

Examples:

# Validate a commit message string directly
linthis cmsg "feat: add login page"
linthis cmsg "fix(auth): handle token expiry"

# Validate via file path (used by git commit-msg hook)
linthis cmsg .git/COMMIT_EDITMSG

# AI rewrite on failure (rewrites and writes back to file)
linthis cmsg .git/COMMIT_EDITMSG --auto-fix
linthis cmsg .git/COMMIT_EDITMSG --auto-fix --provider claude-cli

# Install the commit-msg hook (calls linthis cmsg automatically)
linthis hook install --event commit-msg
linthis hook install --global --event commit-msg

The default pattern enforces Conventional Commits format:

type(scope)?: description

Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

Config (.linthis.toml):

[cmsg]
commit_msg_pattern = '^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?: .{1,72}'
require_ticket = false
# ticket_pattern = '^(PROJ-\d+|feat|fix|...)'

format¶

Format files with automatic backup and undo support.

linthis format [OPTIONS]

Option	Description
`-s, --staged`	Format only Git staged files
`-m, --modified`	Format only locally modified files (staged + unstaged)
`-i, --include`	Files/directories to format
`--undo`	Restore files from the last backup
`--list-backups`	List available backups
`--source`	Backup source for undo (default: latest)

Examples:

linthis format                        # Format all files
linthis format -s                     # Format staged files
linthis format -m                     # Format modified files
linthis format -i src/main.rs         # Format specific file
linthis format --undo                 # Undo last format
linthis format --list-backups         # List available backups

A backup is automatically created before each format operation. Use --undo to revert if the result is unwanted.

security¶

Security vulnerability scanning (SCA + SAST).

linthis security [OPTIONS] [PATH]

Option	Description	Default
`--scan-type`	Scan type: `all`, `sca`, `sast`	`all`
`-s`, `--severity`	Minimum severity: `critical`, `high`, `medium`, `low`
`--include-dev`	Include dev dependencies
`--fix`	Show fix suggestions
`-f`, `--format`	Output format: `human`, `json`, `sarif`	`human`
`--sast-config`	Custom SAST rules/config file
`--sbom`	Generate SBOM
`--fail-on`	Exit with error if severity threshold met
`--verbose`	Verbose output

SAST tools (auto-detected by language):

Tool	Languages	Install
linthis-secrets (built-in)	All	Always available
OpenGrep / Semgrep	30+ languages	`pip install opengrep`
Bandit	Python	`pip install bandit`
Gosec	Go	`go install github.com/securego/gosec/v2/cmd/gosec@latest`
Flawfinder	C/C++	`pip install flawfinder`

Examples:

linthis security                         # SCA + SAST
linthis security --scan-type sast        # SAST only
linthis security --severity high         # High+ only
linthis security --format json           # JSON output

Inline ignore directives (for secrets scanner):

KEY = "sk-real-key"  # linthis:ignore secrets
# linthis:ignore-next-line secrets/sk-prefix-key
KEY = "sk-real-key"

complexity¶

Code complexity analysis with trend tracking.

linthis complexity [OPTIONS] [PATH]

Option	Description	Default
`-s`, `--staged`	Analyze staged files only
`-m`, `--modified`	Analyze modified files only
`-t`, `--threshold`	Cyclomatic complexity threshold
`--preset`	Threshold preset: `default`, `strict`, `lenient`	`default`
`-o`, `--output`	Output format: `human`, `json`, `markdown`, `html`	`human`
`--with-trends`	Include trend analysis
`--only-high`	Only show high-complexity functions
`--sort`	Sort by: `cyclomatic`, `cognitive`, `lines`, `name`	`cyclomatic`
`--fail-on-high`	Exit with error if threshold exceeded

Examples:

linthis complexity                       # Analyze current directory
linthis complexity -s                    # Analyze staged files
linthis complexity -t 15 --only-high     # Show functions above 15
linthis complexity --output html         # HTML report

review¶

AI-powered code review with PR/MR creation support.

linthis review [OPTIONS]

Option	Description
`-b, --background`	Run review in background (non-blocking)
`--auto-fix`	Review + auto-fix + create PR/MR with fixes
`-r, --reviewer`	Specify reviewer(s) for PR/MR (repeatable)
`--provider`	AI provider to use
`--base`	Base branch/commit for diff comparison
`--head`	HEAD ref to review (default: `HEAD`)
`--no-pr`	Generate report only, do not create PR/MR
`--notify`	Notification channels (repeatable)
`--status`	Check status of background reviews
`--dry-run`	Preview auto-fix actions without pushing or creating PR
`--clean`	Remove old review artifacts
`-o, --output`	Output format: `markdown` (default) or `json`

Examples:

linthis review                        # Review current branch vs remote
linthis review --auto-fix             # Review + auto-fix + create PR
linthis review -r alice -r bob        # Specify reviewers
linthis review --base main            # Diff against main branch
linthis review --background           # Run in background (non-blocking)
linthis review --status               # Check background review status
linthis review --no-pr                # Generate Markdown report only
linthis review --dry-run              # Preview without pushing

Supported Platforms:

Platform	Detection	CLI Tool
GitHub	`github.com` remote	`gh`
GitLab	`gitlab.com` / self-hosted	`glab`

Config (.linthis.toml):

[review]
enabled = true
auto_fix = false
provider = "claude-cli"
retention_days = 30

[review.reviewers]
default = ["alice", "bob"]

watch¶

Watch mode for continuous checking.

linthis watch [OPTIONS]

See Watch Mode for details.

doctor¶

Check tool availability.

linthis doctor [OPTIONS]

Option	Description
`-l, --lang`	Check specific language

Exit Codes¶

Code	Meaning
0	Success (no issues or all issues fixed)
1	Lint/format issues found
2	Configuration error
3	Tool not available