CLI リファレンス

zanei の全コマンド・フラグ・共通規約・終了コード。

すべての機能は単一バイナリ zanei に入っています — デーモン管理、権限診断、データ取得、フィルタ管理、agent セットアップ、MCP サーバまで。CLI と MCP サーバは同一コア・同一ストアの薄いラッパーであり、このページの規約を共有します。

• 署名・notarize 済みの単一 Rust バイナリ。外部ランタイム依存なし。
• 完全ローカル：CLI はいかなる外部送信も行いません。
• 破壊的操作（stop・purge）以外は副作用が小さく、agent から安全に呼べます。

コマンド一覧

グローバルオプション

すべてのサブコマンドで有効です。

共通規約

時間表現

--since / --until が受け取る値：

--until の既定は now。--since の既定はコマンドごとに timeline = 1h、query = 15m、export = 24h。

イベント型

--types はイベント型のカンマ区切りリストを受け取ります。末尾ワイルドカード（browser.*）が使えます。

出力形式

終了コード

doctor

設定中の capture.sources に照らして、必要な TCC 権限（アクセシビリティ / 入力監視 / オートメーション）の付与状況を診断します。

zanei doctor            # 人間可読。不足があれば付与手順と System Settings ペインを案内
zanei doctor --fix      # 不足権限の設定ペインを開く（付与自体はユーザー操作）
zanei doctor --json     # agent 向け機械可読

• 必要権限がひとつでも欠けていれば終了コード 3。
• input_monitoring が「必須」になるのは input.* を捕捉する設定のときだけ。不要な構成では欠けていても ok です。

--json の出力：

{
  "ok": false,
  "capture_sources": ["app", "window", "ui", "input", "browser"],
  "permissions": {
    "accessibility":     { "status": "granted" },
    "input_monitoring":  { "status": "denied", "required_for": ["input.key", "input.scroll", "ui.click"] },
    "automation":        { "per_app": { "com.google.Chrome": "not_determined" } }
  },
  "missing_required": ["input_monitoring"],
  "settings_pane": "x-apple.systempreferences:com.apple.preference.security?Privacy_ListenEvent"
}

status の値：granted / denied / not_determined。

人間向け出力の最終行には、必ず次の操作が表示されます。必要な権限が denied の場合は、 付与手順を順に案内します：zanei start で recorder に権限を要求させ、ペインに zanei の行が 出ていればトグルを ON にし、出ない場合のみ zanei doctor --fix、+ ボタン、 Command-Shift-G（または ~ 1 文字）で実行中バイナリの実パスを追加します。 launchd 起動のコマンドラインツールはこれらのペインの一覧に表示されないことがあるため、 一覧ではなく doctor の報告が正である旨も併記されます。Chrome Automation が not_determined の 場合は事前操作不要で、Zanei が初めて Chrome に問い合わせる際に macOS が確認します。 未署名または ad-hoc 署名のビルドでは、再ビルド時に付与済み権限がリセットされる旨も警告します。

start

launchd に登録し、バックグラウンド記録を開始します。

zanei start              # バックグラウンド記録を開始
zanei start --foreground # デーモン化せず前面で実行（開発・デバッグ用）

権限不足を検出した場合、記録は開始されず終了コード 3 で不足内容を案内します。

バックグラウンド起動に成功すると、Zanei が launchd のバックグラウンド項目として 登録されたことを表示します。macOS の通知や Login Items & Extensions への表示は正常な挙動です。

stop

記録を停止し、launchd から登録解除します。破壊的操作ではありません — データは保持されます。対象デーモンがなければ終了コード 4。

zanei stop

pause

デーモンを解除せず、記録だけを一時停止します。

zanei pause --for 30m   # 30 分後に自動再開
zanei pause             # resume まで無期限

resume

一時停止から再開します。

zanei resume

status

デーモンの状態・捕捉設定・ストア統計を表示します。

zanei status
zanei status --json

人間向け出力は、有効時に TEXT CONTENT on (opt-in)、無効時に TEXT CONTENT off (opt-in: zanei config set capture.text_content true) を表示します。 プライバシーに関わる opt-in 状態と明示的な有効化コマンドを JSON なしで確認できます。

{
  "running": true,
  "paused": false,
  "since": "2026-08-16T08:00:00Z",
  "uptime_s": 3600,
  "events_captured": 12345,
  "events_dropped": 2,
  "last_event_ts": "2026-08-16T08:59:58Z",
  "degraded": { "eventtap": "1 degraded collector operation observed" },
  "store": { "path": "~/.local/state/zanei/store.sqlite", "size_bytes": 5242880, "retention_hours": 48, "oldest_event_ts": "2026-08-14T09:00:00Z" },
  "capture": { "sources": ["app", "window", "ui", "input", "browser"], "text_content": false },
  "permissions_ok": true
}

record

前面での捕捉：デーモン化せず、生イベントを NDJSON で stdout（またはファイル）へストリームします。パイプ実験・検証用 — 常用の記録は start を使ってください。

