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
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file blq_cli-1.1.0.tar.gz.
File metadata
- Download URL: blq_cli-1.1.0.tar.gz
- Upload date:
- Size: 731.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a682623fe0ca9686abf818617c144530ef73139365be90310b2d90eeba487521
|
|
| MD5 |
e862c7cff88ae6e0a35b8b6a89da5be4
|
|
| BLAKE2b-256 |
1664c1bca299313d52b5a03e245954086cae8899baa9f8f1cc30f6bb055bebda
|
Provenance
The following attestation bundles were made for blq_cli-1.1.0.tar.gz:
Publisher:
publish.yml on teaguesterling/blq-cli
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
blq_cli-1.1.0.tar.gz -
Subject digest:
a682623fe0ca9686abf818617c144530ef73139365be90310b2d90eeba487521 - Sigstore transparency entry: 2499737394
- Sigstore integration time:
-
Permalink:
teaguesterling/blq-cli@6c6d5626cebc08661c2cd673c0ae21d45239f579 -
Branch / Tag:
refs/tags/v1.1.0 - Owner: https://github.com/teaguesterling
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@6c6d5626cebc08661c2cd673c0ae21d45239f579 -
Trigger Event:
release
-
Statement type:
File details
Details for the file blq_cli-1.1.0-py3-none-any.whl.
File metadata
- Download URL: blq_cli-1.1.0-py3-none-any.whl
- Upload date:
- Size: 264.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1cfc9b0503bdd2d86035d466cd98b4ef2e88f1a8f8a6c01363def96a7e2fb7f5
|
|
| MD5 |
2d7f8a7387d5f054a3263e71f3503d17
|
|
| BLAKE2b-256 |
8d763e5027e41ea824a290c9049636d14481f5f4d8b8d597b2747a2835dbe92a
|
Provenance
The following attestation bundles were made for blq_cli-1.1.0-py3-none-any.whl:
Publisher:
publish.yml on teaguesterling/blq-cli
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
blq_cli-1.1.0-py3-none-any.whl -
Subject digest:
1cfc9b0503bdd2d86035d466cd98b4ef2e88f1a8f8a6c01363def96a7e2fb7f5 - Sigstore transparency entry: 2499737402
- Sigstore integration time:
-
Permalink:
teaguesterling/blq-cli@6c6d5626cebc08661c2cd673c0ae21d45239f579 -
Branch / Tag:
refs/tags/v1.1.0 - Owner: https://github.com/teaguesterling
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@6c6d5626cebc08661c2cd673c0ae21d45239f579 -
Trigger Event:
release
-
Statement type:
