Skip to content

getting-started.md

Latest commit

 

History

History
135 lines (98 loc) · 4.35 KB

getting-started.md

File metadata and controls

135 lines (98 loc) · 4.35 KB
Raw

Getting Started

This guide keeps the shortest path to a working cleanr run. Use it when you want to validate one target quickly, then branch into the deeper docs only where needed.

Pick an Install Path

  • CLI: go install github.com/devr-tools/cleanr/cmd/cleanr@latest
  • Release binary: download a tagged archive from GitHub Releases
  • Container: pull ghcr.io/devr-tools/cleanr:<tag>

The repository root README has the copy-paste install commands.

Generate a Starter Config

For a local interactive setup:

cleanr setup

For CI-safe config generation:

cleanr setup --ci -provider openai -model gpt-4.1-mini -output cleanr.yaml

For staged pipeline scaffolding:

cleanr setup --ci -provider openai -model gpt-4.1-mini -profile pr -output .cleanr/pr.yaml
cleanr setup --ci -provider openai -model gpt-4.1-mini -profile main -output .cleanr/main.yaml
cleanr setup --ci -provider openai -model gpt-4.1-mini -profile release -output .cleanr/release.yaml

When you keep staged configs under .cleanr/, select them with -profile or CLEANR_PROFILE:

cleanr validate -profile pr
cleanr run -profile main
CLEANR_PROFILE=release cleanr snapshot

If you prefer to start from checked-in examples instead of the setup flow, use one of:

  • examples/openai-responses.yaml
  • examples/openai-chat-completions.yaml
  • examples/anthropic-messages.yaml
  • examples/containerized-assistant/cleanr.yaml
  • examples/openai-responses-tuned.yaml
  • examples/best-practices/cleanr-pr.yaml
  • examples/best-practices/cleanr-main.yaml
  • examples/best-practices/cleanr-release.yaml
  • examples/stateful-support-agent/cleanr.yaml

Validate and Run

cleanr validate -config cleanr.yaml
cleanr run -config cleanr.yaml

Common CI-oriented outputs:

cleanr run -config cleanr.yaml -format junit -output cleanr-junit.xml
cleanr run -config cleanr.yaml -trend-file reports/cleanr.trends.yaml -build-id "$GITHUB_SHA"
cleanr run -config cleanr.yaml -replay-artifact reports/cleanr.replay.json -build-id "$GITHUB_SHA"

Capture a Baseline

Before enabling drift gates in CI, capture a known-good snapshot:

cleanr snapshot -config cleanr.yaml

Commit the resulting snapshot file once it reflects expected behavior.

Review Scenario Datasets

If you generate scenarios or export replay failures, review them before merging them into your runnable config:

cleanr dataset review \
  -input generated/cleanr.dataset.yaml \
  -base-config cleanr.yaml \
  -output reviewed/cleanr.reviewed.yaml

Apply explicit review decisions and write an updated config with only approved scenarios:

cleanr dataset review \
  -input generated/cleanr.dataset.yaml \
  -profile pr \
  -approve refund-policy \
  -reject duplicate-password-reset \
  -promote-stable refund-policy \
  -set-metadata refund-policy:owner=qa \
  -merge-output .cleanr/pr.reviewed.yaml

The review artifact ranks candidates by usefulness, marks duplicates, shows field-level diff status against the current config, and preserves replay or generation provenance for approved scenarios.

For local curation, -interactive opens a richer local review flow. In a terminal it now runs as a structured Bubble Tea TUI with single-key actions, panel layout, and inline editing; when stdin/stdout are not TTYs it falls back to the line-oriented command loop. Both paths let you approve, reject, promote, retag, and edit metadata per scenario before the reviewed artifact is written:

cleanr dataset review \
  -interactive \
  -input generated/cleanr.dataset.yaml \
  -base-config cleanr.yaml \
  -output reviewed/cleanr.reviewed.yaml

If you are iterating on the review UI itself, run the focused local test target:

make test-review-ui

To open the live terminal preview against a canned sample dataset:

make preview-review-ui

Choose the Next Guide

  • Configuration: target fields, suites, thresholds, and reporting options
  • Best practices: staged rollout guidance for PR, main, nightly, and release pipelines
  • SDK guide: embed cleanr as a Go package
  • Docker guide: run cleanr from GHCR in pipelines
  • CI guide: wire reports, artifacts, and exit codes into automation
  • Release automation: understand the repo's CD and publishing flow