Metadata-Version: 2.4
Name: blq-cli
Version: 0.10.2
Summary: Buidl Log Query - capture and query build/test logs with DuckDB
Project-URL: Homepage, https://blq-cli.readthedocs.com/
Project-URL: Repository, https://github.com/teaguesterling/blq-cli
Project-URL: Issues, https://github.com/teaguesterling/blq-cli/issues
Author-email: Teague Sterling <teaguesterling@gmail.com>
License-Expression: MIT
Keywords: build,ci,devops,duckdb,logs,test
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: duckdb>=1.4.4
Requires-Dist: jinja2>=3.0.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: tabulate>=0.9.0
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Requires-Dist: watchdog>=3.0.0
Provides-Extra: dev
Requires-Dist: fastmcp>=2.0.0; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
Provides-Extra: mcp
Requires-Dist: fastmcp>=2.0.0; extra == 'mcp'
Description-Content-Type: text/markdown

# blq - Build Log Query

BLQ (pronounced "bleak") is a CLI tool that turns build output into a queryable database. blq parses 100+ log formats via [duck\_hunt](https://duckdb.org/community_extensions/extensions/duck_hunt) into structured events, stores run history with git context, and provides an MCP server for AI agent integration.

## Why blq?

Your build fails. You scroll through 500 lines of output looking for the error. blq solves this:

```bash
blq run build
# build:3 | exit=1 | 12 errors, 35 warnings

blq errors
# ref       severity  file           line  message
# build:3:1 error     src/parser.c   142   expected ';' before '}'
# build:3:2 error     src/parser.c   156   'node' undeclared

blq inspect build:3:1
# Shows error with source context
```

**Key benefits:**
- **Structured events** — Errors with file:line locations, not raw text
- **Run history** — Every build stored with git commit, branch, environment
- **Comparison** — `blq diff 4 5` shows what changed between runs
- **AI agent tools** — MCP server for structured access without log parsing

## Installation

```bash
pip install blq-cli
```

## Quick Start

```bash
cd your-project
blq init --detect                    # Auto-detect build commands

blq run build                        # Run and capture
blq errors                           # See what broke
blq inspect build:3:1                # Drill into specific error
blq diff 4 5                         # Compare runs
```

Register commands manually if needed:

```bash
blq commands register build "make -j8"
blq commands register test "pytest -v"
```

## AI Agent Integration (MCP)

```bash
blq mcp install                      # Creates .mcp.json
```

Agents can then use tools like `run`, `events`, `inspect`, `diff` to work with structured results instead of parsing raw output. See the [MCP Guide](docs/mcp.md).

## Commands

| Command | Description |
|---------|-------------|
| `blq run <cmd>` | Run registered command, capture output |
| `blq errors` | Recent errors |
| `blq inspect <ref>` | Event details with source context |
| `blq info <ref>` | Run details |
| `blq history` | Run history |
| `blq diff <r1> <r2>` | Compare runs |
| `blq ci check` | Check for regressions vs baseline |

## Event References

Every error gets a reference like `build:3:1`:
- `build` — command name
- `3` — run number
- `1` — event within run

Use refs to drill down: `blq inspect build:3:1`, `blq info build:3`

## Features

| Feature | Description |
|---------|-------------|
| **100+ formats** | GCC, Clang, pytest, mypy, ESLint, etc. (see [duck\_hunt](https://duckdb.org/community_extensions/extensions/duck_hunt) |
| **Run history** | Every run with git commit, branch, environment |
| **Format detection** | Auto-detects format at registration time |
| **CI integration** | `blq ci check`, `blq ci comment` for PR feedback |
| **MCP server** | AI agents query errors without parsing logs |
| **Python API** | Programmatic access via `LogStore`, `LogQuery` |

## Documentation

- [Getting Started](docs/getting-started.md)
- [MCP Guide](docs/mcp.md) — AI agent integration
- [Query Guide](docs/query-guide.md) — Filtering, SQL, output formats
- [Integration](docs/integration.md) — CI/CD, hooks, shell completions
- [Python API](docs/python-api.md)
- [Commands Reference](docs/commands/)

## License

MIT
