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

Terminal
marfa audit
id                                    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 cLsSIhjS1hvLPAoNsBwIHAQYYMjAyNi0xMS0xOVQwMDozMToxNC4wNjdaCQGh8Tb4lnchgXqvesFMNds

Entries 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:

Terminal
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, app or key: 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:

OptionKeeps the entries
--kindOf one kind: access, data, settings or housekeeping, as What it records groups them.
--actionWith this action, such as item.create.
--resource-type and --resource-idAbout one kind of thing, such as item, or one item, key or setting by its ID.
--created-after and --created-beforeFrom between two times, such as 2026-11-19T00:30:00Z.
--queryThat 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:

Terminal
marfa audit --query 01a1f130-37fc-7184-b4a2-3fba803cf8be
id                                    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-mac

The 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 365

Reading 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.

On this page