CLI Commands

Command reference

The CLI is built around one deterministic workflow: impact, plan, and gate. Optional AI commands are layered on after the evidence path is already useful.

Core mental model

Read the CLI as deterministic first, AI second

Most teams start and stay inside impact, plan, and gate for a while. The AI commands exist to extend that evidence path, not replace it.

Fast orientation

The three commands most teams learn first

npx impact-gate impact --path . --since origin/main npx impact-gate plan --path . --since origin/main npx impact-gate gate --threshold 80 --path .

Core CI Optional AI Setup Traceability Diagnostics Advanced Global Flags

All commands are invoked via npx impact-gate <command>. Start with the core CI workflow first, then layer in optional AI features if the deterministic plan is already useful. The same deterministic flow supports pull-request gating and release-readiness planning from a git diff, while the AI path adds local-API grounding and hallucination guardrails rather than trusting raw generated code.

Core CI Workflow

impact

Map changed files to impacted route families using deterministic analysis. Free tier.

npx impact-gate impact --path . --since origin/main

Release-readiness example:

npx impact-gate impact --path . --since v2.1.0

Use --since with a previous release tag or branch when you want to compare the current candidate against what is already shipped.

plan (alias: suggest)

Generate a coverage plan with gap analysis, run sets, and confidence scores. Free tier.

npx impact-gate plan --path . --since origin/main --fail-on-must-add-tests

Release-readiness example:

npx impact-gate plan --path . --since v2.1.0

This is the easiest way to turn a release diff into a test plan that shows impacted areas, current coverage, and where new tests or manual checks are still needed before ship.

Key flags: --fail-on-must-add-tests, --github-output, --ci-comment-path, --json

gate

Pass/fail check against a coverage threshold. Exits non-zero on failure.

npx impact-gate gate --threshold 80 --path .

--threshold is percentage-style (0-100). For example, 80 means 80%.

Optional AI Workflow

analyze

Convenience wrapper that runs impact + plan, and optionally generation and healing.

npx impact-gate analyze --path . --generate --heal

generate

LLM-powered spec generation with iterative run-fix loops.

npx impact-gate generate --path . --max-attempts 3

heal

Repair flaky or failing specs from Playwright report data.

npx impact-gate heal --path . --traceability-report ./playwright-report.json

finalize-generated-tests

Stage generated tests, commit, and optionally open a PR.

npx impact-gate finalize-generated-tests --path . --create-pr --pr-title "Add E2E tests"

Setup And Calibration

init

Initialize a new configuration file interactively.

npx impact-gate init

train

Build the route-families manifest by scanning your codebase.

# Offline (free)
npx impact-gate train --no-enrich --path .

# With LLM enrichment
npx impact-gate train --path . --budget-usd 0.50

# Validate accuracy
npx impact-gate train --validate --since HEAD~50 --path .

Key flags: --no-enrich, --validate, --server-path, --budget-usd, --verbose

bootstrap

Generate a route-families manifest from an Understand-Anything knowledge graph. This is the fastest way to onboard a new project: point the tool at an existing knowledge graph and it produces the mapping file that powers impact analysis.

# Default: reads .understand-anything/knowledge-graph.json
npx impact-gate bootstrap --path .

# Custom knowledge graph location
npx impact-gate bootstrap --kg-path ./my-kg.json

# API-only tests, limit to 30 families, preview first
npx impact-gate bootstrap --test-mode api --max-families 30 --dry-run

Key flags:

Flag	Description
--kg-path	Path to a knowledge-graph JSON file (default: .understand-anything/knowledge-graph.json)
--test-mode	Test mode: ui, api, or both (auto-detected from the knowledge graph if omitted)
--max-families	Maximum number of route families to generate (default: 50)
--dry-run	Print the proposed manifest without writing files

Traceability

traceability-capture

Extract test-file relationships from Playwright JSON reports.

npx impact-gate traceability-capture --path . --traceability-report ./report.json

traceability-ingest

Merge captured mappings into the rolling traceability manifest.

npx impact-gate traceability-ingest --path . --traceability-input ./input.json

Key flags: --traceability-min-hits, --traceability-max-files-per-test, --traceability-max-age-days

Feedback & Diagnostics

feedback

Ingest recommendation outcomes for calibration. Free tier.

npx impact-gate feedback --path . --feedback-input ./feedback.json

cost-report

View LLM cost breakdown from past runs. Free tier.

npx impact-gate cost-report --path .

llm-health

Test LLM provider connectivity.

npx impact-gate llm-health

llm-health checks the configured provider, or the auto-detected provider if you rely on environment discovery.

Advanced / Experimental

crew

Run multi-agent workflows when you want richer strategy output or design artifacts on top of the core plan.

npx impact-gate crew --workflow quick-check --path . --tests-root ./e2e --since origin/main

Key flags: --workflow (quick-check, design-only, full-qa), --budget-usd, --dry-run, --json, --plugins

Global Flags

These flags apply across the main CLI surface and are the ones most teams pin in CI, local aliases, or project-level config.

Flag	Description
--path	Project root directory
--tests-root	Path to test directory
--framework	Test framework (playwright, cypress, pytest, supertest, selenium, auto)
--profile	Analysis profile (default, strict)
--since	Git ref for diff base, such as origin/main, a release branch, or a previous shipped tag
--config	Path to config file
--budget-usd	Max LLM spend in USD
--verbose / -v	Debug-level output
--json	Structured JSON output
--degraded-mode	Skip all AI calls
--dry-run	Preview without executing