CLI reference

Every zanei command, flag, shared convention, and exit code.

All functionality lives in a single binary, zanei: daemon control, permission diagnostics, data retrieval, filter management, agent setup, and the MCP server. The CLI and the MCP server are thin wrappers over the same core and store, and share the conventions on this page.

• Signed, notarized single Rust binary; no external runtime.
• Strictly local: the CLI performs no network egress of any kind.
• Apart from the destructive operation (purge), commands have minimal side effects and are safe for agents to call.

Commands at a glance

Global options

Valid for every subcommand.

Environment

Shared conventions

Time expressions

Values accepted by --since / --until:

--until defaults to now. --since defaults per command: timeline = 1h, query = 15m, export = 24h.

Event types

--types takes a comma-separated list of event types, with trailing wildcards allowed (browser.*).

Output formats

Commands with a --format option support these values:

Diagnostic/state commands use a separate fixed-output convention:

Exit codes

doctor

Diagnoses recorder health and the granted state of required TCC permissions (Accessibility / Input Monitoring / Automation) against the configured sources and content opt-ins.

zanei doctor            # human-readable; shows granting steps and the System Settings pane if anything is missing
zanei doctor --fix      # interactively opens each relevant System Settings pane (granting is still a user action)
zanei doctor --json     # machine-readable, for agents

--fix handles missing permissions one pane at a time. Before opening the next pane, it waits for Return; the final pane does not add another wait. Combining --json --fix does not disable this walkthrough: Zanei prints the JSON report first and then enters the same interactive flow when a required permission is missing. In that combination, stdout is therefore not JSON-only.

• Exits with code 3 if any required permission is missing.
• input_monitoring counts as required when the configuration captures input.* or ui.click; when neither input nor ui is selected, its absence still yields ok.

--json output:

{
  "ok": false,
  "reported_by_recorder": true,
  "capture_sources": ["app", "window", "ui", "input", "browser"],
  "capabilities": {
    "read_accessibility_tree": {
      "state": "available", "required": true,
      "required_for": ["window.focus", "window.title", "ui.focus", "ui.click", "ui.value", "content.snapshot"],
      "detail": { "platform": "macos", "permission": "accessibility", "status": "granted", "settings_url": "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility" }
    },
    "observe_input": {
      "state": "action_required", "required": true,
      "required_for": ["input.key", "input.scroll", "clipboard.copy", "clipboard.paste", "ui.click"],
      "detail": { "platform": "macos", "permission": "input_monitoring", "status": "denied", "settings_url": "x-apple.systempreferences:com.apple.preference.security?Privacy_ListenEvent" }
    },
    "automate_browser": {
      "state": "deferred", "required": true,
      "detail": { "platform": "macos", "permission": "automation", "status": "not_determined", "settings_url": "x-apple.systempreferences:com.apple.preference.security?Privacy_Automation", "target_bundle_id": "com.google.Chrome" }
    },
    "automate_safari": {
      "state": "deferred", "required": true,
      "detail": { "platform": "macos", "permission": "automation", "status": "not_determined", "settings_url": "x-apple.systempreferences:com.apple.preference.security?Privacy_Automation", "target_bundle_id": "com.apple.Safari" }
    }
  },
  "store_key": { "state": "key_store", "detail": "the login Keychain (item \"Zanei store key\")" },
  "health": {
    "state": "degraded",
    "degraded": { "chrome": "state=unavailable phase=query kind=apple_event code=-1712" },
    "collector_failures": { "chrome": 3 }
  }
}

Capability state values are available / action_required / deferred. The nested macOS detail preserves the native permission name and granted / denied / not_determined status, and owns the relevant System Settings URL and optional target bundle ID. reported_by_recorder is true when the result came from a fresh recorder heartbeat. Without one, doctor probes from its own process, sets this field to false, and the human output notes that the recorder must be started to see its own permissions.

store_key reports where the store’s encryption key is. state is key_store (the key was found; detail names the place, either the login Keychain or the ZANEI_STORE_KEY_FILE development override), not_needed (the store is missing, plaintext, or not recognized), missing (the store is encrypted but there is no key), mismatch (the key does not decrypt this store), key_store_locked or key_store_denied (detail carries the platform’s advice, for example that the login Keychain is locked), or unavailable; detail is present only when there is more to report. Human-readable output adds a Store key: ... line after the permission table. doctor does not fail when the store is locked: it reports the key state and probes permissions from its own process instead.

Recorder health

health.state classifies only the evidence available from the store lock and persisted recorder status:

The health object has these fields:

Human-readable output adds the following fixed lines after Store key::

