Command-Line Interface

spanforge ships a command-line tool, spanforge, for operational tasks. The entry-point is installed automatically when you pip install spanforge.

spanforge --help

usage: spanforge [-h] [-V] <command> ...

spanforge command-line utilities

positional arguments:
  <command>
    check              End-to-end health check: validates config, emits a test
                       event, confirms export pipeline
    check-compat       Check a JSON file of events against the v1.0
                       compatibility checklist
    list-deprecated    Print all deprecated event types from the global
                       deprecation registry
    migration-roadmap  Print the planned v1 → v2 migration roadmap
    check-consumers    Assert all registered consumers are compatible with the
                       installed schema
    validate           Validate every event in a JSONL file against the
                       published schema
    audit-chain        Verify HMAC signing chain integrity of events in a
                       JSONL file
    audit              Audit chain management (erase, rotate-key, check-health,
                       verify)
    scan               Scan a JSONL file for PII using regex detectors
    migrate            Migrate a JSONL file from schema v1 to v2
    inspect            Pretty-print a single event by event_id from a JSONL
                       file
    stats              Print a summary of events in a JSONL file (counts,
                       tokens, cost, timestamps)
    compliance         Compliance evidence generation and attestation
                       validation
    cost               Cost brief management
    dev                Local development environment lifecycle
    module             SpanForge plugin module scaffolding
    serve              Start a local HTTP trace viewer at /traces (default
                       port 8888)
    init               Scaffold a spanforge.toml config file in the current
                       directory
    quickstart         Interactive setup wizard: configure exporter, service
                       name, and signing
    report             Generate a static HTML trace report from a JSONL events
                       file
    eval               Evaluation dataset management and scorer execution
    migrate-langsmith  Convert a LangSmith export file to SpanForge events
    ui                 Open a local HTML trace viewer in your browser
    secrets            Secrets scanning commands (scan files for credentials)
    gate               CI/CD gate pipeline (run YAML pipelines, evaluate gates, trust-gate)
    config             Configuration management (validate .halluccheck.toml)
    trust              T.R.U.S.T. scorecard (scorecard, badge, gate)
    enterprise         Enterprise multi-tenancy, encryption, health
    security           OWASP audit, STRIDE threat model, dependency scan
    doctor             Environment diagnostics: config, sandbox, service health

options:
  -h, --help           show this help message and exit
  -V, --version        show program's version number and exit

--version

Print the installed version and conformance profile label, then exit.

spanforge --version
spanforge -V

Example output

spanforge 2.0.13 [spanforge-Enterprise-2.0]

The bracketed label is CONFORMANCE_PROFILE from spanforge.CONFORMANCE_PROFILE (RFC §1.5). Use this to verify that your installed SDK declares the correct conformance class.

check

Runs a five-step end-to-end health check of the spanforge installation:

1. Configuration loaded and valid
2. An Event can be created with required fields
3. The event passes JSON Schema validation
4. The export pipeline initialises and accepts the test event
5. The TraceStore is accessible

Usage

spanforge check

Exit codes

Example — passing

$ spanforge check
[1/5] Config ............. OK
[2/5] Event creation ..... OK
[3/5] Schema validation .. OK
[4/5] Export pipeline .... OK
[5/5] Trace store ........ OK
All checks passed.

check-compat

Validate a batch of serialised events against the spanforge v1.0 compatibility checklist (CHK-1 through CHK-5). Useful in CI pipelines, pre-commit hooks, and onboarding audits for third-party tool authors.

Usage

spanforge check-compat EVENTS_JSON

EVENTS_JSON : Path to a JSON file containing a top-level array of serialised Event objects (the output of [evt.to_dict() for evt in events]).

Exit codes

Example — passing

$ spanforge check-compat events.json
OK — 42 event(s) passed all compatibility checks.

Example — violations found

$ spanforge check-compat events.json
FAIL — 2 violation(s) found in 42 event(s):

  [01JPXXX...] CHK-3 (Source identifier format): source 'MyTool/1.0' does not match ...
  [01JPYYY...] CHK-5 (Event ID is a valid ULID): event_id 'not-a-ulid' is not a valid ULID

