whyfail

Diagnose why your build, test, or deploy just failed -- pipe a log in, get the cause, explanation, fix, and exact commands back. No account, no config, no local backend to run: it talks to the live WhyDidThisFail? API by default.

A thin CLI client for the WhyDidThisFail? API (see the repo root for the Phase 1 service). It has no diagnosis logic of its own -- it collects the failing log text, POSTs it to /diagnose, and prints the result.

Install

No install needed for one-off use:

some-failing-command 2>&1 | npx whyfail

Or install it properly if you'll reach for it often:

npm install -g whyfail     # global, gives you the `whyfail` command everywhere
# or
npm install -D whyfail     # as a project dev dependency, run via `npx whyfail` or an npm script

Requires Node >= 18 (uses the built-in fetch; nothing else to install -- this package has zero runtime dependencies).

Usage

# Piped input -- the core workflow: pipe a failing command straight in
some-failing-command 2>&1 | npx whyfail

# From a saved log file (e.g. downloaded from a CI run)
npx whyfail ./build.log

# Interactive paste (for a failure you only have in a CI dashboard, Slack, etc.)
npx whyfail --paste

A real worked example

$ python -c "import definitely_not_installed" 2>&1 | npx whyfail

 ✓ KNOWN ISSUE — pattern-matched
matched pattern: py-module-not-found

Format: python
Error: ModuleNotFoundError: No module named 'definitely_not_installed'
Location: <string>:1

Cause
The package providing 'definitely_not_installed' is not installed in the current Python environment.

Explanation
Python looked for a module named 'definitely_not_installed' on sys.path and couldn't find it. This
almost always means the package isn't installed, is installed in a different virtual
environment/interpreter than the one running the code, or the module name differs from the pip
package name.

Fix
Install the package that provides 'definitely_not_installed' into the environment you're running
with, and double-check you're using the interpreter/virtualenv you think you are.

Commands
  $ pip install definitely_not_installed
  $ python -c "import sys; print(sys.executable)"

Options

| Flag | Description | | --- | --- | | --json | print the raw API response as JSON, for scripting | | --format <type> | hint the log format (python | npm | docker | github_actions | typescript | terraform) instead of auto-detecting | | --api-url <url> | override the API base URL | | -h, --help | show usage |

API URL resolution

--api-url flag > WHYFAIL_API_URL env var > the live production API (https://whydidthisfail-production.up.railway.app).

A fresh install needs zero configuration -- it hits the production backend automatically. Override with --api-url or WHYFAIL_API_URL only if you're running your own instance of the Phase 1 API (e.g. local development against the repo root, or a self-hosted deployment):

npx whyfail --api-url http://localhost:8000 ./build.log
# or
export WHYFAIL_API_URL=http://localhost:8000

Output

Results are visually tagged by where they came from:

• ✓ KNOWN ISSUE — pattern-matched -- matched a known, common error in the API's pattern database. Fast, and the fix has been seen before.
• ✨ AI ANALYSIS — novel issue -- no known pattern matched; this is Claude's best-effort analysis of something new.

Every result shows the detected format, the extracted error signal (so you can confirm the tool found the right error), cause, explanation, fix, and copy-pasteable exact commands.

Exit codes

0 on any successful diagnosis (pattern-matched or LLM). Non-zero only on a genuine tool error: the API was unreachable, the input couldn't be read, or no input was provided at all. There's no pass/fail verdict here, so exit code doesn't encode one.

Development

npm link   # from this directory, to test `whyfail` locally as if installed

Zero runtime dependencies -- relies on Node's built-in fetch (Node >= 18).

To point a locally-linked CLI at a locally-running Phase 1 API instead of production while developing, use --api-url http://localhost:8000 or set WHYFAIL_API_URL (see "API URL resolution" above).