Control characters in human-readable component names, reasons, and status errors are printed as visible escapes. Recorder health does not change doctor’s exit policy: code 3 still means that a required permission is missing. A degraded health state by itself does not make doctor fail.

Human-readable output always ends with the next action. When a required permission is denied, it walks through granting it: run zanei start so the recorder asks macOS for the permission, then follow the dialog and System Settings guidance. Accessibility adds the bundled app as Zanei, but Input Monitoring may omit the row even after the dialog grant takes effect. After restarting, the recorder-reported doctor result, not the list, is authoritative. The manual + walkthrough copies the Zanei.app root when running from a bundle and the executable path when running as a raw binary; use Command-Shift-G (or a single ~) to select that path. A manually added bundle entry persists. See the permissions guide for the complete setup and removal flow. When Chrome Automation is not_determined, no advance action is needed: macOS asks the first time Zanei contacts Chrome. An unsigned or ad-hoc-signed build also produces a warning that rebuilding will reset granted permissions.

start

Registers Zanei with launchd and starts background recording. If an agent is already registered, Zanei waits up to 10 seconds for launchd to finish unregistering it before registering the agent again. For background starts, Zanei first waits up to 10 seconds for the daemon to report that it is alive. After that, the permission check described below may take up to another 20 seconds. At recorder startup, required missing Accessibility and Input Monitoring permissions are requested once. Automation remains deferred until the first real Apple Event to Chrome.

zanei start              # start background recording
zanei start --foreground # run in the foreground instead (dev/debug)

After the recorder reports that it is alive, background start rereads the recorder’s permission snapshot once per second for up to 20 seconds while it remains pending. At the 5-second mark, it prints Waiting for the recorder's permission check... once to stderr unless --quiet is set. If the snapshot becomes available with all required permissions granted, start prints the normal success message and, when eligible, asks the capture.text_content opt-in question. If it reports missing required permissions, start prints the same granting guidance as doctor and exits with code 3. Only when the snapshot is still pending after 20 seconds does start report that the recorder is still waiting for the macOS permission dialogs. It notes that dialogs may take a moment to appear and advises running zanei doctor --fix if none are visible, then exits with code 0 because the recorder is alive. The recorder remains running; after granting permissions, run zanei stop && zanei start and confirm with zanei doctor. --foreground runs the same recorder startup request logic in the foreground process.

When capture.text_content is not explicitly present in config.toml, the first successful interactive background start for which the recorder has reported all required permissions as granted asks:

Record typed text and clipboard contents too? They stay in the local store like everything else (48-hour retention), password fields are always excluded, and Chrome Incognito text is never captured. You can change this anytime: zanei config set capture.text_content <true|false>  [y/N]

Before bootstrapping, start uses the persisted last-known recorder permission report. If that report does not cause the question, start bootstraps the recorder, waits for it to become alive, and checks the current recorder report. The CLI process’s local permission probe is never used for this decision because it reflects the terminal’s TCC identity rather than the recorder’s.

Only y or Y enables capture; Enter, any other answer, EOF, or a read error selects false. Zanei saves the explicit value through the same path as config set, preserves the rest of the file, and prints Text content will be recorded. or Text content stays off.. If the question was asked after bootstrap, a y answer also prints Restarting the recorder to apply text content capture... and restarts through the canonical stop-then-start path. A false answer needs no restart because it preserves the recorder’s default-off behavior. Because either answer writes the key, the question is not repeated.

Immediately after this question is answered, start prints the following separate opt-in guidance exactly. It does not ask a content-snapshot y/N question:

Content snapshots (text shown in apps you choose) are a separate opt-in. Choose the apps first
(zanei filter content-snapshot only-app add <APP>, or exclude-app), then enable it with
zanei config set capture.content_snapshot true.

If capture.text_content was already explicit and the question is not shown, this guidance is not shown either. The permanent entry point is the CONTENT SNAPSHOT status line.

The question is not shown by --foreground, with non-TTY stdin or stderr, with --quiet or --json, while permissions are missing, or when permission state cannot be determined. A skipped start leaves the setting undecided and keeps the existing opt-in guidance. If the key is already explicitly true or false, start does not ask.

On its first start, the recorder generates the store’s encryption key and saves it in your login Keychain as “Zanei store key”. A plaintext store written by 0.2.x or earlier is not rewritten: the recorder renames it to store.sqlite.plaintext-<timestamp>, starts a fresh encrypted store, and reads keep returning the old events alongside the new ones until they age out of retention (see the FAQ). The recorder never shows Keychain dialogs: if the login Keychain is locked, start fails with store is locked: your login Keychain is locked; unlock it (for example by opening Keychain Access) and try again.