Example — generating an events file

import json
from spanforge import Event, EventType

events = [
    Event(
        event_type=EventType.TRACE_SPAN_COMPLETED,
        source="my-tool@1.0.0",
        payload={"span_name": "chat"},
    )
    for _ in range(5)
]

with open("events.json", "w") as f:
    json.dump([evt.to_dict() for evt in events], f, indent=2)

Using in CI (GitHub Actions)

- name: Validate event compatibility
  run: |
    python -c "
    import json
    from spanforge import Event, EventType
    events = [Event(event_type=EventType.TRACE_SPAN_COMPLETED,
                    source='my-tool@1.0.0', payload={'ok': True})]
    with open('/tmp/events.json', 'w') as f:
        json.dump([e.to_dict() for e in events], f)
    "
    spanforge check-compat /tmp/events.json

Compatibility checks

The check-compat command applies these checks to every event:

Programmatic usage (no CLI required)

The same checks are available directly in Python:

from spanforge.compliance import test_compatibility

result = test_compatibility(events)
if not result:
    for v in result.violations:
        print(f"[{v.check_id}] {v.rule}: {v.detail}")

See spanforge.compliance for the full compliance API.

list-deprecated

Print all deprecation notices from the global DeprecationRegistry.

Usage

spanforge list-deprecated

Example output

Deprecated event types (4 total):
  llm.cache.evicted → llm.cache.entry_evicted (since 1.0.0, sunset 2.0.0)
  llm.cost.estimate → llm.cost.estimated (since 1.0.0, sunset 2.0.0)
  llm.eval.regression → llm.eval.regression_failed (since 1.0.0, sunset 2.0.0)
  ...

The registry is pre-populated at startup with all entries from v2_migration_roadmap(). Additional notices registered at runtime via mark_deprecated() are also included.

migration-roadmap

Print the structured Phase 9 v2 migration roadmap.

Usage

spanforge migration-roadmap [--json]

Options

Example — table output

v2 Migration Roadmap (9 entries)
===================================
llm.cache.evicted
  Since:       1.0.0
  Sunset:      2.0.0
  Policy:      NEXT_MAJOR
  Replacement: llm.cache.entry_evicted
  Notes:       Rename for namespace consistency.

...

Example — JSON output

spanforge migration-roadmap --json | python -m json.tool

check-consumers

Print all consumers registered in the global ConsumerRegistry and check their compatibility with the installed schema version.

Usage

spanforge check-consumers

Exit codes

Example output — all compatible

Registered consumers (2 total):
  billing-agent    namespaces=(llm.cost.*,)          requires=1.0  [OK]
  analytics-agent  namespaces=(llm.trace.*, llm.eval.*)  requires=1.1  [OK]

All consumers are compatible with installed schema version 1.0.0.

Example output — incompatible

Registered consumers (1 total):
  future-tool  namespaces=(llm.trace.*,)  requires=2.0  [INCOMPATIBLE]

ERROR: 1 consumer(s) require a schema version not satisfied by 1.0.0.

validate

Validate every event in a JSONL file against the published v2.0 JSON Schema. Useful for checking that events emitted by third-party integrations conform to the canonical schema before ingestion.

Usage

spanforge validate EVENTS_JSONL

EVENTS_JSONL : Path to a JSONL file (one serialised Event JSON object per line).

Exit codes

Example — all valid

$ spanforge validate events.jsonl
OK — 128 event(s) are all schema-valid.

Example — validation errors

$ spanforge validate events.jsonl
FAIL — 2 event(s) failed schema validation:

  Line 14: missing required field 'source'
  Line 37: 'event_type' value 'foo.bar' is not a registered EventType

audit-chain

Verify the HMAC-SHA256 signing chain of a JSONL file produced when signing_key was set via configure(). Detects tampering, deletions, and out-of-order events.

The signing secret is read from the spanforge_SIGNING_KEY environment variable.

Usage

spanforge_SIGNING_KEY=my-secret spanforge audit-chain EVENTS_JSONL

