Read the audit log
Find out who changed what on your instance, and when, by reading and filtering its audit log.
Your instance keeps a log of every change, sign-in and export: which agent saved a file, who made a key, when a setting changed, and who exported your data. Marfa writes every entry itself, and nothing can write one for it.
What it records
- Changes to your data: items, tags, links between items, types and files.
- Access: sign-ins, failed ones included, keys made, changed and revoked, apps approved, and folders.
- Settings: your instance's settings, webhooks and connectors.
- Housekeeping: the jobs Marfa runs on its own, such as emptying the bin.
- Exports and restores, each recorded before the export starts, so one that fails partway still has its entry.
It never records a read, so it doesn't say who looked at what. Some writes leave no entry: a write Marfa refused, a dry run, and a connector's routine check-ins.
Two rules make it dependable. A change that succeeded is already in the log, and if Marfa can't write the entry, it undoes the change. No entry holds a secret, such as a key or a password.
Read it
marfa auditid action when actor
01a1f13b-d21f-7229-8845-d8d6c16e5b69 key.revoke 2026-11-19T00:36:31.895Z marfa on your-mac
01a1f13a-805e-7533-93d8-13ec40863738 connector.register 2026-11-19T00:35:05.437Z RSS connector
01a1f139-68c6-719a-882e-0fd85c7dd6e5 folder.revoke 2026-11-19T00:33:53.859Z marfa on your-mac
more: --cursor cLsSIhjS1hvLPAoNsBwIHAQYYMjAyNi0xMS0xOVQwMDozMToxNC4wNjdaCQGh8Tb4lnchgXqvesFMNdsEntries come newest first, 50 at a time. The action column says what happened, such as item.create or key.revoke. When more match, the last line gives the --cursor that reads the next page, and --all reads every page at once.
See who did it
The actor column names who made each change, by the name the sign-in had at the time: renaming or revoking it later doesn't change the entry. It shows Marfa for work Marfa did on its own, such as emptying the bin, and no sign-in for an entry from before anyone signed in, such as a failed sign-in. Add --json to see the actor's kind and ID:
marfa audit --resource-type item --resource-id 01a1f130-ece6-765a-9d0b-113af7fdef49 --json | jq '.data[0].actor'{
"kind": "key",
"id": "01a1f130-37fc-7184-b4a2-3fba803cf8be",
"name": "Reading digest"
}The kind says what acted:
browser,apporkey: one of your sign-ins.local: a command run through the server's private socket, on the machine it runs on.server: Marfa itself.
Filter it
Combine these options to narrow the log:
| Option | Keeps the entries |
|---|---|
--kind | Of one kind: access, data, settings or housekeeping, as What it records groups them. |
--action | With this action, such as item.create. |
--resource-type and --resource-id | About one kind of thing, such as item, or one item, key or setting by its ID. |
--created-after and --created-before | From between two times, such as 2026-11-19T00:30:00Z. |
--query | That hold every word you give, in any order. It searches the action, the kind and ID of what changed, the ID of the key that acted, the address the request came from and the details. |
For example, everything one key did:
marfa audit --query 01a1f130-37fc-7184-b4a2-3fba803cf8beid action when actor
01a1f13b-d21f-7229-8845-d8d6c16e5b69 key.revoke 2026-11-19T00:36:31.895Z marfa on your-mac
01a1f130-ece7-710c-afc6-e9d9b9be1008 item.create 2026-11-19T00:24:37.862Z Reading digest
01a1f130-37fc-7184-b4a2-3fbbafb27732 key.create 2026-11-19T00:23:51.547Z marfa on your-macThe search doesn't read the actor's name, so search by a key's ID, which marfa sign-ins list shows.
How long entries are kept
Your instance keeps entries for 90 days, and a daily housekeeping job deletes older ones. To keep them for a year, or for ever with 0:
marfa config set audit_retention_days 365Reading the log needs the audit.read permission, which the CLI's own sign-in holds. A key you give an agent can hold it too, to read the log and nothing else. The audit log in the contract has every action it records.