cleanr is a Go-based AI testing CLI and SDK for validating AI applications in CI. Use it to generate configs, run suites against providers or HTTP targets, and emit machine-readable reports for release gates.

Install

Recommended:

go install github.com/devr-tools/cleanr/cmd/cleanr@latest
cleanr version

Other install paths:

• GitHub Releases: tagged binaries for direct download
• Homebrew: brew install devr-tools/tap/cleanr
• Source build: make build

Install details and packaging notes live in docs/getting-started.md and docs/homebrew.md.

Quickstart

Generate a config, validate it, and run your first suite:

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

If you prefer an interactive local flow:

cleanr setup
cleanr snapshot -config cleanr.yaml

For staged CI configs:

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

For scenario generation and dataset import flows, start with docs/getting-started.md.

Review generated or replay-backed scenarios before merging them into your checked-in config:

cleanr dataset review -input generated/cleanr.dataset.yaml -base-config cleanr.yaml -output reviewed/cleanr.reviewed.yaml
cleanr dataset review -input reviewed/cleanr.dataset.yaml -profile pr -approve happy-path -promote-regression happy-path -merge-output .cleanr/pr.reviewed.yaml

If you want to review candidates one by one locally, use interactive mode:

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

CI Example

jobs:
  cleanr:
    runs-on: ubuntu-latest
    container: ghcr.io/devr-tools/cleanr:<tag>
    steps:
      - uses: actions/checkout@v4
      - run: cleanr validate -config cleanr.yaml
      - run: cleanr run -config cleanr.yaml -format junit -output cleanr-junit.xml

More CI, Docker, SDK, and release patterns are in docs/ci.md, docs/docker.md, docs/sdk.md, and docs/release-automation.md.

Docs

• Getting started
• SDK guide
• Docker guide
• Configuration
• CI guide
• Buildkite guide
• Best practices
• Release automation
• Homebrew packaging
• MCP and MCPO
• Developer guide
• Docs index

Examples

• OpenAI Responses
• OpenAI Chat Completions
• Anthropic Messages
• Containerized Assistant
• Best Practice Profiles
• Stateful Support Agent

updates