A CLI tool that parses command output (errors, JSON, logs, stack traces) and generates human-readable explanations with actionable fix suggestions. Works offline without any API, supports multiple programming languages, and can be piped to from any command.

Features

Multi-language Support: Python, JavaScript, Go, Rust, JSON, YAML, and generic CLI errors
Offline Knowledge Base: No API calls required - all explanations stored locally
Rich Terminal Output: Beautiful formatted output using the Rich library
Pipe-friendly: Easy to pipe errors from any command
Configuration: User preferences stored in config file
Multiple Output Formats: Rich, JSON, or plain text output

Installation

# Install from source
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/cli-explain-fix.git
cd cli-explain-fix
pip install -e .

# Or install dependencies manually
pip install -r requirements.txt

Usage

Pipe errors from any command

# Python error
python script.py 2>&1 | cli-explain-fix

# JavaScript error
node app.js 2>&1 | cli-explain-fix

# Any command output
make 2>&1 | cli-explain-fix

Direct input

cli-explain-fix main "ValueError: invalid value for int()"

# With explicit language
cli-explain-fix main --lang python "ImportError: No module named requests"

File input

cli-explain-fix main --file error.txt

Output formats

# JSON output
cli-explain-fix main --json "ValueError: test"

# Plain text output
cli-explain-fix main --plain "ValueError: test"

# No colors
cli-explain-fix main --no-color "ValueError: test"

Verbose mode

cli-explain-fix main --verbose "ValueError: test"

List supported languages

cli-explain-fix list-languages

List known errors

# All errors
cli-explain-fix list-errors

# Filter by language
cli-explain-fix list-errors --lang python

Show current configuration

cli-explain-fix show-config

Configuration

Configuration is stored in ~/.config/cli-explain-fix/config.yaml.

Environment Variables

Variable	Description
`CLI_EXPLAIN_FIX_LANG`	Default language for explanations
`CLI_EXPLAIN_FIX_OUTPUT`	Output format (rich, json, plain)
`CLI_EXPLAIN_FIX_VERBOSE`	Verbosity level (0-2)
`CLI_EXPLAIN_FIX_THEME`	Color theme for Rich output

Example Config File

default_language: python
output_format: rich
verbosity: 1
theme: default

Supported Error Types

Python

ImportError, ValueError, TypeError, SyntaxError
KeyError, IndexError, AttributeError
FileNotFoundError, and more...

JavaScript

ReferenceError, TypeError, SyntaxError
RangeError, and more...

Go

Panic errors (nil pointer, index out of range)

Rust

Panic errors, borrow checker errors
Trait bound errors

Common CLI Tools

Git (merge conflicts, not a repo)
Docker (connection errors, image not found)
Kubernetes (connection errors, resource not found)
npm (permission errors, ENOENT)
And more...

Development

# Clone the repository
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/cli-explain-fix.git

# Install in development mode
pip install -e ".[dev]"

# Run all tests
pytest -v --tb=short

# Run with coverage
pytest --cov=src --cov-report=term-missing

# Run specific test file
pytest tests/test_parser.py -v

Project Structure

cli-explain-fix/
├── pyproject.toml
├── requirements.txt
├── README.md
├── .gitignore
├── src/
│   └── cli_explain_fix/
│       ├── __init__.py
│       ├── main.py
│       ├── cli.py
│       ├── parser.py
│       ├── explainer.py
│       ├── knowledge_base.py
│       └── config.py
├── tests/
│   ├── conftest.py
│   ├── test_parser.py
│   ├── test_explainer.py
│   └── test_cli.py
└── knowledge_base/
    ├── errors.yaml
    └── patterns.yaml

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run tests to ensure everything passes
Submit a pull request

License

MIT License