DEV Community

Cover image for I built a CLI that reads your broken CI log and tells you why it failed in plain English
ci why
ci why

Posted on

I built a CLI that reads your broken CI log and tells you why it failed in plain English

#cicd #cli #productivity #showdev

Every developer knows the feeling.

Your CI pipeline fails. You open the log. There are 300 lines of noise — progress bars, timestamps, test runner output — and somewhere buried in there is the one line that actually matters.

I got tired of hunting for it. So I built ci-why.

What it does

You pipe your failed CI log into it, and it tells you:

  • WHY the build failed (in one sentence)
  • Which exact line caused it
  • What to fix 
cat build.log | ci-why
Enter fullscreen mode Exit fullscreen mode

That's it. You get back something like this:

──────────────────────────────────────────────────
  WHY
  The authentication service is returning null for the token field
  instead of a valid token string, causing the test assertion to fail.

  FAILING LINE
  src/services/auth.test.ts:63

  SUGGESTED FIX
  Check authService.login() in auth.ts — it's returning {"token": null}
  for valid credentials. The login logic needs fixing, not the test.
──────────────────────────────────────────────────
Enter fullscreen mode Exit fullscreen mode

Instead of reading 300 lines, you read 8.

How to install it 

npm install -g ci-why
Enter fullscreen mode Exit fullscreen mode

You'll need an Anthropic API key (free to get at console.anthropic.com). Set it once:

export ANTHROPIC_API_KEY=your-key-here
Enter fullscreen mode Exit fullscreen mode

Then use it however fits your workflow:

# Pipe from anywhere
cat build.log | ci-why

# Point at a file
ci-why ./logs/build.log
Enter fullscreen mode Exit fullscreen mode

How it works

ci-why does four things under the hood:

  1. Strips the noise — removes ANSI escape codes, progress bars, timestamps, and anything else that clutters CI logs
  2. Finds the signal — pulls out lines containing errors, exceptions, and failures, plus the last section of the log
  3. Asks Claude — sends the cleaned excerpt to the Anthropic API with a tight prompt asking for: why, where, and how to fix it
  4. Prints the result — formats it into the clean coloured output you saw above

The whole thing uses claude-haiku which is fast and cheap. A typical analysis costs less than a fraction of a cent.

It's free and open source

ci-why is completely free. You bring your own Anthropic API key so there's no subscription, no account, no billing through me.

The code is on GitHub: github.com/ciwhy-tool/ci-why

A paid cloud tier with GitHub Actions integration and team features is planned for the future — but the core CLI will always be free and open source.

What's coming next

  • GitHub Actions integration (auto-comment on PRs with the failure explanation)
  • Support for more log formats (pytest, Go test, Cargo, Maven)
  • --json flag for piping output into other tools

Try it and let me know what you think

If you try ci-why and hit a bug, have a suggestion, or just want to say it helped — drop a comment below or open an issue on GitHub. This is v0.1 and real feedback from real developers is exactly what I need to make it better.

npm install -g ci-why
Enter fullscreen mode Exit fullscreen mode

Update: v0.1.2 is out — better error messages, --version and --help flags, and graceful handling of empty logs. npm install -g ci-why to get it.

Top comments (0)