Skip to main content

Trail CLI

Use verdictan trail for immutable audit evidence about control-plane actions and changes. It complements, but does not replace, runtime Events queried through verdictan events or the Events API and capture-enabled History.

SurfaceBest used for
verdictan events or the Events APIRuntime governance outcomes and request-policy activity
HistoryCaptured conversation or session artifacts when capture is enabled
TrailAuditable actors, resources, changes, chronology, and integrity evidence

Look up events​

Look up one request:

verdictan trail lookup --request-id 660e8400-e29b-41d4-a716-446655440000

Or filter the audit stream:

verdictan trail lookup \
  --org-id 550e8400-e29b-41d4-a716-446655440000 \
  --event-source identity_access \
  --resource-type Role \
  --resource-id role-production-reviewer \
  --limit 100

The token selects the organization. Optional --org-id is a safety assertion. The CLI calls GET /v1/whoami and stops if the authenticated organization does not match. It does not send this value as an organization selector.

Available filters include event source, event name, resource type, resource ID, actor ARN, start time, and end time. --limit defaults to 100 and accepts 1–1,000. General queries default to the last 24 hours and cannot span more than seven days. Specified boundaries must be RFC3339 timestamps with the start earlier than the end. Add --json for the API response.

Use the narrowest time and resource scope that answers the investigation. Request-ID lookup is a dedicated path. Do not use it with broad assumptions about nearby events.

Verify integrity​

Verify an organization window:

verdictan trail verify \
  --org-id 550e8400-e29b-41d4-a716-446655440000 \
  --start-time 7d

Without start and end dates, the command uses the last seven days through the time when it runs. --start-time accepts an ISO 8601 timestamp or a relative value such as 7d. --end-time accepts ISO 8601.

The standard procedure verifies stored digest-to-digest links in the selected window. It does not do cryptographic DSSE-envelope verification.

Deep verification gets the events in the selected window. It calculates each record hash again. It also verifies that sequence numbers have no gaps. It verifies links in the same window:

verdictan trail verify \
  --org-id 550e8400-e29b-41d4-a716-446655440000 \
  --start-time 2026-07-01T00:00:00Z \
  --end-time 2026-07-15T00:00:00Z \
  --deep \
  --json

Deep verification accepts a maximum 90-day window. The first event or digest in each bounded result has no previous record in that result. The check does not examine its inbound link. An empty window, equal boundaries, an end before the start, a gap, or a hash/link mismatch exits nonzero.

Use adjacent windows with set boundaries for a longer review. Overlap the windows when boundary continuity is important. Alternatively, verify boundary continuity independently. Preserve each result.

To examine if one event's recorded hash is available:

verdictan trail verify --event-id 770e8400-e29b-41d4-a716-446655440000

Single-event verification fetches the event. It verifies only that record_hash is available and is not empty. It does not calculate that hash again or verify chain continuity. Plain and JSON modes use a nonzero exit code when the hash is missing.

Export evidence​

Export an organization window:

verdictan trail export \
  --org-id 550e8400-e29b-41d4-a716-446655440000 \
  --start-time 2026-07-01T00:00:00Z \
  --end-time 2026-07-08T00:00:00Z \
  --output evidence.jsonl

Supported formats are json, jsonl, and csv. jsonl is the default. The command accepts an RFC3339 window of seven days maximum and paginates until it has fetched each matching event. It creates the destination only after it fetches all pages and finds one or more events. An empty result exits nonzero and does not create or truncate the destination.

An empty page with a continuation cursor or a duplicate cursor also fails closed before file creation. An output name ending in .gz creates gzip-compressed output:

verdictan trail export \
  --org-id 550e8400-e29b-41d4-a716-446655440000 \
  --format csv \
  --output evidence.csv.gz

Event-source and event-name filters can narrow the export. Record the command parameters, file digest, export time, and reviewer with the evidence handoff. Store exported content according to your retention and access policy because audit records can contain sensitive metadata.

Verification workflow​

  1. Capture the organization, UTC window, request ID, actor, and resource where available.
  2. Use lookup to make sure that the scope contains the specified records.
  3. Run standard or deep verify for the same window.
  4. Export that same scope.
  5. Hash the exported file with your approved evidence tooling.
  6. Preserve the CLI JSON result and all detected gaps.
  7. Escalate a failed integrity result.
  8. Do not relabel a failed result as an export that succeeded.

Authentication and locality​

Trail commands are API-backed and support --profile, --region, --api-url, and --config. Authenticate with VERDICTAN_API_TOKEN or a stored profile from verdictan auth login. The caller must have the applicable Trail permissions: lookup and filtered export use org:trail:read. Window verification uses org:trail:admin. The token and region select the scope. Use optional --org-id when automation must fail on an unexpected authenticated organization.

Next steps​