CLI reference

This page is the current CLI reference for command discovery and mirrors the front-door product story: release confidence first, expansion second.

Primary outcome: know if a change is ready to ship.

Canonical first path: python -m sdetkit gate fast → python -m sdetkit gate release → python -m sdetkit doctor.

Canonical first-time path (public / stable)

Use this exact sequence first:

1. python -m sdetkit gate fast
2. python -m sdetkit gate release
3. python -m sdetkit doctor

This is the primary product path for first-time adoption and release-confidence proof. If a new visitor remembers only one thing, it should be this exact path.

What gate fast runs in your repository

gate fast enforces the policy your repository declares, not SDETKit's own conventions:

Step	Runs when	Default command
doctor	always	sdetkit doctor --dev --deps --clean-tree
ruff, ruff_format	ruff is configured ([tool.ruff], ruff.toml, or a pre-commit ruff hook)	ruff check / ruff format --check on src and tests (or .); when the pre-commit ruff hook or the config's top level sets files or exclude, exactly the files pre-commit would pass to that hook
mypy	mypy is configured ([tool.mypy], mypy.ini, or setup.cfg [mypy])	mypy with your configured files; else the files and arguments of your pre-commit mypy hook; else each mypy ... command in tox.ini; else mypy src
pytest	the repository has Python and tests are detected (tests/, test/, or pytest config)	pytest -q
tests:<ecosystem>[:<dir>]	the repository model found a non-Python test suite	the workspace's own chain, for example go test ./..., npm test, cargo test, mvn test, dotnet test, or cmake --preset → cmake --build → ctest
ci_templates	opted in	SDETKit CI template validation

When the targets come from pre-commit or tox, the step records it in targets_from. Skipped steps are listed under skipped_steps with a reason. Selecting a step with --only <step> forces it to run; --only tests, --skip tests and --no-tests select the non-Python suites. A suite whose tool is not installed is skipped, and the verdict is then NOT_RUN, not SHIP: green steps do not prove a release when the repository's own tests never ran. Override any default in pyproject.toml:

[tool.sdetkit.gate]
pytest_args = ["-q", "tests/smoke"]
mypy_args = ["src"]
ruff_paths = ["src", "tests"]
doctor_args = ["--dev", "--deps", "--clean-tree"]
ci_templates = false

[tool.sdetkit.doctor]
# Optional: require .github/workflows/release.yml to run this tag/version check.
release_tag_check_script = "scripts/check_release_tag_version.py"

Which Python runs your checks

ruff, mypy and pytest run in the project's own environment, so the tests import your checkout and mypy reads your dependencies. gate fast uses the first of:

1. --python <interpreter>
2. .venv or venv in the repository
3. Poetry's or Pipenv's environment (poetry env info --executable, pipenv --py) when the repository has their lockfile
4. an activated virtualenv (VIRTUAL_ENV)
5. the interpreter SDETKit runs in

