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
    export             Export events to external formats (SIEM, etc.)

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.

With the --dataset flag the command switches to Training Data Compliance Scanner mode: it recursively scans a dataset directory or file and produces a signed EU AI Act Article 10 compliance report instead of running event-schema validation.

Usage

# Event schema validation
spanforge validate EVENTS_JSONL

# Training dataset EU AI Act Article 10 scan (CARD 1C-4)
spanforge validate --dataset PATH [--output report|json] [--no-sign]

EVENTS_JSONL : Path to a JSONL file (one serialised Event JSON object per line). Optional when --dataset is supplied.

Dataset scanner flags

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

Example — dataset scan (Article 10 report)

$ spanforge validate --dataset ./data/training/ --output report

## EU AI Act Article 10 Compliance Report

scan_id            : 01HWXYZ...
scanned_at         : 2026-05-10T14:32:00Z
dataset_path       : ./data/training
file_count         : 3
row_count          : 1 200
token_estimate     : 48 000
pii_density_score  : 0.08
consent_coverage   : 96.7 %
provenance_coverage: 100.0 %
bias_signal        : low

| Clause        | Title                                      | Result |
|---------------|--------------------------------------------|--------|
| Art.10(2)(a)  | Data quality — PII density                 | PASS   |
| Art.10(2)(b)  | Data governance — consent documentation    | PASS   |
| Art.10(2)(c)  | Data collection — source provenance        | PASS   |
| Art.10(2)(d)  | Bias detection — vocabulary distribution   | PASS   |

hmac_signature: hmac-sha256:3d9f...

Example — dataset scan JSON output

$ spanforge validate --dataset ./data/training/ --output json
{
  "scan_id": "01HWXYZ...",
  "scanned_at": "2026-05-10T14:32:00Z",
  "dataset_path": "./data/training",
  "file_count": 3,
  "row_count": 1200,
  "token_estimate": 48000,
  "pii_density_score": 0.08,
  "consent_coverage_pct": 96.7,
  "provenance_coverage_pct": 100.0,
  "bias_signal": "low",
  "eu_ai_act_article_10_clauses": [...],
  "hmac_signature": "hmac-sha256:3d9f..."
}

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-dataset

Recursively scan a training dataset directory or file and produce a signed EU AI Act Article 10 compliance report. Supports .jsonl, .json, .csv, .txt, and .parquet files.

Usage

spanforge compliance validate-dataset PATH [--output report|json|pdf] [--no-sign]

Options

Article 10 clauses checked

Exit codes

Example — clean dataset

$ spanforge compliance validate-dataset ./data/training/ --output report
...
| Art.10(2)(a) | Data quality — PII density              | PASS |
| Art.10(2)(b) | Data governance — consent documentation | PASS |
| Art.10(2)(c) | Data collection — source provenance     | PASS |
| Art.10(2)(d) | Bias detection — vocabulary distribution| PASS |
hmac_signature: hmac-sha256:3d9f...
$ echo $?
0

Example — dataset with PII

$ spanforge compliance validate-dataset ./data/raw/ --output json | python -m json.tool
{
  "eu_ai_act_article_10_clauses": [
    {"clause_id": "Art.10(2)(a)", "passed": false, "detail": "PII density 3.42 ≥ 1.0 threshold"},
    ...
  ]
}
$ echo $?
1

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, reset).

Usage

spanforge dev [start|stop|status|reset]

dev reset

Wipe local development state (trace store, audit chain, schema cache). Optionally delete ~/.spanforge/config.yaml with --hard.

Usage

spanforge dev reset [--hard] [--dry-run]

Options

Exit codes

Example — soft reset (data files only)

$ spanforge dev reset
[✓] Trace store cleared
[✓] Audit chain cleared
[✓] Schema cache cleared

Example — dry run

$ spanforge dev reset --dry-run
[dry-run] Would remove: ~/.spanforge/traces.db
[dry-run] Would remove: ~/.spanforge/audit.jsonl
[dry-run] Would remove: ~/.spanforge/schema_cache/

Example — hard reset (also removes config)