Exit codes

Example — intact chain

$ spanforge_SIGNING_KEY=secret spanforge audit-chain events.jsonl
OK — chain of 50 event(s) is intact. No tampering or gaps detected.

Example — tampered chain

FAIL — chain verification failed:
  Event 01JPXXX... signature mismatch (tampered or wrong key)
  Gap detected: event 01JPYYY... has no prev_id link to prior event

inspect

Look up a single event by its event_id in a JSONL file and pretty-print it as indented JSON. Useful for debugging a specific event without loading the whole file.

Usage

spanforge inspect EVENT_ID EVENTS_JSONL

Exit codes

Example

$ spanforge inspect 01JPXXXXXXXXXXXXXXXXXXX events.jsonl
{
  "event_id": "01JPXXXXXXXXXXXXXXXXXXX",
  "schema_version": "2.0",
  "event_type": "llm.trace.span.completed",
  "source": "my-app@1.0.0",
  ...
}

stats

Print a human-readable summary of all events in a JSONL file: total count, breakdown by event type, total input/output tokens, estimated cost, and the timestamp range of the events.

Usage

spanforge stats EVENTS_JSONL

Exit codes

Example

$ spanforge stats events.jsonl
Events:  342 total
Types:
  llm.trace.span.completed  : 300
  llm.cost.token_recorded   :  42
Tokens:  input=48 200  output=12 300  total=60 500
Cost:    $0.1820 USD
Range:   2026-03-04T08:00:00Z → 2026-03-04T09:15:33Z

compliance

Generate compliance evidence packages and validate attestations against regulatory frameworks. Supports EU AI Act, ISO 42001, NIST AI RMF, GDPR, and SOC 2.

compliance generate

Generate a full compliance evidence package (JSON) including clause mappings, gap analysis, and HMAC-signed attestations. Attestations are automatically enriched with model registry metadata (model_owner, model_risk_tier, model_status, model_warnings) and explanation_coverage_pct when corresponding telemetry events are present.

The engine maps event prefixes to regulatory clauses including:

• consent.* / hitl.* → GDPR Art. 22, EU AI Act Art. 14
• explanation.* → EU AI Act Art. 13, NIST MAP 1.1
• model_registry.* → SOC 2 CC6.1, NIST MAP 1.1

Gap clauses now include a remediation hint in the JSON output under gap_data.remediation[<clause_id>] — an actionable fix command you can run immediately to close the gap.

Usage

spanforge compliance generate --model-id MODEL_ID --framework FRAMEWORK --from FROM_DATE --to TO_DATE [--events-file EVENTS_JSONL]

Options

Example

spanforge compliance generate --model-id gpt-4o --framework eu_ai_act --from 2026-01-01 --to 2026-03-31 --events-file events.jsonl

compliance report

Export a rendered compliance report to disk.

Usage

spanforge compliance report --model-id MODEL_ID --framework FRAMEWORK --from FROM_DATE --to TO_DATE [--format FORMAT] [--output DIR]

Options

Choosing markdown writes <prefix>_report.md — a human-readable Markdown document suitable for sharing with stakeholders or importing into Notion/Confluence. Choosing both writes both the JSON evidence package and the Markdown report simultaneously.

Example

# Markdown report for a quarterly EU AI Act review
spanforge compliance report --model-id gpt-4o --framework eu_ai_act \
  --from 2026-01-01 --to 2026-03-31 --format markdown

# Full package: JSON + Markdown
spanforge compliance report --model-id gpt-4o --framework soc2 \
  --from 2026-01-01 --to 2026-03-31 --format both --output ./reports

compliance readiness

Run a pre-audit configuration check — no events required. Inspects your current SpanForge configuration and answers: "What do I need to turn on before I hire an auditor?"

Usage

spanforge compliance readiness [--framework FRAMEWORK]

Options

What is checked

Exit codes

Example

