Skip to content

CLI and Config

Initialize A Starter

Use groundguard-init to create a minimal config and sample files:

groundguard-init --template github-action

Available templates:

groundguard-init --template github-action
groundguard-init --template openai
groundguard-init --template promptfoo
groundguard-init --template langgraph
groundguard-init --template pydanticai
groundguard-init --template crewai
groundguard-init --template autogen
groundguard-init --template fastapi

The command writes groundguard.yml, groundguard-ledger.jsonl, answer.txt, and a small template-specific starter file. Existing files are not overwritten unless you pass --force.

Generate a Report

groundguard-report \
  --ledger-jsonl facts.jsonl \
  --answer-file answer.txt \
  --required-fact revenue_2025 \
  --schema assertion \
  --fail-on-policy

Use groundguard.yml

Start from the repository sample:

cp groundguard.example.yml groundguard.yml

required_facts:
  - revenue_2025
policy:
  allow_candidate_matches: false
  on_contradicted: block
  on_unverified: flag
units:
  tolerance: 0.005
report:
  schema: assertion
  format: json
  fail_on_policy: true

groundguard-report --config groundguard.yml --ledger-jsonl facts.jsonl --answer-file answer.txt

CLI flags extend or override the config where appropriate. For example, additional --required-fact values are appended to required_facts.

Render Human Reports

groundguard-report \
  --config groundguard.yml \
  --ledger-jsonl facts.jsonl \
  --answer-file answer.txt \
  --format markdown \
  --output groundguard-report.md

Supported formats are json, markdown, html, and github. The github format is a compact Markdown body designed for PR comments.

Reports include matched_fact_key, ledger_value, answer_value, and start:end spans for claim highlighting and review UIs.

Scoped Extractor Packs

extractors:
  packs:
    - finance
    - saas
    - ops

Extractor packs are resolved per report run. They do not mutate the global process registry, so they are safe to use in multi-tenant services.

Built-in packs cover common labels for finance (revenue, gross_margin, eps), SaaS (arr, mrr, churn, nrr, cac, ltv), ecommerce (gmv, orders, conversion_rate, aov), and ops (p95_latency, error_rate, uptime, throughput, storage).