Only one recorder can own a store at a time. A second foreground or launchd recorder for the same store exits with code 1 and reports the PID of the current owner.

After a background start succeeds, the confirmation states that Zanei is registered as a launchd background item. A macOS notification or an entry under Login Items & Extensions is expected behavior.

stop

Stops the recorder instance that owns the selected store. A launchd recorder is unregistered; a foreground recorder receives SIGTERM. Not destructive: stored data is kept. Exits with code 4 if there is no recorder to stop.

Stopping uses two bounded stages in order: it waits up to 10 seconds for the selected store owner to disappear, then, for a launchd recorder, up to another 10 seconds for launchd registration to be removed. A timeout in either stage is an error.

zanei stop

pause

Temporarily suspends recording without unregistering the daemon.

zanei pause --for 30m   # auto-resume after 30 minutes
zanei pause             # paused until `resume`

resume

Resumes recording after a pause.

zanei resume

status

Reports daemon state, capture configuration, and store statistics.

zanei status
zanei status --json

Human-readable output shows the current app/site scope next to enabled TEXT CONTENT and CONTENT SNAPSHOT lines. Disabled lines show their explicit activation commands, so both privacy-sensitive opt-ins are visible without requesting JSON. Examples are TEXT CONTENT on (apps: exclude 6, sites: exclude 0) and CONTENT SNAPSHOT off (opt-in: zanei config set capture.content_snapshot true).

{
  "state": "running",
  "running": true,
  "paused": false,
  "since": "2026-08-16T08:00:00.000Z",
  "instance": "4242@2026-08-16T08:00:00.000Z",
  "mode": "launchd",
  "uptime_s": 3600,
  "events_captured": 12345,
  "events_dropped": 2,
  "collector_failures": { "eventtap": 1 },
  "last_event_ts": "2026-08-16T08:59:58.000Z",
  "heartbeat_freshness": "fresh",
  "heartbeat_age_s": 2,
  "last_event_age_s": 4,
  "store_write_state": "healthy",
  "degraded": {},
  "store": { "path": "~/.local/state/zanei/store.sqlite", "size_bytes": 5242880, "retention_hours": 48, "oldest_event_ts": "2026-08-14T09:00:00.000Z", "encryption": "sqlcipher" },
  "capture": { "sources": ["app", "window", "ui", "input", "browser"], "text_content": false, "content_snapshot": false },
  "permissions_ok": true
}

The JSON object always has the following fields. integer values are non-negative.

Human-readable output is a fixed set of lines rather than a table selected with --format:

JSON fields not listed in this human-output table are not printed in human mode.

status exits with code 0 for running, 4 for stopped, and 1 for every store_* state.

For store_corrupt, preserve the damaged file and create a fresh store:

zanei stop
mv ~/.local/state/zanei/store.sqlite ~/.local/state/zanei/store.sqlite.corrupt
zanei start

Use the configured store path instead of the default path when applicable. The moved file remains available for investigation; the new store is empty.

store_locked with a missing or mismatched key is recovered the same way: the new store is created with the existing key, or with a new key if none exists. Losing the key loses at most the retention window (48 hours by default) of data. When degraded.store says the login Keychain is locked, unlock it and retry instead of moving the store. The recorder never shows Keychain dialogs, so zanei start fails while the Keychain is locked; zanei status and zanei query may show the macOS unlock dialog. zanei doctor reports the key state.

record

Foreground capture: streams raw events as NDJSON to stdout (or a file) without daemonizing. Intended for piping and experiments; use start for everyday recording.

zanei record --stream                 # NDJSON to stdout
zanei record --out events.jsonl       # to a file

query

Retrieves raw events matching the given conditions. Machine-readable, structured output.

zanei query --since 15m --types browser.navigate,app.activate
zanei query --since 2h --app Safari --format json --limit 500

These are query-time filters: they narrow reads, not what gets recorded (see filters).

When --types is omitted, content.* is excluded. Request --types content.snapshot or --types content.* explicitly to read snapshot bodies; other families can be listed alongside it. --format json remains an array of event objects. If stored rows use unknown event types, Zanei skips them and warns with the count on stderr; global --quiet suppresses that warning.

timeline

Splits raw events into sessions, deduplicates, coalesces, and serializes an LLM-ready summary within a token budget. This is the command agents call most.

zanei timeline --since 1h --format md --token-budget 4000
zanei timeline --since 30m --format json --granularity fine

Default --format md output (abridged; activity phrases and headings are emitted exactly as shown):