$ spanforge compliance readiness --framework eu_ai_act
SpanForge Compliance Readiness — EU AI Act
========================================================
  [✓] SPANFORGE_SIGNING_KEY is set to a non-default value
  [✓] Durable exporter configured (current: 'sqlite')
  [✗] PII redaction enabled (redact_pii=True)
         Fix: spanforge.configure(redact_pii=True)
  [✗] Drift detection enabled (drift_detection=True)
         Fix: spanforge.configure(drift_detection=True)

Readiness: 3/5 checks passing (60%)

[!] Fix 2 item(s) above before starting your audit engagement.

compliance check

Run a CI-friendly compliance gate against an events file and audit period.

Usage

spanforge compliance check --framework FRAMEWORK --from FROM_DATE --to TO_DATE [--events-file EVENTS_JSONL]

compliance validate-attestation

Verify the HMAC-SHA256 attestation signature inside an evidence package.

Usage

spanforge compliance validate-attestation EVIDENCE_JSON

compliance status

Output a single JSON summary of compliance posture from an events file. Includes chain integrity, PII scan results, per-clause coverage, last attestation timestamp, and event count.

Usage

spanforge compliance status --events-file EVENTS.jsonl [--framework FRAMEWORK]

Options

Example

spanforge compliance status --events-file traces.jsonl --framework gdpr

Exit codes

serve

Start a local HTTP server that serves the SPA trace viewer at /traces. Requires enable_trace_store=True in configuration.

The viewer includes a compliance dashboard (click the compliance chip in the header) showing:

• Chain integrity — verified / not verified / tampered status
• Overview stats — total events, signed events, PII hits, explanation coverage
• Clause pass/fail tables — per-framework breakdown (SOC 2, HIPAA, GDPR, etc.)
• Model registry — all models observed in event payloads with counts and sources

Usage

spanforge serve [--port PORT]

Options

Example

spanforge serve --port 9000

ui

Open a self-contained HTML trace viewer in your default browser.

Usage

spanforge ui [EVENTS_JSONL]

cost

Cost tracking and analysis commands.

cost brief submit

Submit a cost brief JSON file to the local brief store.

Usage

spanforge cost brief submit --file BRIEF_JSON [--store STORE_JSON]

Options

cost run

Show a per-run cost breakdown for a single agent run. Reads a JSONL events file, filters llm.cost.* and llm.trace.agent.completed events by run ID, and prints a per-model cost table.

Usage

spanforge cost run --run-id RUN_ID --input EVENTS_JSONL

Options

Example

$ spanforge cost run --run-id 01JPXXXXXXXX --input events.jsonl
==============================================================
  SpanForge Per-Run Cost Report
==============================================================
  Run ID         : 01JPXXXXXXXX
  Agent          : research-agent
  Status         : ok
  Duration       : 2,340.0 ms
  Total cost     : $0.005200
  Input tokens   : 1,024
  Output tokens  : 384
  LLM calls      : 3
--------------------------------------------------------------
  Cost by model:
  Model                          Calls  Input $   Output $    Total $
  ------------------------------ ----- --------- --------- ----------
  gpt-4o                             2 $0.002560 $0.001920  $0.004480
  gpt-4o-mini                        1 $0.000077 $0.000115  $0.000192
==============================================================

Exit codes

dev

Local development environment lifecycle commands (start, stop, status).

Usage

spanforge dev [start|stop|status]

module

Scaffold a new spanforge plugin module with boilerplate files.

Usage

spanforge module MODULE_NAME

init

Scaffold a spanforge.toml configuration file in the current directory.

Usage

spanforge init

quickstart

Interactive setup wizard that walks you through configuring an exporter, service name, and signing key.

Usage

spanforge quickstart

scan

Scan a JSONL audit file for PII using built-in regex detectors (SSN, credit card, email, phone, etc.). Useful as a CI gate or pre-export validation step.

Usage

spanforge scan FILE [--format {text,json}] [--types TYPES] [--fail-on-match]

Positional arguments

Options

Exit codes

Example — basic scan

$ spanforge scan audit.jsonl
Scanned 128 event(s): 3 PII hit(s) found.
  ssn          payload.user_info.id     (2 matches, sensitivity=high)
  credit_card  payload.payment.card_no  (1 match,  sensitivity=high)