$ spanforge dev reset --hard
This will delete ~/.spanforge/config.yaml. Continue? [y/N]: y
[✓] Config deleted: ~/.spanforge/config.yaml
[✓] Trace store cleared

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 management commands. Includes scanning source files for leaked credentials (secrets scan) and managing a local encrypted secrets store (secrets set, secrets get, secrets list, secrets delete).

secrets set

Store a named secret in the local encrypted secrets store (~/.spanforge/secrets.db). Values are base64-encoded and persisted as JSON.

Usage

spanforge secrets set KEY VALUE

Positional arguments

Exit codes

Example

$ spanforge secrets set OPENAI_KEY sk-abc123
[✓] Secret 'OPENAI_KEY' stored.

secrets get

Retrieve and print a named secret from the local secrets store.

Usage

spanforge secrets get KEY

Exit codes

Example

$ spanforge secrets get OPENAI_KEY
sk-abc123

secrets list

List all key names stored in the local secrets store (values are not shown).

Usage

spanforge secrets list

Exit codes

Example

$ spanforge secrets list
OPENAI_KEY
LANGCHAIN_API_KEY
DATADOG_API_KEY

secrets delete

Remove a named secret from the local secrets store.

Usage

spanforge secrets delete KEY

Exit codes

Example

$ spanforge secrets delete OPENAI_KEY
[✓] Secret 'OPENAI_KEY' deleted.

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 ~/.spanforge/config.yaml and .halluccheck.toml validation.

config init

Generate ~/.spanforge/config.yaml with sensible defaults. Runs an interactive wizard by default; pass --non-interactive to write defaults without prompts.

Usage

spanforge config init [--non-interactive] [--force]

Options

Exit codes

Example — interactive

$ spanforge config init
SpanForge Config Wizard
-----------------------
Exporter [console/jsonl/sqlite/otlp/webhook/datadog/grafana_loki] (console):
Service name (my-service):
Environment [dev/staging/prod] (dev):
[✓] Config written: ~/.spanforge/config.yaml
    Exporter:      console
    Service name:  my-service
    Environment:   dev

Example — non-interactive

$ spanforge config init --non-interactive
[✓] Config written: ~/.spanforge/config.yaml
    Exporter:      console
    Service name:  my-service
    Environment:   dev

config validate

Validate a config file against the SpanForge schema. By default checks ~/.spanforge/config.yaml; pass --config PATH to check a specific file. Optionally probe OTLP endpoint connectivity with --check-connectivity.

Usage

spanforge config validate [--config PATH] [--check-connectivity] [--file PATH]

Options

Exit codes

Example — validate default config

$ spanforge config validate
[✓] Config is valid: ~/.spanforge/config.yaml

Example — explicit path

$ spanforge config validate --config /etc/spanforge/prod.yaml
[✓] Config is valid: /etc/spanforge/prod.yaml

Example — with connectivity check

$ spanforge config validate --check-connectivity
[✓] Config is valid: ~/.spanforge/config.yaml
[✓] Connectivity: OTLP endpoint localhost:4317 reachable

Example — validation errors

$ spanforge config validate --config bad.yaml
Config validation failed (2 error(s)):
  - Unknown key 'spanforge.foo' (not in schema)
  - 'spanforge.log_level' must be one of DEBUG/INFO/WARNING/ERROR/CRITICAL, got 'VERBOSE'

Using in CI (GitHub Actions)

- name: Validate SpanForge config
  run: spanforge config validate --config .spanforge/config.yaml

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

export

Export SpanForge events to external SIEM formats (CARD 1E-1).

export siem

Convert a JSONL events file to ArcSight CEF or IBM LEEF strings for ingestion by any SIEM via syslog or file ingestion.

Usage

spanforge export siem [--format cef|leef] [--input FILE]

Options

Output

One formatted SIEM line per event, written to stdout. Invalid lines are skipped with an error to stderr.

Exit codes

Examples

# Convert events.jsonl to CEF (default)
spanforge export siem --input events.jsonl

# Convert to LEEF and forward to syslog
spanforge export siem --format leef --input events.jsonl | logger -n siem.corp.example -P 514

# Pipe from another command
spanforge validate events.jsonl | spanforge export siem --format cef

CEF format