# Zanei timeline

Range: 2026-08-16T08:00:00.000Z — 2026-08-16T09:00:00.000Z
Estimated tokens: 3810
Truncated: no

## 2026-08-16T08:12:00.000Z — 2026-08-16T08:31:00.000Z · Safari

Title: Reviewing PR #42
- Browsed 3 pages on github.com
- Edited text in "Reviewing PR #42"
Content snapshots: 3

With --format json, the same session is represented by range, token_estimate, truncated, skipped_unknown_types, and sessions; session activities use the same fixed phrases. Every JSON session includes content_snapshots, including 0. Markdown prints Content snapshots: N after the activity lines only when the count is nonzero. Snapshot bodies are never inlined. JSON sessions always include event_ids_truncated and include up to 100 event_ids when the token budget permits. event_ids may be omitted before sessions are removed. Ranges that contain only snapshots, including snapshots before the first ordinary event, still emit metadata-backed sessions with empty activity and event lists.

export

Dumps every raw event in range (backup / external processing).

zanei export --since 24h --format jsonl --out dump.jsonl
zanei export --since 24h --format sqlite --out snapshot.sqlite
zanei export --since 24h --types app.*,window.*,ui.*,input.*,browser.*,clipboard.* --format sqlite --out share.sqlite

Export includes every event type by default in all formats, including content.snapshot; unlike query, an omitted --types does not hide content. --format json remains an array of event objects. JSON/JSONL export skips unknown event types and warns with the count on stderr unless --quiet is set.

--format sqlite writes a plaintext SQLite snapshot with the same tables as the live store (events, daemon_state, daemon_capabilities, meta) for the requested range; retention applies like every read. SQLite export copies matching rows without decoding them, so unknown types are copied rather than skipped. --out is required (usage error, code 2, without it). The file is created owner-only (mode 0600) and never overwritten: an existing path fails with code 1 and snapshot file already exists at PATH; choose another --out path. On success it prints Wrote a plaintext SQLite snapshot with N events to PATH (suppressed by --quiet). The snapshot is not encrypted and contains snapshot bodies in plaintext when content.* is selected. Treat it like a sensitive JSONL export; use --types to select only the families intended for sharing or external processing. It opens in sqlite3, DB Browser for SQLite, any language’s SQLite bindings, and zanei query --store snapshot.sqlite.

purge

Deletes stored events manually, independent of retention-based auto-purge. Destructive.

zanei purge --before 24h   # delete events older than 24 hours
zanei purge --all          # delete everything (confirmation prompt; suppress with --quiet)
zanei purge --types '*'    # also delete everything (same confirmation as --all)
zanei purge --types content.* --before 24h
zanei purge --types content.* --app Slack
zanei purge --types content.* --bundle-id com.tinyspeck.slackmacgap

--types can be combined with --before and one app selector, for example to remove snapshots from an app after excluding it. An unscoped --types '*' is a universal selection and requires the same confirmation as --all unless --quiet is set; narrower type patterns such as content.* do not prompt. This deletion is irreversible and has no dry-run mode; the command reports the applied scope and deleted count. When the store does not exist, purge prints Purged 0 events and does not create one. Set-aside plaintext stores from the encryption upgrade are purged too: scoped options delete matching rows, while --all deletes the files.

apps

Lists apps available for filter selection from installed apps, running apps, and app.activate events still in the store.

zanei apps
zanei apps slack
zanei apps slack --json

The optional QUERY is a case-insensitive substring match on name or bundle ID. The table contains NAME, BUNDLE ID, SOURCES (installed, running, recent), and LAST USED. Recently used apps come first, then other running apps, then installed apps. No result is success (code 0) with No apps match "QUERY". on stderr. No TCC permission is needed, and the command works while the daemon is stopped.

--json returns { "apps": [{ "name", "bundle_id", "path", "installed", "running", "last_used" }], "recent_unavailable": null, "installed_unreadable": 0 } in the same order. If the store is absent or cannot be opened, installed and running apps remain available and recent_unavailable contains the reason. App bundles with missing, unreadable, or malformed Info.plist files are skipped; installed_unreadable reports their count, and a nonzero count also prints warning: N app bundles could not be read to stderr.

filter

Manages three capture-time scopes: [filter] for all events, [filter.text_content] for typed/copied bodies, and [filter.content_snapshot] for snapshot events. The command shape is zanei filter [<scope>] <list> add|remove [VALUE]; <scope> is omitted, text-content, or content-snapshot.

