Docs

Getting started

Install Faultline, run it against a failed build log, and get a structured failure report. No account required.

1

Install

Install the CLI via npm, Homebrew, or by downloading a binary from the GitHub releases page.

npm 
$ npm install -g faultline
Homebrew 
$ brew install faultline-cli/tap/faultline

Verify the installation:

bash 
$ faultline --version
faultline 0.x.x
2

Analyze a log

Pass a failed CI log file to faultline analyze. The CLI reads the log, matches it against known failure classes, and prints a structured report.

bash 
$ faultline analyze failed.log

failure_id:    dependency.lockfile_drift
confidence:    0.91
evidence:
  - npm ci rejected the lockfile
  - package.json and package-lock.json are out of sync
suggested_fix:
  - regenerate the lockfile
  - commit package.json and package-lock.json together

You can also pipe log content directly:

bash 
$ cat failed.log | faultline analyze -
No network calls during analysis. Faultline runs entirely offline. The log never leaves your machine.
3

JSON output

Pass --json to get machine-readable output. This is useful for piping into scripts, posting to APIs, or integrating with Faultline Teams.

bash 
$ faultline analyze failed.log --json
{
  "failure_id": "dependency.lockfile_drift",
  "confidence": 0.91,
  "evidence": [
    "npm ci rejected the lockfile",
    "package.json and package-lock.json are out of sync"
  ],
  "suggested_fix": [
    "regenerate the lockfile",
    "commit package.json and package-lock.json together"
  ]
}

Pipe the output to jq or use it in a CI post-step:

bash — GitHub Actions step 
# In a GitHub Actions workflow:
- name: Classify failure
  if: failure()
  run: |
    faultline analyze build.log --json > failure.json
    cat failure.json | jq '.failure_id'

CLI flags

Common flags for faultline analyze:

Flag Description Default
--json Output structured JSON instead of human-readable text false
--confidence Minimum confidence threshold for a match (0–1) 0.70
--class Filter output to a specific failure class prefix —
--verbose Show all candidate matches, not just the top result false
--version Print the CLI version and exit —