Getting Started

Installation

Using pip

pip install pycmdcheck

Using uv

uv add pycmdcheck

From source

git clone https://github.com/coatless-py-pkg/pycmdcheck.git
cd pycmdcheck
pip install -e .

Basic Usage

Command Line

The simplest way to use pycmdcheck is from the command line:

# Check the current directory
pycmdcheck

# Check a specific path
pycmdcheck ./my-package

# Output as JSON
pycmdcheck --format json

# Skip specific checks
pycmdcheck --skip ST001 --skip MT003

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

Python API

You can also use pycmdcheck programmatically:

import pycmdcheck

# Basic check
results = pycmdcheck.check("./my-package")

# Check with options
results = pycmdcheck.check(
    "./my-package",
    skip_ids=["ST001", "MT003"],
    error_on="warning"
)

# Inspect results
print(f"Total checks: {results.total}")
print(f"Passed: {results.passed}")
print(f"Failed: {results.failed}")
print(f"Warnings: {results.warnings}")
print(f"Exit code: {results.exit_code}")

# Iterate over results
for group in results.groups:
    print(f"\n{group.name}:")
    for result in group.results:
        print(f"  {result.check_id}: {result.status.name}")

Async API

For better performance with many checks:

import asyncio
import pycmdcheck

async def main():
    results = await pycmdcheck.check_async("./my-package")
    print(f"Exit code: {results.exit_code}")

asyncio.run(main())

Understanding Results

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
3 Fixture resolution error

Check Statuses

Status Description
PASSED Check completed successfully
FAILED Check found an issue
SKIPPED Check was skipped (missing dependency or filtered)
ERRORED Check raised an exception
NOT_APPLICABLE Check doesn’t apply to this package

Severity Levels

Severity Description
ERROR Critical issue that should block release
WARNING Important issue that should be addressed
NOTE Informational, non-blocking issue

Output Formats

Rich (default)

Beautiful terminal output with colors and formatting:

pycmdcheck

JSON

Machine-readable output:

pycmdcheck --format json

GitHub Actions

Outputs workflow commands for annotations:

pycmdcheck --format github

Next Steps