custodian audit list

custodian audit list presents the vault's audit trail: every recorded event, newest first, following the trail to its end rather than stopping at the first page. It renders identities only — the principal, the device asserted, the record, the field, the permitting grant and the caller's context — and never a field value, which the trail does not hold. It is how a regulatory question about who read what is answered.

The trail is reserved for operators. Be signed in with an operator token first.

custodian audit list --vault acme

2026-08-21 14:02:07 +00:00  agent-claims  agent     read_token      dev_9Xy4…*  rec_8VN2QJ4KpR  holder_tax_id  grant#12  task=nightly-claims lease=lease_5f3a
2026-08-21 09:15:44 +00:00  ops-admin     operator  read_plaintext  —           rec_8VN2QJ4KpR  premium        grant#4   (no lease or task)
* device asserted by the caller, not verified

Each device is marked * because the trail records the device the caller asserted; the server never proved the caller held that device's key. Token and masked reads are sampled, so when the result includes any, a note on standard error says the count is a lower bound — one sampled row can stand for several reads.

Narrowing the trail

Each filter restricts the trail to events matching one field. Combine them to bound a question at both ends.

• --collection <name> — one collection.
• --field <name> — one field.
• --action <action> — one read, write or lifecycle action.
• --record <id> — one record, by its identifier.
• --principal <slug> — one principal.
• --device <id> — what one machine did.
• --since <duration|timestamp> — a lower time bound, e.g. 30d or an ISO 8601 timestamp.
• --until <duration|timestamp> — an upper time bound, same grammar as --since.
• --limit <n> — stop after n rows. When more match, a note says so and tells you to re-run without --limit for the whole window.
• --utc — render times in UTC instead of the host time zone.

custodian audit list --vault acme --collection policies --since 30d

--devices — the device-lifecycle preset

--devices is a preset that restricts the trail to the device-lifecycle actions — device_enrolled and device_revoked — so you can review the enrolment chain. It is distinct from --device, which asks what one machine did, and it cannot be combined with --action:

custodian audit list --vault acme --devices

At present this returns an empty result. The two device-lifecycle actions the preset selects are part of the audit action set, but nothing in the deployment records them yet, so there is nothing for the preset to show. The command prints no rows and, on standard error, notes that this is a fact about what the trail records, not about the vault, and points you to custodian doctor for the vault's live device list rather than its enrolment history.

Passing both --devices and --action is refused:

Use either --devices (the device-lifecycle actions) or --action <action>, not both — they name the same filter two ways.

--json

--json emits one JSON object per event, newline-delimited, carrying every field unaltered — including the raw timestamp and the sample rate — so no formatting choice reaches a machine reader.

custodian audit list --vault acme --json

The HTTP surface these events come from, and the exact shape of each, is described at the audit API.