CEF:0|SpanForge|SDK|<version>|<event_type>|<event_type>|<severity>|event_id=... event_type=... timestamp=...

LEEF format

LEEF:2.0|SpanForge|SDK|<version>|<event_type>	event_id=...	event_type=...	timestamp=...

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

event

Event management utilities.

event create

Create one or more synthetic SpanForge events and write them to a JSONL file or stdout. Useful for fixture generation and load testing.

Usage

spanforge event create --type TYPE [--payload JSON|@FILE] [--count N] [--output FILE] [--format jsonl|json]

Options

Examples

# Single event to stdout
spanforge event create --type llm.trace.span.completed

# 100 events, JSON array output to file
spanforge event create --type llm.trace.span.completed --count 100 --output fixtures.jsonl

# Custom payload from a JSON file
spanforge event create --type agent.step.started --payload @payload.json --count 5

explain

Generate a signed explainability record for a runtime decision. The record is emitted into the audit store and can be retrieved via the operator workflow.

Usage

spanforge explain --trace-id ID --agent-id ID --decision-id ID --summary TEXT

Options

Example

spanforge explain \
  --trace-id trace-123 \
  --agent-id claims-agent \
  --decision-id dec-456 \
  --summary "Escalated because grounding confidence 0.62 fell below threshold 0.85"

operator

Operator workflow inspection and evidence export.

operator inspect

Inspect a runtime-governance trace workflow — displays the policy decision, explanation, scope, RBAC, and lineage evidence for a given trace in a single summary view.

Usage

spanforge operator inspect TRACE_ID [--format text|json]

Options

Example

spanforge operator inspect trace-abc123
spanforge operator inspect trace-abc123 --format json

operator export

Export a signed evidence package for a trace to a JSON file or stdout. The package contains all governance evidence (policy decisions, explanations, scope, RBAC, lineage) as a signed bundle suitable for audit handover.

Usage

spanforge operator export TRACE_ID [--output PATH] [--format text|json]

Options

Example

spanforge operator export trace-abc123 --output evidence-package.json

consent

Consent boundary management for data-subject rights workflows (GDPR / DPDP).

consent check

Check whether consent is currently granted for a subject/scope pair.

spanforge consent check --subject USER_ID --scope SCOPE

consent grant

Grant consent for a subject/scope pair.

spanforge consent grant --subject USER_ID --scope SCOPE [--purpose PURPOSE] [--legal-basis BASIS]

Options

consent revoke

Revoke consent for a subject/scope pair.

spanforge consent revoke --subject USER_ID --scope SCOPE

Example workflow

spanforge consent grant  --subject alice --scope analytics --purpose "product improvement"
spanforge consent check  --subject alice --scope analytics
spanforge consent revoke --subject alice --scope analytics

hitl

Human-in-the-loop review queue. Manages pending decisions that have been escalated for human review.

hitl pending

List all pending items in the HITL review queue.

spanforge hitl pending

hitl review

Record a review outcome for a pending item.

spanforge hitl review --id DECISION_ID --reviewer REVIEWER --outcome approved|rejected

Options

Example

# Check queue
spanforge hitl pending

# Approve a decision
spanforge hitl review --id dec-789 --reviewer alice --outcome approved

model

Model registry management. Track, deprecate, and retire AI model versions.

model list

List all models registered in the model registry.

spanforge model list

model register

Register a new model in the registry.

spanforge model register \
  --model-id MODEL_ID \
  --name NAME \
  --version VERSION \
  --risk-tier low|medium|high|critical \
  --owner OWNER \
  --purpose PURPOSE

Options

model deprecate

Mark a model as deprecated.

spanforge model deprecate --model-id MODEL_ID [--reason TEXT]

model retire

Retire a model (permanently removed from active use).

spanforge model retire --model-id MODEL_ID

Example workflow

spanforge model register \
  --model-id gpt-claims-v2 \
  --name "Claims Classifier v2" \
  --version 2.1.0 \
  --risk-tier high \
  --owner platform-team \
  --purpose "Classify incoming claims for routing"

spanforge model list
spanforge model deprecate --model-id gpt-claims-v1 --reason "Superseded by v2"
spanforge model retire    --model-id gpt-claims-v1