Tracevity CLI

A trace tells you what was recorded. Tracevity tells you what you can reconstruct from it.

This is the release README for the authorized 0.5.5 Public Beta distribution. Its presence in the source tree does not establish that PyPI or the canonical documentation domain currently serves the release; the install and documentation links below become observed release facts only after exact package and provider readbacks.

Tracevity is a deterministic, local tool for evaluating the evidentiary sufficiency of AI-agent activity traces. Inspect evaluates one selected execution against named reconstruction requirements. Gate compares an accepted baseline with a release or migration candidate and reports requirement-level reconstruction regressions.

Tracevity is not a telemetry collector, hosted trace viewer, generic semantic-convention checker, or certification service. Your trace and correlated evidence remain on the machine or CI runner where the command executes.

Install

Use an isolated tool environment when possible:

pipx install tracevity==0.5.5

or:

uv tool install tracevity==0.5.5

Conventional installation is also supported:

python -m pip install tracevity==0.5.5

Tracevity 0.5.5 supports CPython 3.11, 3.12, 3.13, and 3.14. Its operational dependency closure is limited to pinned OTLP protobuf definitions and protobuf itself.

tracevity --version, the current Inspector engine, and the current Gate engine all identify version 0.5.5. Current reports use additive Reconstruction Report v0.2 and Gate Report v0.2 contracts. Historical v0.1 reports remain readable; their historical engine identities are not rewritten. Exact packaged engine and resource bytes contribute to report build identity, so changes remain visible and sealed reports are never treated as interchangeable without an exact compatibility check.

Quickstart

Download, verify, and extract the safe synthetic example bundle from tracevity.com/cli, then run these commands from the extracted bundle directory. No production trace is needed.

tracevity --version

tracevity traces list --manifest inspect/manifest.json

tracevity inspect \
  --manifest inspect/manifest.json \
  --requirements inspect/requirements.json \
  --out reconstruction-report.json

tracevity gate \
  --suite gate/tracevity-gate.json \
  --out tracevity-gate-report.json

traces list returns bounded structural information for explicit target selection. It does not print prompts, outputs, tool arguments, tool results, or arbitrary captured attributes.

Capture and destination evidence

Start the bounded loopback receiver before running an OTLP HTTP/protobuf exporter:

tracevity capture otlp \
  --listen 127.0.0.1:4318 \
  --out trace.otlp.pb \
  --receipt capture-receipt.json

The receiver accepts only /v1/traces on IPv4 loopback, enforces request, byte, span, and idle-time bounds, combines valid batches, and never uploads or prints captured values.

Tracevity ships one deliberately narrow, read-only destination adapter:

tracevity evidence github issue-comment \
  --repo OWNER/REPOSITORY \
  --comment-id COMMENT_ID \
  --out github-evidence.json

It reads exactly one existing issue or pull-request comment from api.github.com. Public comments can be read without authentication. For private repositories or higher rate limits, set TRACEVITY_GITHUB_TOKEN in the environment; command-line tokens and custom API origins are not accepted. The envelope stores a body SHA-256, not the comment body. Provider API retrieval is external-system evidence with unverified record authenticity; HTTPS, ETags, and request IDs are not cryptographic proof.

Render either report locally as inert HTML and/or Markdown:

tracevity report render reconstruction-report.json \
  --html reconstruction-report.html \
  --markdown reconstruction-report.md

Supported trace declarations

The Inspector accepts OTLP trace protobuf for four exact declared representations:

OTLP logs and metrics are recognized but unsupported as primary trace inputs. A structurally valid OTLP payload does not prove producer identity, complete capture, or semantic sufficiency.

Gate exits

Gate compares reconstruction consequences for named requirements, not raw span counts or field sets. Replayable baseline and candidate inputs run through the same current Inspector. An incompatible sealed report yields INCOMPARABLE_REQUIRES_REBASE; it is never silently accepted.

Privacy, network, and semantic limits

inspect, gate, traces list, and report render make no network requests. capture otlp opens only the loopback listener the operator requests. The GitHub evidence adapter makes one explicit, bounded outbound read to the official GitHub REST API. No command contacts a Tracevity service, emits Tracevity analytics, calls a model, uploads a trace, creates an account, performs an update check, sends a crash report, or keeps a hidden input cache. Trace contents remain local and are never executed.

Keep these boundaries explicit:

tool success != external settlement
agent identity != initiating principal
valid OTLP != sufficient reconstruction
recorded rationale != hidden reasoning
Gate pass != certification

Tracevity reports what supplied evidence establishes for a named use case. An exactly correlated provider record can corroborate destination state without becoming cryptographically authenticated. Tracevity does not reveal true latent motivation, prove omitted evidence never existed, certify an arbitrary producer, or turn a tool-reported result into independently verified external state.

Documentation and feedback

• CLI documentation
• Inspector
• Gate
• Methodology
• Bug reports and corrections
• Private security report

Never post production traces, prompts, outputs, credentials, secrets, customer data, or private logs to a public issue.

License

Files included in the public Python distribution and its bundled public runtime resources are licensed under Apache-2.0. See LICENSE-CLI in the distribution. That scoped license does not relicense the private Tracevity monorepo or material not included in the wheel/source distribution.