CLI commands

The CLI is provided by @flaky-tests/core. Run it with bunx:

bunx @flaky-tests/core [flags]

Or install globally:

bun add -g @flaky-tests/core
flaky-tests [flags]

npm only — JSR has no CLI

The flaky-tests command is only available when installed from npm. JSR does not support the bin field in package.json — it publishes TypeScript source as modules, not executables.

If you installed via bunx jsr add @flaky-tests/core, you’ll get the library exports but no flaky-tests binary on your PATH. Either:

• Install from npm instead: bun add -D @flaky-tests/core (recommended for CLI use), or

• Invoke the CLI as a module from a wrapper script:

  scripts/report.ts

  import '@flaky-tests/core/check'

  { "scripts": { "report": "bun scripts/report.ts --html" } }

Dual-publishing (npm for the CLI, JSR for library imports) is the idiomatic split. Library-only consumers can use either registry; CLI users need npm.

Default behavior

Running the CLI with no flags:

1. Connects to the configured store
2. Calls getNewPatterns() with default window (7 days) and threshold (2 failures)
3. Prints a summary to stdout
4. Exits 0 if no patterns found, 1 if patterns were found

Flags

--window <days>

Number of days in each detection window. The CLI compares the current window against an equal prior window.

bunx @flaky-tests/core --window 14   # 14-day windows

Default: 7

--threshold <n>

Minimum number of failures in the current window to flag a test as flaky.

bunx @flaky-tests/core --threshold 3

Default: 2

--prompt

Print an AI investigation prompt for each pattern to stdout. Structured for pasting into Claude, Cursor, or Copilot.

bunx @flaky-tests/core --prompt

--copy

Copy the investigation prompt to the clipboard. Uses pbcopy on macOS, xclip on Linux, clip on Windows.

bunx @flaky-tests/core --prompt --copy

If multiple patterns are found, all prompts are concatenated before copying.

--create-issue

Open a GitHub issue for each new pattern. Requires GITHUB_TOKEN and either GITHUB_REPOSITORY (set automatically in Actions) or --repo.

bunx @flaky-tests/core --create-issue --repo your-org/your-repo

Issues include the investigation prompt in a collapsible <details> block. If an open issue for the same test already exists, a new one is not created.

--repo <owner/repo>

Override the repository for issue creation. Defaults to GITHUB_REPOSITORY env var, then falls back to parsing git remote get-url origin.

bunx @flaky-tests/core --create-issue --repo acme/api

--html

Generate a self-contained HTML report (single file, inline CSS + JS) and open it in the default browser.

bunx @flaky-tests/core --html

Works even when there are no newly-flaky patterns — the report falls back to run history. See Using the HTML report for what’s included and how to share it.

--out <path>

Destination path for --html. Defaults to a timestamped temp file.

bunx @flaky-tests/core --html --out flaky-report.html

Use this to commit the report, attach it to a PR, or upload it as a CI artifact.

Exit codes

Code	Meaning
0	No new patterns detected
1	One or more new patterns detected
2	Configuration error (missing env vars, store connection failed)

Tip

The exit code makes the CLI composable in CI pipelines. Use || true to suppress failure if you want CI to pass regardless of flaky patterns:

bunx @flaky-tests/core || true

Examples

# Check with defaults
bunx @flaky-tests/core

# Check 30-day window, threshold 5
bunx @flaky-tests/core --window 30 --threshold 5

# Print prompts for each pattern
bunx @flaky-tests/core --prompt

# Copy single prompt to clipboard
bunx @flaky-tests/core --prompt --copy

# Create GitHub issues
GITHUB_TOKEN=$TOKEN bunx @flaky-tests/core --create-issue --repo your-org/your-repo

# Use Turso store
FLAKY_TESTS_STORE=turso \
  TURSO_URL=libsql://... \
  TURSO_AUTH_TOKEN=... \
  bunx @flaky-tests/core