CLI Reference

Complete reference for all pycmdcheck CLI commands and options

CLI Commands Reference

pycmdcheck provides a comprehensive command-line interface for checking Python packages. This page documents all available commands and their options.

Commands Overview

Command	Description
`check`	Check a Python package for issues
`list`	List all available checks
`info`	Show details for a specific check
`explain`	Get detailed explanation of a check
`fix`	Auto-fix package issues where possible
`init`	Initialize CI/CD configuration files
`remote`	Check a remote package from PyPI
`watch`	Watch mode (via `check --watch`)
`profiles`	List and inspect check profiles

check

Check a Python package for common issues.

pycmdcheck check [PATH] [OPTIONS]

Arguments

Argument	Default	Description
`PATH`	`.`	Directory to check

Output Options

Option	Description
`-f, --format FORMAT`	Output format: `rich` (default), `json`, `github`, `markdown`, `html`, `sarif`, `junit`
`-o, --output FILE`	Write output to file instead of stdout
`-v, --verbose`	Show all checks including passed
`-q, --quiet`	Minimal output, show only failures

Filter Options

Option	Description
`-s, --skip ID`	Skip check ID(s), can be repeated
`--skip-group GROUP`	Skip check group(s), can be repeated
`--only ID`	Only run these check ID(s), can be repeated
`--only-group GROUP`	Only run checks in these group(s), can be repeated

Profile Options

Option	Description
`-p, --profile NAME`	Use a check profile (strict, relaxed, ci, release)
`--list-profiles`	Show available profiles and exit

Exit Behavior

Option	Description
`--error-on LEVEL`	Minimum severity that causes non-zero exit: `error` (default), `warning`, `note`
`--fail-fast`	Stop on first failure

Performance Options

Option	Description
`--parallel/--no-parallel`	Run checks in parallel (default: sequential)
`--workers N`	Number of worker threads for parallel execution (default: 4)
`--cache/--no-cache`	Enable caching of check results (default: enabled)
`--incremental`	Only check files modified since last run

Fix Options

Option	Description
`--fix`	Automatically fix issues where possible
`--dry-run`	Show what would be fixed without making changes

Baseline Options

Option	Description
`--baseline FILE`	Path to baseline JSON file for ignoring known issues
`--generate-baseline FILE`	Generate baseline file from current failures

Diff Options

Option	Description
`--diff FILE`	Compare with previous run JSON file

Watch Options

Option	Description
`-w, --watch`	Watch for changes and re-run checks automatically

Badge Options

Option	Description
`--badge FILE`	Generate SVG badge to this file
`--badge-url`	Print shields.io badge URL

Examples

# Check current directory
pycmdcheck check

# Check a specific package
pycmdcheck check ./my-package

# Output as JSON
pycmdcheck check --format json

# Skip specific checks
pycmdcheck check --skip ST001 --skip ST002

# Only run structure checks
pycmdcheck check --only-group structure

# Use strict profile
pycmdcheck check --profile strict

# Auto-fix issues
pycmdcheck check --fix

# Preview fixes
pycmdcheck check --fix --dry-run

# Generate baseline from failures
pycmdcheck check --generate-baseline baseline.json

# Check against baseline
pycmdcheck check --baseline baseline.json

# Compare with previous run
pycmdcheck check --format json -o current.json
pycmdcheck check --diff previous.json

list

List all available checks.

pycmdcheck list [OPTIONS]

Options

Option	Description
`-g, --group GROUP`	Filter by check group
`--format FORMAT`	Output format: `table` (default), `json`

Examples

# List all checks
pycmdcheck list

# Filter by group
pycmdcheck list --group structure

# Output as JSON
pycmdcheck list --format json

Output

The table output shows:

Column	Description
ID	Check identifier (e.g., ST001)
Name	Human-readable check name
Group	Check group (structure, metadata, etc.)
Severity	ERROR, WARNING, or NOTE

info

Show details for a specific check.

pycmdcheck info CHECK_ID [OPTIONS]

Arguments

Argument	Description
`CHECK_ID`	Check identifier (e.g., ST001, MT002)

Options

Option	Description
`--format FORMAT`	Output format: `rich` (default), `json`

Examples

# Show check details
pycmdcheck info ST001

# Output as JSON
pycmdcheck info ST001 --format json

Output

The info output includes:

ID: Check identifier
Name: Human-readable name
Group: Which group the check belongs to
Severity: ERROR, WARNING, or NOTE
Requires: Fixture dependencies
Description: Full documentation for the check

explain

Get a detailed explanation of a check, including what it checks, why it matters, and how to fix issues.

pycmdcheck explain CHECK_ID [OPTIONS]