zanei filter show
zanei filter exclude-app add 1Password
zanei filter text-content exclude-app add Slack
zanei filter content-snapshot only-app add Terminal
zanei filter content-snapshot exclude-site add mail.google.com
zanei filter content-snapshot exclude-app add FutureApp --unverified

• Every app-list add accepts a display name or bundle ID, resolves it against zanei apps, and saves the bundle ID when available. An unresolved value is not saved and exits with code 2, with a close candidate when available. --unverified explicitly saves an unresolved value with a warning.
• add with no value opens a numbered, recently-used-first selector. Non-TTY use and --quiet require a value; omission exits with code 2. remove resolves against the current list, including entries for apps no longer installed.
• filter show displays all three scopes, each apps/sites mode and count, resolved names, and (not installed) for unresolved entries. It also lists hard-coded built-in exclusions separately.
• Both content scopes default to excluding Safari, Firefox, Brave, Edge, Vivaldi, and Arc. Adding one with only-app or removing it from exclude-app warns unless --quiet is set, because private-window detection is unavailable. The defaults are editable.
• Site rules apply to Chrome and Safari. Changes apply on the next configuration-watch cycle, normally within 2 seconds; no restart is required.

The exact evaluation order and the fields removed by each scope are in the filters guide.

config

zanei config init   # create a fully commented configuration template
zanei config path   # print the config file path
zanei config show   # print the effective configuration (defaults merged)
zanei config edit   # open the config in $EDITOR
zanei config set capture.text_content true
zanei config set capture.content_snapshot true

config init writes a complete, commented template containing every supported option and its current default. By default it creates ~/.config/zanei/config.toml; the global --config <path> flag selects a different destination. Missing parent directories are created. On success, the command prints the created path and exits with code 0. If the destination already exists, it leaves the file unchanged, reports the existing path, and exits with code 1.

config set <DOTTED_KEY> <VALUE> validates and saves one scalar setting. Supported keys and values:

Array settings are not accepted: use zanei filter for filter lists, or zanei config edit for other arrays. Unknown keys, array keys, and invalid values exit with code 2 without saving. output.retention_hours is reloaded by a running daemon and immediately applied to retention purging. If the daemon is running, a successful capture.text_content, capture.content_snapshot, or output.batch_interval_s change prints:

Restart recording with `zanei stop && zanei start` for this to take effect.

config set capture.content_snapshot true first prints the current app/site scope and waits for [y/N], with N as the default. The scope summary reflects the effective lists, and the deletion interval comes from the loaded output.retention_hours; with its default value, the prompt is:

Content snapshots record the text shown in the frontmost window, including messages and
documents written by other people and text you typed that is on screen. Password fields and
Chrome Incognito windows are never captured; stored text is redacted and deleted after 48 hours.

Current scope (change it first if this is not what you want):
  Apps:  every app except 6 excluded (Safari, Firefox, Brave, Edge, Vivaldi, Arc)
  Sites: every site
  zanei filter content-snapshot only-app add <APP>      record only these apps
  zanei filter content-snapshot exclude-app add <APP>   everything except these
  zanei apps                                            list apps to choose from

Enable content snapshots with this scope? [y/N]

N, Enter, or EOF leaves the file unchanged. With non-TTY input, --quiet is required to write; without it Zanei prints the scope summary to stderr, exits with code 2, and does not save. After choosing the scope with filter content-snapshot, an agent can use zanei config set capture.content_snapshot true --quiet, must state what will be recorded, and then restart. Setting the value to false does not ask for confirmation.

Schema: see the configuration reference.

mcp

Runs the stdio MCP server: JSON-RPC on stdin/stdout, with no network access. Started by MCP clients (Claude Code, Codex, opencode, Claude Desktop, …), not usually by hand.

zanei mcp [--store <PATH>]

• Read-only view over the store; independent from the recording daemon.
• Exposed tools: get_timeline / query_events / get_status — see the MCP reference.

setup

Configures Zanei instructions and MCP integration for the target agent. Every agent that runs the CLI gets the skill file; Claude Desktop’s chat gets only its MCP registration, and opencode’s MCP JSON is printed for you to place.

zanei setup --agent claude            # SKILL.md into Claude Code's skill location + MCP registration
zanei setup --agent codex --scope user
zanei setup --agent hermes            # skill into ~/.hermes/skills/ + MCP in ~/.hermes/config.yaml
zanei setup --agent pi                # skill into ~/.pi/agent/skills/ or .pi/skills/; no MCP
zanei setup --agent claude-desktop    # MCP registration in claude_desktop_config.json
zanei setup --agent opencode          # skill into opencode's skill location + MCP JSON printed

Per-agent behavior and setup output: see agent setup.