build-stats

1.8.0 verified Sat May 09 auth: no javascript

A CLI tool that fetches and analyzes build pipeline history from Travis CI or Bitbucket Pipelines. Current stable version is 1.8.0. It offers commands to download, calculate averages, display history, and show success/failure stats. Designed for continuous integration environments, it supports private repositories via auth tokens, branch filtering, and customizable time periods. The tool caches data locally to avoid repeated API calls.

Common errors

error Error: Authentication failed. Please provide a valid token. ↓

cause Missing or invalid --auth token for a private repository.

fix

Use --auth with a valid token (see GENERATING_AUTH_TOKENS.md).

error Error: Cannot download history. Repo not found. ↓

cause Incorrect repository specifier format (service:user/repo).

fix

Use format like travis:owner/repo or bitbucket:owner/repo.

error Error: Cache directory not writable. ↓

cause Insufficient permissions to create .data folder in current directory.

fix

Run from a directory with write permissions or change directory.

Warnings

gotcha The --auth flag is required for private repos but optional for public; missing token on private repo causes authentication errors. ↓

fix Provide a valid authentication token using --auth <token>.

gotcha The --period flag defaults to 1 day, which may produce noisy data for repos with many builds. ↓

fix Use a larger period like 7 or 30 for smoother trends.

gotcha The --last flag defaults to 30 periods; if period is 1 day, it fetches only the last 30 days. Combine with --period for longer timeframes. ↓

fix Set --last to the total number of periods (e.g., --period 30 --last 12 for 1 year).

gotcha The download command saves data to a .data folder in the current working directory; not running from the expected directory may cause confusion. ↓

fix Run build-stats from the directory where you want the .data cache folder.

gotcha Bitbucket Pipelines support requires additional setup compared to Travis CI; auth token generation differs. ↓

fix Refer to GENERATING_AUTH_TOKENS.md for Bitbucket token instructions.

Install

npm install build-stats

yarn add build-stats

pnpm add build-stats

Quickstart

Install and run build-stats CLI to download and calculate build statistics for a Travis CI repository.

yarn global add build-stats
build-stats travis:boltpkg/bolt download --auth $TRAVIS_TOKEN
build-stats travis:boltpkg/bolt calculate --period 7 --last 90