Arguments

Argument	Description
`CHECK_ID`	Check identifier (e.g., ST001, TS002) or name

Options

Option	Description
`--format FORMAT`	Output format: `text` (default), `json`, `yaml`

Examples

# Get explanation for a check
pycmdcheck explain ST001

# Output as JSON
pycmdcheck explain TS002 --format json

# Search by name
pycmdcheck explain "HasReadme"

Output

The explain output includes:

What it checks: Description of what the check validates
Why it matters: Explanation of why this check is important
How to fix: Step-by-step instructions to resolve issues
Configuration: Available configuration options for the check
Examples: Example configurations and code
See also: Related checks and external resources

fix

Auto-fix package issues where possible.

pycmdcheck fix [PATH] [OPTIONS]

Arguments

Argument	Default	Description
`PATH`	`.`	Directory to fix

Options

Option	Description
`--dry-run`	Show what would be fixed without making changes
`--only ID`	Only fix specific check IDs (can be repeated)
`--skip ID`	Skip specific check IDs (can be repeated)
`--group GROUP`	Only fix checks in specific groups (can be repeated)
`-v, --verbose`	Show verbose output

Examples

# Preview what would be fixed
pycmdcheck fix --dry-run

# Fix all fixable issues
pycmdcheck fix

# Fix only specific checks
pycmdcheck fix --only DC002 --only CQ002

# Fix checks in a specific group
pycmdcheck fix --group documentation

Fixable Checks

Check ID	Name	What Gets Fixed
ST001	HasReadme	Creates a `README.md` template
ST002	HasLicense	Creates an MIT `LICENSE` file
DC002	HasDocsDirectory	Creates `docs/index.md`
CQ002	HasTypeHints	Creates `py.typed` marker file
RL001	HasChangelog	Creates `CHANGELOG.md` template

init

Initialize CI/CD configuration files.

pycmdcheck init [OPTIONS]

Options

Option	Description
`--gitlab`	Create GitLab CI configuration (`.gitlab-ci.yml`)
`--circleci`	Create CircleCI configuration (`.circleci/config.yml`)
`--azure`	Create Azure Pipelines configuration (`azure-pipelines.yml`)

Examples

# Create GitLab CI configuration
pycmdcheck init --gitlab

# Create CircleCI configuration
pycmdcheck init --circleci

# Create Azure Pipelines configuration
pycmdcheck init --azure

# Create multiple configurations at once
pycmdcheck init --gitlab --azure

remote

Check a remote package from PyPI.

pycmdcheck remote PACKAGE_NAME [OPTIONS]

Arguments

Argument	Description
`PACKAGE_NAME`	Name of the package on PyPI

Options

Option	Description
`--version VERSION`	Specific version to check (default: latest)
`-f, --format FORMAT`	Output format: `rich` (default), `json`, `github`, `markdown`, `html`, `sarif`
`-v, --verbose`	Show all checks including passed
`-q, --quiet`	Minimal output, show only failures

Examples

# Check latest version of a package
pycmdcheck remote requests

# Check a specific version
pycmdcheck remote requests --version 2.28.0

# Output as JSON
pycmdcheck remote requests --format json

profiles

List and inspect available check profiles.

pycmdcheck profiles [OPTIONS]

Options

Option	Description
`--format FORMAT`	Output format: `table` (default), `json`
`--show NAME`	Show details of a specific profile

Examples

# List all profiles
pycmdcheck profiles

# Output as JSON
pycmdcheck profiles --format json

# Show details of a specific profile
pycmdcheck profiles --show strict

Built-in Profiles

Profile	Description	Error On
strict	Fail on any issue including notes	note
relaxed	Skip informational checks	error
ci	Optimized for CI pipelines	warning
release	Focus on release-critical checks	warning

Common Options

These options are available across most commands:

Version

pycmdcheck --version

Help

# General help
pycmdcheck --help

# Command-specific help
pycmdcheck check --help
pycmdcheck fix --help

Exit Codes

Code	Meaning
0	All checks passed (or only notes/skipped)
1	At least one check failed with ERROR severity
2	At least one check failed with WARNING severity (when `--error-on warning`)
3	Internal error or fixture resolution error

Environment Variables

pycmdcheck supports configuration via environment variables:

Variable	Description
`PYCMDCHECK_SKIP`	Comma-separated list of check IDs to skip
`PYCMDCHECK_ONLY`	Comma-separated list of check IDs to run
`PYCMDCHECK_PROFILE`	Profile to use
`PYCMDCHECK_ERROR_ON`	Minimum severity for non-zero exit

Environment variables are overridden by CLI options but take precedence over pyproject.toml settings.