opstruth

Read-only operational truth checks for AI-assisted engineering.

The canonical website is opstruth.io, and the independent hosted MCP service is mcp.opstruth.io/mcp. Deployment receipts are indexed in the owned-domain cutover evidence.

AI coding tools are fast, but developers still need proof:

• what changed
• what is configured
• what looks risky
• what was verified
• what was not verified

opstruth is a stack-aware, read-only CLI. It inspects the repo, detects the stack, runs safe probes, collects evidence, explains risks, and produces a proof-oriented report.

opstruth

Example Output

Cleaned example from a fixture run:

STATUS: Partial pass

What Matters Most
- No failures

Verified
- Project boundary: /tmp/opstruth-fixture-runs/vite-react-app
- Probe catalogue entries: 30
- Automatic safe probes selected: 15
- Project language detected: TypeScript
- Platforms detected: TypeScript, React, Vite, Node ESM

Skipped Or Not Configured
- routes.head_root: Not relevant to detected stack or missing configuration
- local.ports: Not relevant to detected stack or missing configuration

Not Verified
- Production/public route availability was not checked
- Local runtime liveness was not checked

Overall Confidence
Basic checks passed. Runtime or production verification may still be incomplete.

Install

Published package:

npm install -g opstruth
opstruth

One-off usage:

npx opstruth

GitHub Actions:

- uses: AyobamiH/opstruth@v1
  with:
    output_path: evidence/opstruth.md

The Marketplace action runs the bundled CLI source with contents: read sufficient for repository evidence. It writes only the configured local evidence report and does not deploy, push, merge, publish, or mutate target systems. See GitHub Marketplace action.

The latest published npm package is opstruth@0.2.0. This is an early public testing release, not a claim of mature production coverage.

Local development:

git clone https://github.com/AyobamiH/opstruth.git
cd opstruth
cd cli
npm install
npm link
opstruth

Release:

https://github.com/AyobamiH/opstruth/releases/tag/v0.2.0

Commands

opstruth
opstruth welcome
opstruth init
opstruth repo
opstruth quality
opstruth github-ci --workflow CI
opstruth routes --base-url https://example.com
opstruth secrets
opstruth supabase
opstruth supabase-live --evidence-file <redacted.json>
opstruth supabase-live --telemetry-file /tmp/opstruth-supabase-telemetry.json
opstruth cloudflare
opstruth local --port 3000 --health /health
opstruth evidence
opstruth probes

Useful flags:

opstruth --strict
opstruth --json
opstruth --out evidence/opstruth.md
opstruth --skip routes
opstruth --only secrets
opstruth --color
opstruth --no-color
NO_COLOR=1 opstruth

Human terminal output is colourised when supported, using the same calm status language as the website. Use --no-color or NO_COLOR=1 to disable colour, or --color to force colour for terminal demos. --json remains machine-readable and ANSI-free.

Safety Model

opstruth is read-only by default. It does not:

• deploy
• mutate databases
• trigger jobs or queues
• publish content
• call OpenAI
• restart services
• kill processes
• print raw secrets

Skipped is not failed. Unverified is not safe. opstruth reports proof gaps instead of pretending they are confidence.

Secret scans group findings into actionable source findings, documentation references, placeholders/examples, local-only files, generated/dependency paths, ignored binaries, and unknown review items. See docs/secret-reference-classification.md.

Quality checks report lint, typecheck, tests, build, and CI as distinct proof signals. See docs/quality-proof-signals.md.

GitHub Actions proof is explicit and exact-commit matched. Use opstruth github-ci or opstruth --github-ci when hosted CI metadata should be attached to the proof record. CI remains separate from production proof. See docs/github-actions-proof.md.

Supabase live proof is explicit and local-file driven. Use opstruth supabase-live --evidence-file <redacted.json> or opstruth supabase-live --telemetry-file /tmp/opstruth-supabase-telemetry.json to validate already collected production evidence without making Supabase calls, inspecting secret values, or mutating anything. See docs/supabase-live-proof.md.

Completion Gate

Codex work in this repo is not complete until the completion gate has run and the final report includes proof:

./scripts/opstruth-completion-gate.sh

See docs/completion-gate.md.

Who It Is For

