Lintro

A comprehensive CLI tool that unifies various code formatting, linting, and quality assurance tools under a single command-line interface.

What is Lintro?

Lintro is a unified command-line interface that brings together multiple code quality tools into a single, easy-to-use package. Instead of managing separate tools like Ruff, Prettier, Yamllint, and others individually, Lintro provides a consistent interface for all your code quality needs.

Why Lintro?

• 🚀 Unified Interface: One command to run all your linting and formatting tools
• 🎯 Consistent Output: Beautiful, standardized output formats across all tools
• 🔧 Auto-fixing: Automatically fix issues where possible
• 🐳 Docker Ready: Run in isolated containers for consistent environments
• 📊 Rich Reporting: Multiple output formats (grid, JSON, HTML, CSV, Markdown)
• ⚡ Fast: Optimized execution with efficient tool management
• 🔒 Reliable: Comprehensive test suite with 84% coverage

Features

• Unified CLI for multiple code quality tools
• Multi-language support - Python, JavaScript, YAML, Docker, and more
• Auto-fixing capabilities where possible
• Beautiful output formatting with table views
• Docker support for containerized environments
• CI/CD integration with GitHub Actions

Supported Tools

Tool	Language	Auto-fix
	⚙️ GitHub Workflows	-
	🐍 Python	-
	🐍 Python	-
	🐳 Dockerfile	-
	🟨 JS/TS · 🧾 JSON	✅
	🐍 Python	✅
	🐍 Python	✅
	🧾 YAML	-

Quick Start

Installation

From PyPI (Recommended)

pip install lintro

Development Installation

# Clone and install in development mode
git clone https://github.com/TurboCoder13/py-lintro.git
cd py-lintro
pip install -e .

Basic Usage

# Check all files for issues
lintro check

# Auto-fix issues where possible
lintro format

# Use grid formatting for better readability
lintro check --output-format grid

# Run specific tools only
lintro check --tools ruff,prettier,actionlint

# List all available tools
lintro list-tools

Docker Usage

Quick Start with Published Image

# Run Lintro directly from GitHub Container Registry
docker run --rm -v $(pwd):/code ghcr.io/turbocoder13/py-lintro:latest check

# With specific formatting
docker run --rm -v $(pwd):/code ghcr.io/turbocoder13/py-lintro:latest check --output-format grid

# Run specific tools only
docker run --rm -v $(pwd):/code ghcr.io/turbocoder13/py-lintro:latest check --tools ruff,prettier

Development Setup

# Clone and setup
git clone https://github.com/TurboCoder13/py-lintro.git
cd py-lintro
chmod +x scripts/**/*.sh

# Run with local Docker build
./scripts/docker/docker-lintro.sh check --output-format grid

See Docker Documentation for detailed usage.

Advanced Usage

Output Formatting

# Grid format (recommended)
lintro check --output-format grid --group-by code

# Export to file
lintro check --output report.txt

# Different grouping options
lintro check --output-format grid --group-by file  # Group by file
lintro check --output-format grid --group-by code  # Group by error type

Tool-Specific Options

# Exclude patterns
lintro check --exclude "migrations,node_modules,dist"

# Tool-specific options use key=value (lists with |)
lintro check --tool-options "ruff:line_length=88,prettier:print_width=80"

# Ruff + Black cooperation:
# Lintro prefers Ruff for linting and Black for formatting.
# When Black is configured as a post-check, Lintro disables Ruff formatting by
# default to avoid double-formatting. Override if needed:
lintro format --tool-options ruff:format=True        # force Ruff to format
lintro check  --tool-options ruff:format_check=True  # force Ruff format check

CI/CD Integration

Lintro includes pre-built GitHub Actions workflows:

• Automated code quality checks on pull requests
• Coverage reporting with badges
• Multi-tool analysis across your entire codebase

See GitHub Integration Guide for setup instructions.

Documentation

For comprehensive documentation, see our Documentation Hub which includes:

• Getting Started - Installation and basic usage
• Docker Usage - Containerized development
• GitHub Integration - CI/CD setup
• Configuration - Tool configuration options
• Contributing - Developer guide
• Tool Analysis - Detailed tool comparisons

Development

# Run tests
./scripts/local/run-tests.sh

# Run Lintro on itself
./scripts/local/local-lintro.sh check --output-format grid

# Docker development
./scripts/docker/docker-test.sh
./scripts/docker/docker-lintro.sh check --output-format grid

For detailed information about all available scripts, see Scripts Documentation.

Dependencies

• Renovate for automated dependency updates
• Python 3.13+ with UV package manager
• Optional: Docker for containerized usage

License

This project is licensed under the MIT License. See the LICENSE file for details.

Troubleshooting

Common Issues

"Command not found: lintro"

Solution: Ensure Lintro is installed correctly:

pip install lintro
# or for development
pip install -e .

"Tool not found" errors

Solution: Install the required tools or use Docker:

# Install tools individually
pip install ruff darglint
npm install -g prettier
pip install yamllint
# or use Docker (recommended)
docker run --rm -v $(pwd):/code ghcr.io/turbocoder13/py-lintro:latest check

Permission errors on Windows

Solution: Run as administrator or use WSL:

# Use WSL for better compatibility
wsl
pip install lintro

Docker permission issues

Solution: Add your user to the docker group:

sudo usermod -aG docker $USER
# Log out and back in

Slow performance

Solution: Use exclude patterns and specific tools:

# Exclude large directories
lintro check --exclude "node_modules,venv,.git"

# Run specific tools only
lintro check --tools ruff,prettier

Getting Help

• 📖 Documentation: Check the docs/ directory
• 🐛 Bug Reports: Use the bug report template
• 💡 Questions: Use the question template
• 🚀 Feature Requests: Use the feature request template

Contributing

We welcome contributions! See our Contributing Guide for details on:

• Adding new tools
• Reporting bugs
• Submitting features
• Code style guidelines