The payload's environment field records the interpreter and where it came from, and the text output prints it. When the project environment has no ruff or mypy, SDETKit's own copy runs (mypy with --python-executable pointing at the project's interpreter); it has to have pytest, or the pytest step does not run.

A failure that comes from the environment, not the code, reads NOT_RUN with classification: environment, and its next command sets the environment up (for example uv sync && python -m sdetkit gate fast). That covers pytest failing with No module named '<your package>' (the project is not installed where the tests ran), pytest missing any dependency while running in SDETKit's own interpreter, mypy errors that all sit in installed packages, and failing tests that ran against a different copy of the project. That last case covers a project with no environment of its own and not installed in SDETKit's interpreter (mypy and pytest), and tests that imported another installed release instead of the checkout (pytest). The checkout counts as installed when it is an editable install of the repository, when the installed version equals the checkout's own version, or when its src/ packages resolve inside the repository. The gate still exits non-zero: nothing was proven. A real code failure in another step outranks it and the verdict stays NO_SHIP.

One repository model

gate fast, doctor --ci, init and fit --root read the repository through one model (sdetkit.repo_model.v1), built from the same discovery as sdetkit adoption-surface. It covers Python, JavaScript/TypeScript, Go, Java, Rust, .NET and C++, and GitHub Actions, GitLab CI, Jenkins, CircleCI and Azure Pipelines. Directories named fixtures, node_modules, vendor, build, dist and similar are not part of the model.

• gate fast runs each workspace's own test chain and stops running pytest in repositories without Python. The payload's repo field records the languages, CI systems and suites it saw.
• doctor --ci accepts CI on any detected system: a CI file that runs a linter or formatter satisfies the quality group, and one that runs a security scanner satisfies the security group. The GitHub workflow names ci.yml, quality.yml and security.yml still count.
• init reports the languages, CI and test suites it found, warns when the enterprise_python preset would scaffold Python CI into a repository without Python, and suggests gate fast, doctor --ci and gate release --reuse-fast.
• fit --root <path> infers the repository size, lists what it found, and leads its next steps with the gaps (no proven test command, no CI, no security scanner in CI).

One verdict across every decision

gate fast, gate release, mission-control run, release-room plan and diagnose run each add a verdict object (sdetkit.verdict.v1) to their JSON output. It uses four decisions, SHIP, REVIEW, NOT_RUN and NO_SHIP, and every authority flag in it is false.

Pass results forward instead of re-running them:

python -m sdetkit gate fast --format json --out build/gate-fast.json
# Reuses gate fast when it was recorded on this commit with a clean tree; otherwise runs it again.
python -m sdetkit gate release --format json --reuse-fast build/gate-fast.json --out build/gate-release.json
# The most severe verdict wins: green required checks do not hide a NO_SHIP gate.
python -m sdetkit verify merge --checks-json checks.json --evidence build/gate-release.json

Enterprise reliability workflow (step-by-step)

After the canonical path succeeds, use the enterprise doctor profile for stricter release governance and focused remediation loops:

1. Full enterprise scan:
2. python -m sdetkit doctor --enterprise --format md
3. Focused failed-check rerun from workspace history:
4. python -m sdetkit doctor --enterprise-rerun-failed --json
5. optional scope cap: --enterprise-rerun-top <N>
6. Focused high-severity rerun from workspace history:
7. python -m sdetkit doctor --enterprise-rerun-high --json
8. optional scope cap: --enterprise-rerun-top <N>
9. Repeat rerun/fix cycles until blockers are cleared and score stabilizes.
10. Automation handoff (emit only suggested follow-up pass command):
11. python -m sdetkit doctor --enterprise-next-pass-only
12. CI-friendly status mode: python -m sdetkit doctor --enterprise-next-pass-only --enterprise-next-pass-exit-code (returns exit code 2 when a follow-up pass is recommended, else 0)
13. plain output emits three lines: command/no-op, reason: ..., alternates: ...
14. markdown-friendly output: python -m sdetkit doctor --enterprise-next-pass-only --format md
15. when no follow-up is needed in markdown mode, output is _no follow-up pass required_
16. markdown mode also emits a second line reason hint: `reason: <reason>`
17. markdown mode also emits a third line alternates hint: `alternates: <cmds|none>`
18. JSON handoff payload includes schema_version=sdetkit.doctor.next_pass.v1
19. JSON handoff payload includes has_next_pass boolean for direct pipeline branching
20. JSON handoff payload includes next_pass_reason (none|blockers_present|failed_checks_present)
21. JSON handoff payload includes alternate_commands for fallback lane selection
22. JSON handoff payload includes exit_code_hint (0 no follow-up, 2 follow-up recommended)
23. note: this handoff mode is standalone and cannot be combined with rerun flags.
24. note: --enterprise-next-pass-exit-code only works with --enterprise-next-pass-only.

If historical workspace payloads do not include per-check severity metadata, --enterprise-rerun-high falls back to rerunning recorded failed checks.

Expected enterprise outputs include:

• profile markers (profile=enterprise, profile_mode=full_scan|rerun_failed|rerun_high)
• rerun scope metadata (rerun_top) when --enterprise-rerun-top is used
• enterprise execution insights (maturity tier, blockers, optimization queue, follow-up pass reason)
• follow-up command hint (next_pass_command) for the recommended focused rerun step
• remediation bundle items for rapid operator follow-up

Command reference

python -m sdetkit --help lists every command. Run python -m sdetkit <command> --help for its options.

Release confidence

Command	What it does
gate	Run the fast or release quality gate (SHIP, REVIEW, NOT_RUN or NO_SHIP)
doctor	Check repository and release readiness
release	Release kit: release gate
security	Scan for secrets and risky code, with a baseline
evidence	Pack, validate and compare release evidence
report	Ingest, diff and build run report artifacts

Diagnose and adopt

Command	What it does
diagnose	Diagnosis engine: check intelligence, failure vectors, remediation plans
verify	Fix-safety checks: protected verifier, patch scoring, benchmarks, merge
investigate	Diagnose a failure and print the next action
triage-ci	Diagnose a saved CI job log
mission-control	Build a release-confidence evidence bundle
adoption-surface	Map a repository's languages, CI and proof commands (read-only)
adoption-proof-recommendations	Recommend proof commands from an adoption-surface artifact
adoption-repo-topology	Map workspace topology from an adoption-surface artifact
fit	Recommend an adoption depth for a repository (--root reads the repository)
adoption	Plan follow-up actions from fit and gate results
repo	Check, fix and audit repository hygiene
init	Scaffold SDETKit config in a repository
dev	Developer setup: pre-commit and IDE integration
maintenance	Run repository maintenance checks

SDET utilities

Command	What it does
apiget	HTTP GET JSON with retries, pagination and cassette record/replay
cassette-get	Record or replay a single HTTP GET cassette
kv	Parse key=value input into JSON
patch	Apply a JSON patch spec to files, with size limits
serve	Run SDETKit as a local review API service
inspect	Inspect CSV/JSON evidence and emit diagnostics
inspect-compare	Compare inspect snapshots for baseline drift
inspect-project	Run inspection policy packs over dataset families

Advanced

Command	What it does
readiness	Score repository release readiness
release-room	Build a release-room operator plan
adaptive	Local adaptive memory: init, ingest, history, explain
ci	Validate CI workflow templates
policy	Snapshot, check and diff repository policy
review	Run the review workflow over a repository
boost	Scan a repository and rank local risk signals
index	Build or inspect a local repository index
kits	List, search and describe the umbrella kits
intelligence	Flake detection, change impact and failure fingerprints
integration	Integration checks, environment matrix and cassette validation
forensics	Failure forensics kit
contract	Print SDETKit runtime and integration contracts
example	Run the guided example flow
notify	Send a message through a notification adapter
ops	Run, replay and diff operations workflows
workflow-governance-report	Report on GitHub Actions workflow permissions (read-only)

Subcommand groups

release, diagnose and verify take a subcommand and pass the remaining arguments to it. python -m sdetkit <group> --help lists them.

release

Subcommand	What it does
gate	Run the gate
doctor	Run doctor
security	Run the security gate
evidence	Build or check evidence
repo	Run repository checks

diagnose

diagnose run chains the other subcommands end to end; with no --log it reads the failed steps of the latest gate fast or gate release run. See Remediation loop.

Subcommand	What it does
run	Run the full loop on saved CI logs: diagnose, plan, prove in a copy, verify
card	Build the decision card and PR comment for a run
decide	Record a person's approve/reject on a decision card
checks	Classify failed checks and their provenance
ci-log	Extract the first failure from a CI log
vector	Build a diagnostic vector for a failure
plan	Plan which proofs to run for a failure
job	Run a full diagnostic job from saved evidence
remediation	Build a review-first remediation plan
trajectory	Record a diagnostic worker trajectory
history	Record diagnostic trajectories
memory	Show what the repository's remediation history has proven
security	Summarise security review evidence

verify

Subcommand	What it does
patch	Verify a candidate patch against protections
score	Score a candidate patch
benchmark	Replay a fix benchmark
merge	Decide merge readiness from evidence
isolated	Run a proof command in isolation
network	Check a proof run's network boundary
inventory	Collect a git file inventory
### Removed commands

The CLI no longer includes the hidden playbook, closeout, phase and legacy-namespace commands (playbooks, legacy, *-closeout, phase*, start, onboarding, agent, author and similar) together with --show-hidden and --no-legacy-hint. Their workflows were reporting-only and are not replaced. gate release no longer runs a playbook validation step.

Adoption surface artifact

Use adoption-surface when an operator needs a read-only map of the repository before choosing proof commands or rollout depth.

python -m sdetkit adoption-surface --root . --out build/sdetkit/adoption-surface.json --format text

The command writes a deterministic JSON artifact at build/sdetkit/adoption-surface.json by default. It detects repository evidence such as languages, package managers, CI systems, security tools, artifact surfaces, and recommended proof commands.

Safety boundary:

• it does not run the recommended proof commands
• it does not install dependencies
• it does not apply patches
• it does not authorize automation or merge
• the emitted payload keeps automation_allowed=false, merge_authorized=false, and semantic_equivalence_proven=false

Use this artifact as an operator handoff before expanding into CI rollout, investigation, or portfolio automation.

Contract expectations

Public kit commands are contract-oriented:

• machine-readable JSON with schema_version
• deterministic ordering and reproducible artifacts
• stable exit-code lanes (0 success, 1 policy/contract failure, 2 invalid input/usage)

Boost Scan Engine (advanced but supported)

boost scan is a deterministic local-only repo intelligence surface that ranks important local signals into one concise operator report.

Posture:

• no external services
• no network dependency
• stable machine-readable output via operator-json

Recommended first command:

python -m sdetkit boost scan . --minutes 5 --max-lines 100 --format text

Operator JSON contract example:

python -m sdetkit boost scan . --minutes 5 --max-lines 100 --format operator-json

The v1 report (default mode) includes decision, score, top risks, recommended fixes, high-signal files, next PR candidates, and evidence files.

Boost Scan v2 (adaptive mode)

When --deep and/or --learn is enabled, Boost Scan switches to adaptive schema sdetkit.boost.scan.v2.

• --deep builds repo index evidence via the local index engine.
• --learn initializes and ingests into local SQLite adaptive memory.
• --db sets adaptive DB path (local file, do not commit).
• --index-out sets index evidence output location.
• --evidence-dir writes boost-scan.json, boost-scan.txt, index.json, and memory evidence files when learning.

Examples:

python -m sdetkit boost scan . --deep --learn --db .sdetkit/adaptive.db --max-lines 100 --format text
python -m sdetkit boost scan . --deep --learn --db .sdetkit/adaptive.db --format operator-json
python -m sdetkit boost scan . --index-out build/sdetkit-index --evidence-dir build/boost-scan --format operator-json

Related references

• Command surface inventory (stability-aware)
• Stability levels
• Versioning and support posture
• Command taxonomy
• Umbrella architecture

sdetkit adoption-surface --format report

Render a Markdown-style operator readiness report while also writing the deterministic adoption-surface JSON artifact:

python -m sdetkit adoption-surface --root . --out build/sdetkit/adoption-surface.json --format report

Use this report for review-first adoption planning. It does not authorize automation, patch application, merging, or semantic-equivalence claims.