CLI Reference

Complete reference for all BunCover CLI commands and options. A cross-platform CLI tool for collecting, analyzing, and reporting test coverage data for Bun projects.

Commands

buncover login

Login using browser authentication or access key. Supports both interactive browser-based authentication and access key authentication for CI/CD environments.

Options

--access-key <key>Use an access key for authentication (recommended for CI/CD). Environment variable BUNCOVER_ACCESS_KEY takes precedence for security.

buncover logout

Logout and remove stored authentication token

buncover status

Display current configuration status including authentication state and project information

buncover create-project

Create a new project

Options

-n, --name <NAME>Project name

--log-level <LOG_LEVEL>Log level (error, warn, info, debug, trace)

buncover run

Run tests with coverage reporting. Automatically includes --coverage --coverage-reporter=text flags. All arguments after buncover run options are passed directly to bun test.

Options

--project-id <id>Specify project ID for coverage upload

--Pass additional arguments to Bun test (e.g., -- --timeout 5000, -- --bail, -- src/**/*.test.ts)

Available Bun Test Arguments

All arguments after buncover run options are passed directly to bun test:

• --bail - Stop after first test failure
• --timeout <ms> - Set test timeout (default: 5000)
• --preload <file> - Preload a script before running tests
• --test-name-pattern <pattern> - Only run tests matching the pattern
• --rerun-each <n> - Run each test n times
• File/directory paths - Specify which test files to run

buncover serve

Serve source files for a project to enable real-time coverage visualization in the web interface

Options

--dir <path>Specify custom directory to serve (default: current directory)

--project-id <id>Use specific project ID for serving files

buncover help

Print help message or the help of the given subcommand(s)

Usage Examples

Authentication

Browser Authentication (Interactive)

# Login using browser authentication (default) buncover login

Access Key Authentication (CI/CD)

# Login with access key parameter buncover login --access-key buncover_live_your_access_key # Or use environment variable (recommended for CI/CD) export BUNCOVER_ACCESS_KEY=buncover_live_your_access_key buncover login

Note: Environment variables take precedence over command parameters for security.

Running Tests with Coverage

Basic Usage

Run tests and collect coverage. If no project ID is provided, it will use the one executed the last time. If there is no run history, then you will be asked to select to create a new project:

# Run tests and collect coverage buncover run # Run with specific project ID buncover run --project-id

Passing Arguments to Bun Test

All arguments after buncover run options are passed directly to bun test:

# Run specific test files or directories buncover run src/utils/*.test.ts buncover run tests/integration/ # Control test execution buncover run --bail # Stop after first failure buncover run --timeout 10000 # Set timeout to 10 seconds buncover run --preload ./setup.ts # Preload setup file # Filter tests by name pattern buncover run --test-name-pattern "user.*" # Combine multiple arguments buncover run --bail --timeout 5000 src/**/*.test.ts # Combine with BunCover options buncover run --project-id abc123 --bail tests/

Coverage Server

# Start server with default settings buncover serve # Specify custom directory buncover serve --dir ./src # Use specific project ID buncover serve --project-id

CI/CD Integration

GitHub Actions

name: Coverage Report on: [push, pull_request] jobs: coverage: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: oven-sh/setup-bun@v1 - name: Install dependencies run: bun install - name: Install BunCover CLI run: bun install -g @qualipsolutions/buncover - name: Login and run tests with coverage run: | buncover login buncover run env: BUNCOVER_ACCESS_KEY: ${{ secrets.BUNCOVER_ACCESS_KEY }}

Docker

FROM oven/bun:latest # Install BunCover CLI RUN bun install -g @qualipsolutions/buncover # Set access key via environment variable ENV BUNCOVER_ACCESS_KEY=buncover_live_your_access_key # Login and run tests with coverage CMD ["sh", "-c", "buncover login && buncover run"]

Other CI Systems

For other CI systems, simply:

Install BunCover CLI
Set BUNCOVER_ACCESS_KEY environment variable
Run buncover login
Run buncover run

Configuration

Environment Variables

# Access key for authentication (recommended for CI/CD) export BUNCOVER_ACCESS_KEY=buncover_live_your_access_key

Configuration File

BunCover automatically creates and manages a configuration file at .buncover/config.json:

{ "project_id": "your_project_id", }

Configuration Options

• project_id (string): Your project identifier (set automatically after first run)

Requirements

• Node.js ≥ 18.0.0
• Bun runtime installed
• Supported platforms: Linux, macOS, Windows
• BunCover must be run from a JavaScript/TypeScript project root (directory containing package.json)