/tools/cli

@speccle/cli

Shipped[tool]

The speccle command. It reads the three inputs from disk, runs analyse, and prints a terminal heatmap — or the raw ReportModel JSON with --json, ready for any renderer or a feedback-loop agent.

speccle

$ speccle --spec spec.md --mutation mutation.json --coverage coverage-summary.jsonmath — oracle-strength heatmapgenerated 2026-06-30T00:00:00Z from spec.md  Line coverage    75%  Oracle strength  62.5%  Gap              12.5%   (8 mutants: 5 killed, 1 survived, 2 uncovered)Arithmetic  🟢 AC-1  100%  add returns the sum of its two arguments.  (2/2 killed)  🔴 AC-2   50%  sub returns the difference of its two arguments.  (1/2 killed)       ↳ src/math.ts:6  ArithmeticOperator  a - b → a + bUnimplemented  ⬛ AC-3     —  pow raises the base to the exponent.  (no tagged tests)⚪ Unattributed mutants: 4

This is the exact output for the fixture report rendered live in the demo.

Options

--name <string>	Project name in the report (default: derived from the spec path).
--threshold <0..1>	Kill-rate at/above which a criterion is “strong” (default 0.8).
--json	Emit the raw report model as JSON instead of the terminal heatmap.
--fail-under <pct>	Exit 1 when oracle strength (0–100) is below <pct>. CI gate.
--no-color	Disable ANSI colour.
-h, --help	Show usage.

Try the fixtures

The repo bundles the @speccle/heatmap test fixtures, so you can run the CLI without generating anything:

shell

pnpm --filter @speccle/cli build
node packages/cli/dist/cli.js \
  --spec packages/heatmap/test/fixtures/spec.md \
  --mutation packages/heatmap/test/fixtures/mutation-report.json \
  --coverage packages/heatmap/test/fixtures/coverage-summary.json