CLI reference #

The full command list below is generated from testerkit itself.

Installation #

pip install testerkit       # PyPI name is testerkit; the import is `testerkit`
testerkit --help

After install, testerkit is on $PATH.

Commands #

testerkit benchmark {#cli-benchmark} #

Measure this machine's per-store performance.

testerkit catalog (group) {#cli-catalog} #

Catalog commands.

testerkit catalog datasheet {#cli-catalog-datasheet} #

Generate a formatted datasheet from a catalog YAML file.

testerkit daemon (group) {#cli-daemon} #

Manage TesterKit background daemons (events / runs / channels).

testerkit daemon restart {#cli-daemon-restart} #

Restart selected daemons (SIGTERM the running process; respawn on next access).

testerkit daemon status {#cli-daemon-status} #

Show running daemons, their PIDs, refs, and locations.

(no options or arguments.)

testerkit daemon stop {#cli-daemon-stop} #

Stop selected daemons without respawning.

testerkit data (group) {#cli-data} #

Data retention and management.

testerkit data import {#cli-data-import} #

Merge another data_dir into this one; the store daemons rebuild from the files.

testerkit data index (group) {#cli-data-index} #

Runs-index (DuckDB) epoch lifecycle tooling.

testerkit data index build {#cli-data-index-build} #

Eagerly build/warm the CURRENT runs-index epoch (blocks until warm).

testerkit data index list {#cli-data-index-list} #

List every runs-index epoch by fingerprint, versions, rows, size, last seen.

testerkit data index prune {#cli-data-index-prune} #

Remove stale runs-index epochs by last-access (never the current epoch).

testerkit data index rm {#cli-data-index-rm} #

Delete one runs-index epoch file by fingerprint prefix.

testerkit data promote {#cli-data-promote} #

Move a starter project's local runs + their referenced data to the global store.

testerkit data prune {#cli-data-prune} #

Delete date-partitioned data older than the specified period.

testerkit data reindex {#cli-data-reindex} #

Kill index daemons and rebuild on next access.

testerkit discover {#cli-discover} #

Scan for available instruments.

testerkit docs (group) {#cli-docs} #

Stream the shipped documentation to stdout.

testerkit docs list {#cli-docs-list} #

List available documentation pages, optionally filtered to SECTION.

testerkit docs show {#cli-docs-show} #

Print the named documentation page to stdout.

testerkit export {#cli-export} #

Export a test run or session to a different format via event replay.

testerkit grafana (group) {#cli-grafana} #

Grafana dashboard provisioning and data server.

testerkit grafana export {#cli-grafana-export} #

Export dashboards and provisioning templates for manual setup.

testerkit grafana serve {#cli-grafana-serve} #

Start the pgwire server for Grafana.

testerkit grafana setup {#cli-grafana-setup} #

Install provisioning config and dashboards into Grafana.

testerkit init {#cli-init} #

Initialize a new TesterKit project.

testerkit instrument (group) {#cli-instrument} #

Instrument management commands.

testerkit instrument cal {#cli-instrument-cal} #

Update calibration information for an instrument.

testerkit instrument list {#cli-instrument-list} #

List all instrument configuration files.

testerkit instrument show {#cli-instrument-show} #

Show details for a specific instrument.

testerkit mcp (group) {#cli-mcp} #

MCP server commands for AI-assisted workflows.

testerkit mcp serve {#cli-mcp-serve} #

Start the MCP server for AI agents.

testerkit metrics (group) {#cli-metrics} #

Manufacturing-test analytics (yield, pareto, ppk, trend, retest, time-loss).

testerkit metrics pareto {#cli-metrics-pareto} #

Top failures (Pareto). Group by part / step / measurement.

testerkit metrics ppk {#cli-metrics-ppk} #

Process performance (Ppk/Pp) per measurement.

testerkit metrics retest {#cli-metrics-retest} #

Retest rates: how often UUTs are retried.

testerkit metrics summary {#cli-metrics-summary} #

Yield summary: FPY, final yield, run counts, RTY, DPMO, DPPM, duration stats.

testerkit metrics time-loss {#cli-metrics-time-loss} #

Time lost to failures and errors.

testerkit metrics trend {#cli-metrics-trend} #

Yield trend over time.

testerkit new-test {#cli-new-test} #

Scaffold a new test file.

testerkit runs {#cli-runs} #

List recent test runs.

testerkit sbom {#cli-sbom} #

Export CycloneDX SBOM for a test run's software environment.

testerkit schema (group) {#cli-schema} #

JSON Schema generation for YAML validation.

testerkit schema export {#cli-schema-export} #

Export JSON Schema files for all TesterKit YAML types.

testerkit schema refresh {#cli-schema-refresh} #

Refresh .vscode/schemas/ and .vscode/settings.json after a TesterKit upgrade.

testerkit serve {#cli-serve} #

Start the operator UI server.

testerkit setup (group) {#cli-setup} #

Configure AI tool integrations.

testerkit setup claude-code {#cli-setup-claude-code} #

Configure TesterKit MCP server for Claude Code.

testerkit setup claude-desktop {#cli-setup-claude-desktop} #

Configure TesterKit for Claude Desktop.

testerkit setup cline {#cli-setup-cline} #

Configure TesterKit MCP server for Cline (VS Code extension).

testerkit setup codex {#cli-setup-codex} #

Configure TesterKit for OpenAI Codex.

testerkit setup copilot {#cli-setup-copilot} #

Configure TesterKit for GitHub Copilot (VS Code + CLI).

testerkit setup cursor {#cli-setup-cursor} #

Configure TesterKit for Cursor.

testerkit setup show {#cli-setup-show} #

Show current MCP server configuration.

(no options or arguments.)

testerkit show {#cli-show} #

Show details for a specific test run.

testerkit station (group) {#cli-station} #

Station management commands.

testerkit station init {#cli-station-init} #

Initialize a new station configuration.

testerkit station update {#cli-station-update} #

Re-discover and update instrument identity in configuration.

testerkit station validate {#cli-station-validate} #

Validate station instruments against configuration.

testerkit validate {#cli-validate} #

Validate YAML configuration files.

Test phase #

test_phase tags every run with the maturity tier it was produced for (development, validation, characterization, production). It lands on every parquet row so dashboards and queries can filter by phase.

Setting the phase #

Resolution order (first match wins):

1. pytest --test-phase=<phase> — explicit per-run.
2. TESTERKIT_TEST_PHASE env var.
3. Default — development when neither is set.

Git-status and mock enforcement #

Non-development phases require a clean git repository and real instruments. Uncommitted changes (or no git at all), or running with --mock-instruments, force the stamp down to development regardless of what was requested — a production-tagged row is then always reproducible from a commit hash and came from real hardware. (Profile selection still honors the requested phase; only the recorded stamp is demoted.)

Query by phase #

import duckdb
 
duckdb.sql("""
    SELECT * FROM read_parquet('data/runs/**/*.parquet')
    WHERE test_phase = 'production'
""")
 
# Exclude dev work
duckdb.sql("""
    SELECT * FROM read_parquet('data/runs/**/*.parquet')
    WHERE test_phase != 'development'
""")

See Profiles for the profile YAML shape.

Environment variables #

Exit codes #

See also #

• Platform architecture — what each entry point owns
• MCP tools — the agent-side parallel to most testerkit subcommands
• Configuration — YAML files the CLI reads
• API reference — HTTP routes the testerkit serve UI mounts