Example — CI gate with type filter

spanforge scan audit.jsonl --types ssn,credit_card --fail-on-match --format json

India PII (DPDP Act)

For Indian data protection compliance, use DPDP_PATTERNS programmatically with scan_payload():

from spanforge import scan_payload, DPDP_PATTERNS

result = scan_payload(event.payload, extra_patterns=DPDP_PATTERNS)
# Detects Aadhaar (with Verhoeff checksum) and PAN numbers

Built-in types: email, phone, ssn, credit_card, ip_address, uk_national_insurance, date_of_birth (global formats: ISO, US, day-first DMY, written-month), address. DPDP add-on types: aadhaar (high), pan (high).

migrate

Migrate a JSONL file from schema v1.0 to v2.0. Applies field renames (model → model_id), tag coercion, and md5 → sha256 checksum re-hashing.

Usage

spanforge migrate FILE [--output FILE] [--target-version VER] [--sign] [--dry-run]

Positional arguments

Options

Exit codes

Example

$ spanforge migrate audit.jsonl --sign
Migrated 120/128 events → audit_v2.jsonl
Skipped: 8 (already v2.0), Errors: 0
Transformed: payload.model→model_id (45), checksum.md5→sha256 (12)

Example — dry run

$ spanforge migrate audit.jsonl --dry-run
[DRY RUN] Would migrate 120/128 events, skip 8

audit

The audit command groups audit chain management sub-commands for GDPR erasure, key rotation, health checks, and chain verification.

audit erase

GDPR subject erasure: replaces events mentioning a subject with tombstone records while preserving chain integrity.

Usage

spanforge audit erase EVENTS_JSONL --subject-id ID [--erased-by WHO] [--reason TEXT] [--request-ref REF] [--output FILE]

Options

audit rotate-key

Rotate the HMAC signing key in a JSONL audit file. Re-signs the entire chain with the new key and verifies the result.

Usage

spanforge audit rotate-key EVENTS_JSONL [--new-key-env VAR] [--output FILE] [--reason TEXT]

Options

Example

$ SPANFORGE_SIGNING_KEY=old-key SPANFORGE_NEW_SIGNING_KEY=new-key \
    spanforge audit rotate-key audit.jsonl --output audit_rotated.jsonl
Rotated 128 event(s) → audit_rotated.jsonl
Chain re-verified: OK

audit check-health

Run health checks on a JSONL audit file: PII scan, chain integrity, egress configuration, and configuration validation.

Usage

spanforge audit check-health EVENTS_JSONL [--output {text,json}]

Options

Exit codes

Example

$ spanforge audit check-health audit.jsonl --output json
{
  "config": "OK",
  "chain_integrity": "OK",
  "pii_scan": "WARN: 2 PII hits",
  "egress": "OK"
}

audit verify

Verify HMAC chain integrity of one or more JSONL audit files. Supports glob patterns for multi-file verification.

Usage

spanforge audit verify --input FILE_OR_GLOB [--key KEY]

Options

Example

$ spanforge audit verify --input "audit-*.jsonl"
audit-2026-01.jsonl: OK (1200 events, chain intact)
audit-2026-02.jsonl: OK (980 events, chain intact)

report

Generate a static HTML trace report from a JSONL events file.

Usage

spanforge report EVENTS_JSONL [-o OUTPUT_PATH]

eval

Manage evaluation datasets and run built-in quality scorers.

eval save

Extract evaluation examples from a JSONL events file into a reusable dataset.

Usage

spanforge eval save --input EVENTS.jsonl --output DATASET.jsonl

Options

eval run

Run built-in scorers over a JSONL evaluation dataset.

Usage

spanforge eval run --file DATASET.jsonl [--scorers S1,S2,...] [--format text|json]

Options

Example

spanforge eval run --file dataset.jsonl --scorers faithfulness,pii_leakage --format json

Exit codes

migrate-langsmith

Convert a LangSmith export file (JSONL or JSON array) to SpanForge events.

Usage