zanei record --stream                 # NDJSON を stdout へ
zanei record --out events.jsonl       # ファイルへ

query

条件に合う生イベントを取り出します。構造化された機械可読出力。

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

これらは query-time フィルタです — 読み出しを絞るだけで、記録対象には影響しません（フィルタ参照）。

timeline

生イベントをセッション分割・重複除去・coalesce し、token budget 内に収めた LLM 向け要約を返します。agent が最もよく叩くコマンドです。

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

--format json の構造（要約）：

{
  "range": { "since": "2026-08-16T08:00:00Z", "until": "2026-08-16T09:00:00Z" },
  "token_estimate": 3810,
  "truncated": false,
  "sessions": [
    {
      "start": "2026-08-16T08:12:00Z", "end": "2026-08-16T08:31:00Z",
      "app": "Safari", "title_summary": "PR #42 のレビュー",
      "activities": ["GitHub で 3 ファイルを閲覧", "コメントを 2 件記入"],
      "event_ids": ["evt_01J...", "evt_01J..."]
    }
  ]
}

export

範囲内の全生イベントをダンプします（バックアップ / 外部処理用）。

zanei export --since 24h --format jsonl --out dump.jsonl

purge

保持期間による自動 purge とは別に、手動で削除します。破壊的操作です。

zanei purge --before 24h   # 24 時間より古いイベントを削除
zanei purge --all          # 全削除（確認プロンプトあり。--quiet で抑制）

filter

capture-time の許可/不許可リスト — ストアに書き込まれる前に破棄するアプリ・サイト — を管理します。セマンティクスとマッチングルールはフィルタガイドを参照。config.toml の [filter] 編集と等価ですが、キー検証と重複排除を行うぶん安全です。

zanei filter show                                      # 全リストと有効モード
zanei filter exclude-app add com.1password.1password
zanei filter exclude-app remove com.1password.1password
zanei filter only-app add com.apple.Safari
zanei filter exclude-site add example.com
zanei filter only-site add github.com

• アプリは BUNDLE_ID（推奨）または表示名で指定。filter show は既定の除外リスト（1Password・Keychain Access 等）も併せて表示します。
• 変更は次のイベントから反映 — デーモン再起動不要。
• only-app をひとつでも追加すると許可リストモードに切り替わります。filter show が現在のモードを明示します。

config

zanei config init   # 全設定項目にコメントを付けたテンプレートを生成
zanei config path   # 設定ファイルのパスを表示
zanei config show   # 有効設定（既定値マージ後）を表示
zanei config edit   # $EDITOR で設定を開く
zanei config set capture.text_content true

config init は、対応する全設定項目と現在の既定値を含むコメント付きテンプレートを 生成します。既定の生成先は ~/.config/zanei/config.toml で、グローバル --config <path> で別の生成先を指定できます。親ディレクトリがなければ作成します。 成功時は生成したパスを表示して終了コード 0 で終了します。生成先にファイルが存在する 場合は変更せず、既存ファイルのパスを表示して終了コード 1 で終了します。

config set <DOTTED_KEY> <VALUE> は、スカラー設定を 1 項目検証して保存します。対応するキーと値は次のとおりです。

配列設定には対応しません。filter リストには zanei filter、その他の配列には zanei config edit を使います。不明なキー、配列キー、不正な値は保存せず終了コード 2 で 終了します。記録デーモンの稼働中に capture.* または output.* の変更に成功すると、次の メッセージを表示します。

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

スキーマは設定リファレンスを参照。

mcp

stdio MCP サーバを起動します — stdin/stdout 上の JSON-RPC で、ネットワーク面ゼロ。通常は MCP クライアント（Claude Code・Codex・opencode・Claude Desktop 等）から起動され、手で叩くものではありません。

zanei mcp [--store <PATH>]

• ストアへのread-only ビュー。記録デーモンとは独立プロセス。
• 公開ツール：get_timeline / query_events / get_status — MCP リファレンス参照。

setup

対象 agent 向けの Zanei 指示と MCP 連携を設定します。native skill 対応 agent と Claude Desktop は従来どおりファイルへ設定し、opencode と pi は手動設定用の指示を表示するだけで、ファイルは変更しません。

zanei setup --agent claude            # SKILL.md を Claude Code の skill 位置へ + MCP 登録
zanei setup --agent codex --scope user
zanei setup --agent hermes            # skill を ~/.hermes/skills/ へ + ~/.hermes/config.yaml に MCP 登録
zanei setup --agent pi                # 導出した README 向け指示を表示。MCP・ファイル書き込みなし
zanei setup --agent claude-desktop    # claude_desktop_config.json へ MCP 登録
zanei setup --agent opencode          # AGENTS.md スニペット + MCP JSON を表示。ファイル書き込みなし

agent 別の挙動とセットアップ出力は agent セットアップを参照。