# Read the audit log (/use/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 [#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 [#read-it]

```bash
marfa audit
```

Output:

```text
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 [#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:**

```bash
marfa audit --resource-type item --resource-id 01a1f130-ece6-765a-9d0b-113af7fdef49 --json | jq '.data[0].actor'
```

Output:

```json
{
  "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](/use/see-and-cut-access).
* **`local`:** a command run through the server's private socket, on the machine it runs on.
* **`server`:** Marfa itself.

## Filter it [#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](#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:

```bash
marfa audit --query 01a1f130-37fc-7184-b4a2-3fba803cf8be
```

Output:

```text
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`](/use/see-and-cut-access#see-what-can-reach-your-data) shows.

## How long entries are kept [#how-long-entries-are-kept]

Your instance keeps entries for **90 days**, and a daily [housekeeping job](/run/housekeeping) deletes older ones. To keep them for a year, or for ever with `0`:

```bash
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](https://github.com/withmarfa/marfa/blob/main/conformance/spec/events.md#the-audit-log) in the contract has every action it records.