• Codex users
• Cursor users
• Claude Code users
• Lovable, Replit, and bolt users
• solo founders
• agencies
• developers reviewing AI-generated changes

Focused Diagnostic Reviews

Start with the open-source CLI. If an opstruth report exposes risk you cannot interpret safely, the same evidence can frame a focused diagnostic review for an AI-built website, app, automation, or deployment setup.

A deeper review can look at repo structure, deployment path, secret exposure risk, runtime checks, and the proof gaps to resolve before production changes. opstruth supports that review workflow; it does not replace a security audit or guarantee that an app is safe.

For now, open a GitHub issue with the evidence pack and the narrow question you need answered.

Example Workflows

Before trusting AI changes:

opstruth

Before deployment, with public route evidence:

opstruth --base-url https://example.com

Local runtime check:

opstruth local --port 3000 --health /health

CI:

opstruth --strict --out evidence/opstruth.md

Inspect the probe catalogue:

opstruth probes

Real-World Validation

The Wagging Web Wins case study documents an OpsTruth-style review of a real app repo: authorization hardening, scheduler proof gaps, secret-boundary handling, GitHub PR gates, and the deliberate stop before Supabase mutation.

See docs/case-studies/wagging-web-wins.md.

Project Boundaries

If opstruth starts inside a git repository, the git root is the project boundary. If no git repository is detected, opstruth scans only the current directory with safety ignores and prints:

No git repository detected. opstruth is scanning the current directory with safety ignores. For best results, run inside a project repo.

Probe Catalogue

The initial catalogue covers:

• git status, diff checks, diff stats, log context, and merge conflict marker scan
• Node, TypeScript, Vite, Next.js, React, ESLint, Vitest, Playwright, and package scripts
• route and local runtime checks when explicitly configured
• secret and risky reference scans with redaction
• static Supabase, Cloudflare/Wrangler, Docker, GitHub Actions, Vercel, and Netlify detection

Each probe defines what evidence it collects, what it proves, what it does not prove, and the next safe step.

The current catalogue also reports skipped-probe reasons, explicit inputs required, proof limitations, and metadata suitable for JSON automation:

opstruth probes --json

See docs/probe-quality-model.md for the maturity model.

Configuration

Create a starter config:

opstruth init --yes

opstruth.config.json can provide route paths, local ports/health paths, secret-scan allowlists, and explicit GitHub CI proof settings. The one-command run uses supported route and local config inputs when present; without CLI flags or config, runtime checks stay skipped and are reported as proof gaps. GitHub CI metadata is opt-in through --github-ci or github.ci.enabled.

See docs/configuration.md.

Current Limitations

• Some probes are static-only.
• Route checks need --base-url or route config.
• Local runtime checks need --port, --health, process, or service inputs.
• GitHub Actions checks need opstruth github-ci, --github-ci, or explicit config opt-in.
• opstruth@0.2.0 is the latest published package.
• opstruth is not a replacement for a security audit.
• opstruth does not prove production state unless you provide production/staging route or runtime inputs.

Development

This repository is a monorepo:

• cli/ contains the opstruth package and probe implementation.
• website/ contains the Lovable/TanStack frontend.
• docs/ and evidence/ contain project documentation and proof outputs.

CLI checks:

cd cli
npm run lint
npm test
node bin/opstruth.js
./scripts/demo-fixtures.sh

Website checks:

cd website
npm run lint
npm run build

Fixture evidence is written to root evidence/fixture-runs/.

Website Deployment

The production website is served by Cloudflare Workers:

https://opstruth.io

Lovable is the frontend editing surface, not the production deployment source. Production deploys run from the canonical monorepo through .github/workflows/deploy-cloudflare.yml, using only GitHub repository secrets for Cloudflare credentials. Website dependencies stay in website/package.json.

See docs/deployment.md and docs/cloudflare-deployment.md for the deployment model and local preview commands.

Website Videos

The current website videos are generated from inspected repo, source CLI, npm, GitHub release, and Cloudflare production truth:

website/public/demo/opstruth-hero-runtime-truth.mp4
website/public/demo/opstruth-current-runtime-truth.mp4

The older website/public/demo/opstruth-runtime-truth.mp4 asset is historical launch material, not the current product truth source. See docs/current-video-truth-brief.md for the video evidence brief.