Blinter 🚀
Blinter is a linter for Windows batch files (.bat and .cmd). It provides comprehensive static analysis to identify syntax errors, security vulnerabilities, performance issues and style problems. Blinter helps you write safer, more reliable and maintainable batch scripts. Even in 2025, batch files deserve professional tooling! 💻
- ✅ Configurable Options - Configurable rules, logging, robust error handling
- ✅ Unicode Support - Support for international characters and filenames
- ✅ Performance Optimized - Handles large files (10MB+) efficiently
Features ✨
🔍 Rule Categories
- 114 Built-in Rules across 5 severity levels
- Error Level (E001-E999): Critical syntax errors that prevent execution
- Warning Level (W001-W999): Potential runtime issues and bad practices
- Style Level (S001-S999): Code formatting and readability improvements
- Security Level (SEC001+): Security vulnerabilities and dangerous operations
- Performance Level (P001-P999): Optimization opportunities and efficiency improvements
📖 For complete rule descriptions with examples and implementation details, see docs/Batch-File-Linter-Requirements.md
📋 Output Format
- Rule Codes: Each issue has a unique identifier (e.g., E002, W005, SEC003)
- Clear Explanations: Detailed descriptions of why each issue matters
- Actionable Recommendations: Specific guidance on how to fix problems
- Line-by-Line Analysis: Precise location of every issue
- Context Information: Additional details about detected problems
🚀 Advanced Analysis
- Static Code Analysis: Detects unreachable code and logic errors
- Advanced Variable Expansion: Validates percent-tilde syntax (%~n1), string operations, and SET /A arithmetic
- Command-Specific Validation: FOR loop variations, IF statement best practices, deprecated command detection
- Variable Tracking: Identifies undefined variables and unsafe usage patterns
- Security Scanning: Path traversal attacks, command injection risks, unsafe temp file creation
- Performance Optimization: DIR flag optimization, unnecessary output detection, string operation efficiency
- Cross-Platform Compatibility: Warns about Windows version issues and deprecated commands
- Large File Handling: Efficiently processes files up to 10MB+ with performance warnings
- Robust Encoding Detection: Handles UTF-8, UTF-16, Latin-1 and 6 more encoding formats
🚀 Quick Start
Get started in 30 seconds:
-
Install Blinter:
pip install Blinter
-
Analyze your batch file:
blinter script.bat
-
That's it! Blinter will show you all issues with detailed explanations and fix recommendations.
Alternative: No Python? No problem!
- Download the standalone executable and run
Blinter.exe script.bat
Installation 🛠️
🚀 Quick Start (Recommended)
Option 1: Install via pip (easiest)
pip install Blinter
Option 2: Download standalone executable
- Download the latest
Blinter-v1.0.x-windows.zipfrom GitHub Releases - Extract and run
Blinter.exedirectly (no Python installation required)
🔧 Development Installation
- Clone the repository:
git clone https://github.com/tboy1337/Blinter.git
cd Blinter
- (Optional) Create a virtual environment:
python -m venv venv
venv\Scripts\activate
- Install dependencies:
pip install -r requirements.txt
Prerequisites
- Python 3.9+ (required for pip installation and development)
- Windows OS (required for standalone executable)
Usage 📟
Basic Usage
If installed via pip:
# Analyze a single batch file
blinter script.bat
# Analyze all batch files in a directory (recursive)
blinter /path/to/batch/files
# Analyze batch files in directory only (non-recursive)
blinter /path/to/batch/files --no-recursive
# Analyze with summary
blinter script.bat --summary
# Get help
blinter --help
If using standalone executable:
# Analyze a single batch file
Blinter.exe script.bat
# Analyze all batch files in a directory (recursive)
Blinter.exe /path/to/batch/files
# Analyze batch files in directory only (non-recursive)
Blinter.exe /path/to/batch/files --no-recursive
# Analyze with summary
Blinter.exe script.bat --summary
# Get help
Blinter.exe --help
If using development/source installation:
# Analyze a single batch file
python blinter.py script.bat
# Analyze all batch files in a directory (recursive)
python blinter.py /path/to/batch/files
# Analyze batch files in directory only (non-recursive)
python blinter.py /path/to/batch/files --no-recursive
# Analyze with summary
python blinter.py script.bat --summary
# Get help
python blinter.py --help
Command Line Options
<path>: Path to a batch file (.bator.cmd) OR directory containing batch files--summary: Display summary statistics of issues found--severity: Show detailed severity level breakdown (always included)--no-recursive: When processing directories, only analyze files in the specified directory (not subdirectories)--help: Show help menu and rule categories
🐍 Programmatic API Usage
Blinter provides a powerful Python API for integration into your applications:
import blinter
# Basic usage
issues = blinter.lint_batch_file("script.bat")
for issue in issues:
print(f"Line {issue.line_number}: {issue.rule.name} ({issue.rule.code})")
print(f" {issue.rule.explanation}")
print(f" Fix: {issue.rule.recommendation}")
# Advanced configuration
issues = blinter.lint_batch_file(
"script.bat",
max_line_length=100, # Custom line length limit
enable_style_rules=False, # Disable style checks
enable_performance_rules=True # Keep performance checks
)
# Thread-safe design allows safe concurrent usage
# You can implement your own concurrent processing if needed
from concurrent.futures import ThreadPoolExecutor
files = ["script1.bat", "script2.cmd", "script3.bat"]
with ThreadPoolExecutor(max_workers=4) as executor:
results = list(executor.map(blinter.lint_batch_file, files))
🔧 Configuration Options
| Parameter | Type | Default | Description |
|---|---|---|---|
file_path |
str |
Required | Path to batch file to analyze |
max_line_length |
int |
120 |
Maximum line length for S011 rule |
enable_style_rules |
bool |
True |
Enable/disable style-related rules |
enable_performance_rules |
bool |
True |
Enable/disable performance rules |
Note: Security rules are always enabled for safety.
Supported File Types
.batfiles (traditional batch files).cmdfiles (recommended for modern Windows)- Unicode filenames and international characters supported
- Large files (10MB+) handled efficiently with performance monitoring
📁 Directory Processing
Blinter can analyze entire directories of batch files with powerful options:
- Recursive Analysis: Automatically finds and processes all
.batand.cmdfiles in directories and subdirectories - Non-Recursive Mode: Use
--no-recursiveto analyze only files in the specified directory - Batch Processing: Handles multiple files efficiently with consolidated reporting
- Error Resilience: Continues processing other files even if some files have encoding or permission issues
- Progress Tracking: Shows detailed results for each file plus combined summary statistics
Examples:
# Pip installation:
blinter ./my-batch-scripts # Analyze all files recursively
blinter . --no-recursive # Current directory only
blinter ./scripts --summary # With summary statistics
# Standalone executable:
Blinter.exe ./my-batch-scripts # Analyze all files recursively
Blinter.exe . --no-recursive # Current directory only
Blinter.exe ./scripts --summary # With summary statistics
# Development/source installation:
python blinter.py ./my-batch-scripts # Analyze all files recursively
python blinter.py . --no-recursive # Current directory only
python blinter.py ./scripts --summary # With summary statistics
🔥 Integration Example
CI/CD Integration
# Example GitHub Actions workflow
- name: Lint Batch Files
run: |
python -c "
import blinter
import sys
issues = blinter.lint_batch_file('deploy.bat')
errors = [i for i in issues if i.rule.severity.value == 'Error']
if errors:
print(f'Found {len(errors)} critical errors!')
sys.exit(1)
print(f'✅ Batch file passed with {len(issues)} total issues')
"
Contributing 🤝
Contributions are welcome!
Ways to Contribute
- 🐛 Report bugs or issues
- 💡 Suggest new rules or features
- 📖 Improve documentation
- 🧪 Add test cases
- 🔧 Submit bug fixes or enhancements
License 📄
This project is licensed under the CRL License - see LICENSE.md for details.
1 maintainer
Metadata
1 maintainer
Release files for blinter 1.0.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| blinter-1.0.3.tar.gz | 103.4 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| blinter-1.0.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 145.4 kB
Release files / blinter-1.0.3.tar.gz
| Download URL | blinter-1.0.3.tar.gz |
|---|---|
| Size | 103.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5eda4e312089c1a732bfa62981f8e828b7df4e20682294d07d2ec75de51768cb
|
|
BLAKE2b-256 checksum How to use checksums |
7c14fab4deb8c32cc6d2b081fcc9fb9892c475ae262d49587e00a098dc7e9acd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Release files / blinter-1.0.3-py3-none-any.whl
| Download URL | blinter-1.0.3-py3-none-any.whl |
|---|---|
| Size | 42.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
645f703b5497316488a1badd1f3cf29d09cf8091d917773af047b06e295bc848
|
|
BLAKE2b-256 checksum How to use checksums |
a053026ca035305bd4046f20bc6ec3f64d1ed7fc6874d52152d28a310dece91a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Security for blinter 1.0.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