spanforge migrate-langsmith FILE [--output OUTPUT.jsonl] [--source NAME]

Options

Example

spanforge migrate-langsmith langsmith_export.jsonl --output traces.jsonl

Exit codes

secrets

Secrets scanning commands. Detects credentials, API keys, private keys, and other sensitive material in source files before they are committed or deployed.

secrets scan

Scan a file for secrets using the built-in 20-pattern registry. Suitable as a CI gate, pre-commit hook step, or standalone audit tool.

Usage

spanforge secrets scan FILE [--format {text,json,sarif}] [--redact] [--confidence FLOAT]

Positional arguments

Options

Exit codes

Example — basic scan

$ spanforge secrets scan config.env
[WARN] 2 secret(s) detected in config.env
  AWS_ACCESS_KEY  line 4   confidence=0.97  [auto-blocked]
  STRIPE_KEY      line 9   confidence=0.90

Example — SARIF output for GitHub Code Scanning

spanforge secrets scan src/config.py --format sarif > secrets.sarif

Upload secrets.sarif as a GitHub Code Scanning result to surface findings directly in pull request reviews.

Example — JSON output for CI pipelines

spanforge secrets scan .env --format json

{
  "detected": true,
  "auto_blocked": true,
  "hits": [
    {
      "secret_type": "AWS_ACCESS_KEY",
      "start": 42,
      "end": 62,
      "confidence": 0.97,
      "redacted_value": "[REDACTED:AWS_ACCESS_KEY]"
    }
  ]
}

Example — redact mode

spanforge secrets scan secrets.txt --redact
# Prints file contents with secrets replaced by [REDACTED:TYPE]

Pre-commit hook

Add to .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: spanforge-secrets-scan
        name: SpanForge Secrets Scan
        entry: spanforge secrets scan
        language: python
        types: [text]
        stages: [pre-commit, pre-push]

Or use the built-in hook from .pre-commit-hooks.yaml:

repos:
  - repo: https://github.com/veerarag1973/spanforge
    rev: v2.0.3
    hooks:
      - id: spanforge-secrets-scan

Detected secret types

gate

CI/CD gate pipeline commands. Evaluate quality gates, run YAML pipelines, and enforce release readiness checks before deployment.

gate run

Parse and execute a YAML gate pipeline file. Gates with on_fail: block that evaluate to FAIL exit with code 1. Artifacts are written to the configured artifact directory.

Usage

spanforge gate run GATE_YAML [--context KEY=VALUE ...] [--artifact-dir DIR] [--format {text,json}]

Positional arguments

Options

Exit codes

Example — passing

$ spanforge gate run gates/ci-pipeline.yaml
Running gate pipeline: gates/ci-pipeline.yaml
  [PASS] schema-validation   (4.7 ms)
  [PASS] secrets-scan        (12.3 ms)
  [WARN] dependency-audit    (45.1 ms)  cve_count=1 severity_max=MEDIUM
  [PASS] perf-regression     (8.9 ms)
  [PASS] prri-check          (2.1 ms)   prri_score=28.5 verdict=GREEN
  [PASS] trust-gate          (6.4 ms)
Result: 5 passed, 0 failed, 1 warned

Example — with context variables

spanforge gate run gates/ci-pipeline.yaml --context project_id=my-agent --context env=staging

Example — JSON output for CI dashboards

spanforge gate run gates/ci-pipeline.yaml --format json | python -m json.tool

Using in CI (GitHub Actions)

- name: Run SpanForge gate pipeline
  env:
    SPANFORGE_GATE_ARTIFACT_DIR: .sf-gate/artifacts
    SPANFORGE_GATE_PRRI_RED_THRESHOLD: "65"
  run: spanforge gate run gates/ci-pipeline.yaml

gate evaluate

Evaluate a single named gate against a payload file or standard input.

Usage

spanforge gate evaluate GATE_ID [--payload FILE] [--project-id ID] [--format {text,json}]

Positional arguments

Options

Exit codes

Example

$ spanforge gate evaluate schema-validation --payload event.json
[PASS] schema-validation  (4.2 ms)  valid=true violations=[]

