Configuration and CLI

marginci.yml uses strict schema version 1. Unknown fields, duplicate keys, ambiguous numeric values and unsupported options are errors with field paths. No confidence interval, bootstrap or population estimate is configured. gate.confidence and --confidence return migration errors.

This configuration shows the required structure for an OpenAI-compatible operation. Replace your-model-id with the exact requested and returned model ID, and replace the illustrative rates and request bound with your own economic values. These numbers are not provider prices. Configure your application endpoint and model separately; running the operation can incur provider charges.

version: 1
providers:
  openai:
    base_url: https://api.openai.com/v1
    credential_env: OPENAI_API_KEY
    max_request_usd: 0.01
    models:
      your-model-id:
        input_per_million: 0.1
        output_per_million: 0.2
        cached_input_per_million: 0.05
operations:
  research:
    command: node marginci/research.cjs
    comparison_files: [marginci/research.cjs]
    providers: [openai]
    cases:
      - id: company-a
        input: {query: example.com}
    compare: {against: HEAD}
    gate:
      metric: cost_per_success
      max_regression: 20%
      max_spend_usd: 1
    limits:
      max_cases: 50
      max_attempts: 1
      max_requests: 50
      timeout_ms: 30000
      max_response_bytes: 2097152

Call your own application with matching provider/model configuration and your chosen rates. Credential values belong in environment variables, not YAML. credential_env names the variable required before dispatch; it does not reconfigure your SDK or choose a model. Legacy configs may omit it, in which case credential provisioning remains entirely application-owned. An absent configured OpenAI model table, Firecrawl credit rate or Exa valuation choice is an ERROR before dispatch. Requests naming unpriced models are blocked before dispatch; an unexpected response model or missing cache rate still invalidates measurement.

Field	Meaning/default
`command`	One Node invocation, directly or through a resolved npm/pnpm script
`comparison_files`	Default empty for compatibility; golden path lists wrapper and input/helper files that must be committed and identical on both sides
`cases`	Explicit IDs/input; default one `case-1`; 1–200 distinct IDs
`compare.against`	Local `origin/HEAD`; `--against` overrides; no automatic fetch
`gate.max_regression`	Nonnegative fraction or percent, default 0.20; max 10 (1000%); equality passes
`gate.max_spend_usd`	Positive numeric USD model budget across the whole check; default 1; no `$` prefix
`max_request_usd`	Required positive reservation per billable request/resource
`limits`	Defaults shown above; max_attempts ≤3, timeout ≤300000 ms, response ≤16777216 bytes
`dependencies.production_only`	Default false; explicit true installs only production dependencies identically on both sides

Numeric syntax is nonnegative decimal (including supported scientific notation). Empty, negative, nonfinite, hexadecimal and coercive values fail. max_spend_usd is a number; the CLI equivalent is --max-spend 1.

./node_modules/.bin/marginci init
./node_modules/.bin/marginci doctor research --against HEAD
./node_modules/.bin/marginci test research --against HEAD --json
./node_modules/.bin/marginci test research --against HEAD --max-regression 20% --max-spend 1 --cases company-a --verbose
./node_modules/.bin/marginci test research --against HEAD -- node marginci/research.cjs

The final form shares the explicit command override. A selected subset becomes the declared workload and is recorded. All overrides are captured in the frozen effective config/identity. --json always emits one JSON document; verbose progress goes to stderr. --version and --help are available.

Optional results: results: {format: jsonl, path: .marginci/results.jsonl}. The runner deletes stale results and supplies MARGINCI_RESULTS_PATH. Each process writes exactly one { "case_id": "company-a", "success": true } line with no extra fields or duplicate keys. Nonzero exit/signal overrides true; missing/ambiguous output invalidates coverage. Without JSONL, exit status supplies success.

Cases receive MARGINCI_CASE_ID, MARGINCI_CASE_JSON and MARGINCI_ATTEMPT_ID. Whole-operation retries run in new processes, keep failed spend and count at most one success per case. SDK retries count as additional observed requests. No hidden provider retry is added.

free_egress optionally contains exact nonprovider origins and an ≥8-character explanation of zero variable economic value. This is a user assertion, never a provider-host bypass. Do not exclude paid downstream work.