CLI & Commands¶

synthkit ships several binaries under cmd/. All configuration is environment-driven (read from .env or the process environment) unless flags override specific values. Build everything with go build ./....

synthkit — the generator¶

The main binary. Loads all blueprints from the directory named by BLUEPRINTS (default ./blueprints), validates the set, and drives the two-cadence generator loop.

./synthkit [flags]

Verification modes (I32):

# Print the full inventory of distinct series names + label keys — push nothing.
DRY_RUN=true ./synthkit -once -dump

# One live cycle (DRY_RUN=false to push real data).
DRY_RUN=false ./synthkit -once

# The continuous loop (default).
./synthkit

DRY_RUN defaults to true. You must explicitly set DRY_RUN=false to push synthetic data to Grafana Cloud. See Configuration for the full environment variable reference, and Credentials for how the Grafana Cloud tokens are scoped.

The control plane is available at http://<bind>:<port>/control/ (default port 8088). See control-plane.md.

sm-provision — Synthetic Monitoring provisioner¶

One-shot idempotent provisioner for Synthetic Monitoring. Reads blueprints, registers the offline private probe, and creates/updates SM checks in Grafana Cloud. Safe to re-run.

GC_SM_URL=https://synthetic-monitoring-api.grafana.net \
  GC_SM_TOKEN=<sm-bearer-token> \
  DRY_RUN=false \
  go run ./cmd/sm-provision

DRY_RUN=true (the default) prints the planned operations without making any API calls. See synthetic-monitoring.md for the two-phase startup procedure.

blueprint-schema — schema artifact generator¶

Regenerates the blueprint schema artifacts from the live Go types: BLUEPRINT-SCHEMA.md (the human reference) and internal/blueprintschema/fielddocs.json (the embedded field-description index used by the control-plane UI). Run this whenever a blueprint field or construct/workload config changes.

go run ./cmd/blueprint-schema
# or
make blueprint-schema

The gate test TestSchemaCurrent (run by go test ./...) fails if these artifacts drift from the live types. See blueprint-reference.md.

skcapture — environment snapshot tool¶

Inspects a Kubernetes environment via kubectl and writes a versioned, optionally age-encrypted inventory file for later processing by skforge.

skcapture [flags]

skcapture imports only internal/capture and the Go standard library — it has no dependency on any blueprint, construct, or workload package. See tools.md for the full capture-to-blueprint workflow.

skforge — blueprint forge¶

Converts a captured inventory into a synthkit blueprint draft. Three subcommands:

skforge inspect <capture> --key <passphrase-file> [--plain]
skforge prompt  <capture> --key <passphrase-file> [--plain] [--report <path>]
skforge validate <blueprint.yaml>

See tools.md for the full skcapture → skforge → blueprint workflow.

synthkit-dash — dashboard generator¶

Generates Grafana v2 dashboards for a blueprint's synthetic telemetry. Resolves the blueprint, derives the signal manifest, runs registered templates, and writes dashboard JSON files.

go run ./cmd/synthkit-dash -blueprint <path> -out <dir> [flags]

Always emits a thin index dashboard and a metrics dashboard. Per-blueprint templates produce additional dashboards when registered. Generated files are named <dashboard-uid>.json. Push and validate with gcx. See tools.md.

synthkit-control-dash — control dashboard generator¶

Generates the customer self-serve control dashboard: an Infinity-datasource-backed Grafana v2 dashboard exposing the master volume multiplier and incident scenario controls as read panels with native action buttons.

go run ./cmd/synthkit-control-dash -ds-name <name> -out <dir> [flags]

GET routes are open; POST routes use HTTP Basic auth so the browser handles the credential prompt natively — no token is embedded in the dashboard. See tools.md.

make targets¶