gate trust-gate

Run the composite trust gate check against live telemetry windows. Checks HRI critical rate, PII detection count, and secrets detection count. Blocks (exit code 1) if any threshold is exceeded.

Usage

spanforge gate trust-gate [--project-id ID] [--format {text,json}]

Options

Exit codes

Example — passing

$ spanforge gate trust-gate --project-id my-agent
[PASS] trust-gate
  HRI critical rate:    0.012  (threshold: 0.050)  OK
  PII detections (24h): 0                           OK
  Secrets detections:   0                           OK

Example — blocked

$ spanforge gate trust-gate --project-id my-agent
[FAIL] trust-gate
  HRI critical rate:    0.073  (threshold: 0.050)  EXCEEDED
  PII detections (24h): 3                           EXCEEDED
BLOCKED: 2 trust failure(s)

config

Configuration management commands for .halluccheck.toml validation.

config validate

Validate a .halluccheck.toml config file against the v6.0 schema. Auto-discovers the file from the current directory (or parent directories) when no explicit path is given.

Usage

spanforge config validate [--file PATH]

Options

Exit codes

Example — valid config

$ spanforge config validate
[✓] Config is valid: .halluccheck.toml

Example — explicit path

$ spanforge config validate --file config/staging.toml
[✓] Config is valid: config/staging.toml

Example — validation errors

$ spanforge config validate --file bad.toml
Config validation failed (2 error(s)):
  - Unknown key 'spanforge.foo' (not in v6.0 schema)
  - 'pii.threshold' must be a float between 0.0 and 1.0, got '2.5'

Example — parse error

$ spanforge config validate --file broken.toml
error: Failed to parse broken.toml: Invalid TOML at line 5

Using in CI (GitHub Actions)

- name: Validate SpanForge config
  run: spanforge config validate --file .halluccheck.toml

trust

T.R.U.S.T. scorecard and trust gate commands (Phase 10).

trust scorecard

Display the five-pillar T.R.U.S.T. scorecard as a text table.

Usage

spanforge trust scorecard [--project-id PID]

Options

Exit codes

Example

$ spanforge trust scorecard --project-id my-agent
╔══════════════════════════════════════════════════╗
║          T.R.U.S.T. Scorecard — my-agent         ║
╠══════════════╦═══════╦═══════╦═══════════════════╣
║ Dimension    ║ Score ║ Trend ║ Last Updated       ║
╠══════════════╬═══════╬═══════╬═══════════════════╣
║ Transparency ║  85.0 ║  up   ║ 2025-07-13T10:00Z ║
║ Reliability  ║  90.0 ║  up   ║ 2025-07-13T09:45Z ║
║ UserTrust    ║  78.0 ║ flat  ║ 2025-07-13T08:30Z ║
║ Security     ║  92.0 ║  up   ║ 2025-07-13T10:00Z ║
║ Traceability ║  88.0 ║  up   ║ 2025-07-13T09:00Z ║
╠══════════════╬═══════╩═══════╩═══════════════════╣
║ Overall      ║  86.6  [green]                     ║
╚══════════════╩═══════════════════════════════════╝

trust badge

Write the T.R.U.S.T. SVG badge to stdout.

Usage

spanforge trust badge [--project-id PID]

Options

Exit codes

Example

$ spanforge trust badge --project-id my-agent > trust-badge.svg

trust gate

Run the composite trust gate. Exits with code 1 if the overall T.R.U.S.T. score falls in the red band (< 60).

Usage

spanforge trust gate [--project-id PID]

Options

Exit codes

Example — passing gate

$ spanforge trust gate --project-id my-agent
T.R.U.S.T. gate PASSED: 86.6 [green]

Example — failing gate

$ spanforge trust gate --project-id my-agent
T.R.U.S.T. gate FAILED: 42.0 [red]

Using in CI (GitHub Actions)

- name: T.R.U.S.T. gate check
  run: spanforge trust gate --project-id ${{ env.PROJECT_ID }}

enterprise

