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 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:
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 5shows what changed between runs - AI agent tools — MCP server for structured access without log parsing
Installation
pip install blq-cli
Quick Start
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:
blq commands register build "make -j8"
blq commands register test "pytest -v"
AI Agent Integration (MCP)
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.
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 name3— run number1— 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 |
| 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
- MCP Guide — AI agent integration
- Query Guide — Filtering, SQL, output formats
- Integration — CI/CD, hooks, shell completions
- Python API
- Commands Reference
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for blq-cli 1.2.2
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 | |
|---|---|---|---|---|
| blq_cli-1.2.2.tar.gz | 736.9 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| blq_cli-1.2.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.0 MB
Release files / blq_cli-1.2.2.tar.gz
| Download URL | blq_cli-1.2.2.tar.gz |
|---|---|
| Size | 736.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4cca7ad79508d75b905569e5628e84f7bcbb799463c9704370fcba95cc5d0858
|
|
BLAKE2b-256 checksum How to use checksums |
7e736c60861933827bb55e01ac73f4df95de8c36b09de45d2e55aca24e37c501
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 29, 2026.
Transparency logRelease files / blq_cli-1.2.2-py3-none-any.whl
| Download URL | blq_cli-1.2.2-py3-none-any.whl |
|---|---|
| Size | 266.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4654727708b5d0e7f68a30593d4f25554b1bb9a50bf7ddf07d58c24080be450c
|
|
BLAKE2b-256 checksum How to use checksums |
83f7e993813597c38b5dee674eea21b1d323082c218b4edf62590772563a8c95
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 29, 2026.
Transparency logSecurity for blq-cli 1.2.2
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.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for blq_cli-1.2.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 29, 2026.
Transparency logA 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.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
