Skip to main content

Trail CLI

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

SurfaceBest used for
kt 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:

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

Or filter the audit stream:

kt 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 is never sent 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. Explicit 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 combine it with broad assumptions about nearby events.

Verify integrity​

Verify an organization window:

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

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

Standard verification checks stored digest-to-digest links inside the selected window. It does not perform cryptographic DSSE-envelope verification.

Deep verification fetches the events in the selected window and recomputes each record hash, checks consecutive sequence numbers, and checks links between events in that same window:

kt 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 is limited to a 90-day window. The first event or digest in each bounded result has no preceding record in that result, so its inbound link is not checked. An empty window, equal boundaries, reversed boundaries, a gap, or a hash/link mismatch exits nonzero. Split a longer review into explicit adjacent windows, overlap or separately establish boundary continuity when that matters, and preserve every result.

To inspect one event's recorded hash presence:

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

Single-event verification fetches the event and checks only that record_hash is present and nonempty. It does not recompute that hash or check chain continuity. Both plain and JSON modes exit nonzero when the hash is absent.

Export evidence​

Export an organization window:

kt 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 a maximum seven-day RFC3339 window and paginates until it has fetched every matching event. It creates the destination only after all pages are fetched and at least one event exists; an empty result exits nonzero and does not create or truncate the destination. An empty page with a continuation cursor or a repeated cursor also fails closed before file creation. An output name ending in .gz produces gzip-compressed output:

kt 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, exact UTC window, request ID, actor, and resource where available.
  2. Use lookup to confirm that the scope contains the expected records.
  3. Run standard or deep verify for the same window.
  4. Export that exact scope.
  5. Hash the exported file with your approved evidence tooling.
  6. Preserve the CLI JSON result and any detected gaps.
  7. Escalate a failed integrity result; do not relabel it as a successful export.

Authentication and locality​

Trail commands are API-backed and support --profile, --region, --api-url, --api-token, and --config. The caller needs the applicable Trail permissions: lookup and filtered export use org:trail:read; window verification uses org:trail:admin. The token and region choose the scope; use optional --org-id when automation should fail on an unexpected authenticated organization.

Next steps​