Enterprise multi-tenancy and operations commands (Phase 11).

enterprise status

Display the enterprise subsystem status including tenants, encryption, and air-gap configuration.

Usage

spanforge enterprise status [--json]

Options

Exit codes

enterprise register-tenant

Register a new tenant for multi-tenant isolation.

Usage

spanforge enterprise register-tenant --org-id ORG --project-id PROJ [--region REGION]

Options

Exit codes

enterprise list-tenants

List all registered tenants.

Usage

spanforge enterprise list-tenants [--json]

enterprise encrypt-config

Encrypt a configuration value using the enterprise encryption engine.

Usage

spanforge enterprise encrypt-config --value VALUE

enterprise health

Run enterprise health probes (/healthz and /readyz).

Usage

spanforge enterprise health [--json]

Exit codes

security

Supply-chain security and OWASP audit commands (Phase 11).

security owasp

Run an OWASP Top 10 for LLM Applications audit.

Usage

spanforge security owasp [--json]

Exit codes

security threat-model

Generate a STRIDE threat model for the current project.

Usage

spanforge security threat-model [--json]

security scan

Run a full security scan (dependency vulnerabilities + static analysis).

Usage

spanforge security scan [--json]

Exit codes

security audit-logs

Check for secrets leaked in log files.

Usage

spanforge security audit-logs --path PATH [--json]

Options

Exit codes

doctor

Full environment diagnostic (Phase 12, DX-005).

Usage

spanforge doctor

Checks performed:

1. Configuration validity — Verifies spanforge.toml or default settings.
2. Sandbox mode detection — Warns if sandbox mode is active.
3. Per-service health — Pings each SDK client (sf_pii, sf_audit, sf_observe, sf_cec, sf_gate, sf_identity, sf_secrets, sf_alert, sf_config, sf_trust, sf_security).
4. PII engine — Confirms entity types are loaded.
5. Connectivity — Tests reachability of configured endpoints.

Exit codes

Example

$ spanforge doctor
✔ Configuration valid (spanforge.toml)
⚠ Sandbox mode is ACTIVE — no production side effects
✔ sf_pii .............. healthy (local mode)
✔ sf_audit ............ healthy (local mode)
✔ sf_observe .......... healthy (local mode)
✔ sf_cec .............. healthy (local mode)
✔ sf_gate ............. healthy (local mode)
✔ sf_identity ......... healthy (local mode)
✔ sf_secrets .......... healthy (local mode)
✔ sf_alert ............ healthy (local mode)
✔ sf_config ........... healthy (local mode)
✔ sf_trust ............ healthy (local mode)
✔ sf_security ......... healthy (local mode)
✔ PII entity types loaded: 8
✔ Endpoint connectivity: ok

Result: 13 passed, 1 warning, 0 failed

lint (module entry-point)

AST-based instrumentation linter (v1.0.7+, Phase F). Detects missing fields, bare PII strings, unknown event types, and LLM/agent context violations before they reach the export pipeline.

Note: spanforge lint is invoked via the Python module entry-point (python -m spanforge.lint), not as a spanforge sub-command.

Usage

# Check the current directory (recursively)
python -m spanforge.lint .

# Check specific files or directories
python -m spanforge.lint myapp/ src/agents/

# Check a single file
python -m spanforge.lint myapp/pipeline.py

Exit codes

Error codes

Example output

$ python -m spanforge.lint myapp/
myapp/pipeline.py:17:1  AO001 Event() is missing required field 'payload'
myapp/pipeline.py:42:12 AO002 actor_id receives a bare str literal; wrap with Redactable()
myapp/pipeline.py:53:5  AO004 LLM provider call outside tracer span context
3 errors in 1 file.

CI integration

# GitHub Actions
- name: spanforge lint
  run: python -m spanforge.lint myapp/ src/

# Makefile
lint:
	ruff check .
	python -m spanforge.lint myapp/

flake8 / ruff plugin

Once spanforge is installed, AO-codes also appear in flake8 and ruff output automatically. No extra configuration is required.

See also: Linting user guide, API reference