---
title: CLI リファレンス
description: zanei の全コマンド・フラグ・共通規約・終了コード。
---

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

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

## コマンド一覧

| コマンド | 概要 |
| --- | --- |
| [`doctor`](#doctor) | 必要な macOS 権限の診断と付与誘導 |
| [`start`](#start) | バックグラウンド記録の開始（launchd） |
| [`stop`](#stop) | 記録停止と登録解除（データは保持） |
| [`pause`](#pause) / [`resume`](#resume) | 記録の一時停止 / 再開 |
| [`status`](#status) | 稼働状態・イベント件数・ストア情報 |
| [`record`](#record) | 前面での捕捉を stdout/ファイルへ（デバッグ・パイプ用） |
| [`query`](#query) | 条件付きで生イベントを取得 |
| [`timeline`](#timeline) | LLM-ready・token budget 付きタイムライン |
| [`export`](#export) | 生イベントの一括ダンプ |
| [`purge`](#purge) | 保存イベントの手動削除（破壊的） |
| [`filter`](#filter) | capture-time 許可/不許可リストの管理 |
| [`config`](#config) | 設定の初期化・表示・パス・編集 |
| [`mcp`](#mcp) | stdio MCP サーバの起動 |
| [`setup`](#setup) | agent 向け指示と MCP 連携の設定 |

## グローバルオプション

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

| フラグ | 説明 |
| --- | --- |
| `--config <path>` | 設定ファイルパスの上書き（既定 `~/.config/zanei/config.toml`） |
| `--store <path>` | ストアパスの上書き（既定 `~/.local/state/zanei/store.sqlite`） |
| `--json` | 診断・状態系コマンドを機械可読 JSON で出力（`--format json` のショートカット） |
| `-q, --quiet` | 進捗・注意書きを抑制 |
| `-v, --verbose` | 詳細ログを stderr へ |
| `--version` / `--help` | バージョン / ヘルプ |

## 共通規約

### 時間表現

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

| 形式 | 例 | 意味 |
| --- | --- | --- |
| 相対 | `15m` `2h` `1d` `1w` | 現在からの遡り。単位は `s` `m` `h` `d` `w` |
| 絶対 | `2026-08-16T09:00:00Z` | RFC3339 タイムスタンプ |
| キーワード | `now` | 現在時刻（主に `--until` 用） |

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

### イベント型

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

### 出力形式

| 値 | 対象コマンド | 説明 |
| --- | --- | --- |
| `jsonl` | `query`・`export`・`record` | 1 行 1 イベントの生イベント（機械可読） |
| `json` | `query`・`export`・`timeline` | 単一 JSON。`timeline` では構造化タイムライン |
| `md` | `timeline` | LLM-ready Markdown（既定） |
| `table` | `query`・`status`・`doctor` | 人間可読の整形テーブル |

### 終了コード

| コード | 意味 |
| --- | --- |
| `0` | 正常 |
| `1` | 一般エラー |
| `2` | 使用法エラー（引数不正） |
| `3` | **権限不足**（必要な TCC 権限が未付与）— agent・スクリプトが検出しやすい専用コード |
| `4` | デーモン未起動（`status`・`stop` 等で対象がない） |

---

## `doctor`

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

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

| フラグ | 説明 |
| --- | --- |
| `--fix` | 不足している権限の System Settings ペインを開く |
| `--json` | 機械可読出力 |

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

`--json` の出力：

```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 に登録し、バックグラウンド記録を開始します。

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

| フラグ | 説明 |
| --- | --- |
| `--foreground` | デーモン化せず前面で実行 |

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

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

## `stop`

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

```bash
zanei stop
```

## `pause`

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

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

| フラグ | 説明 |
| --- | --- |
| `--for <TIME>` | 停止期間。省略時は `resume` まで無期限 |

## `resume`

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

```bash
zanei resume
```

## `status`

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

```bash
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 なしで確認できます。

```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
}
```

| フィールド | 意味 |
| --- | --- |
| `events_dropped` | collector または記録 pipeline が破棄したイベントの累計 |
| `degraded` | component ごとの collector / runtime 劣化状態。既知の劣化がなければ空 |
| `permissions_ok` | heartbeat が新鮮な間は実行中 recorder 自身の権限判定。recorder 不在時はローカル probe の結果 |

## `record`

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

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

| フラグ | 説明 |
| --- | --- |
| `--stream` | 発生順に stdout へストリーム |
| `--out <FILE>` | ファイルへ書き出し |
| `--format jsonl` | 出力形式（NDJSON） |

## `query`

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

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

| フラグ | 説明 |
| --- | --- |
| `--since` / `--until` | 対象範囲（既定 `--since 15m`） |
| `--types <TYPE,...>` | イベント型フィルタ（カンマ区切り。`browser.*` 可） |
| `--app <NAME>` / `--bundle-id <ID>` | アプリ名 / バンドル ID で絞り込み |
| `--limit <N>` | 最大件数（既定 500） |
| `--format` | `jsonl`（既定）/ `json` / `table` |

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

## `timeline`

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

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

| フラグ | 説明 |
| --- | --- |
| `--since` / `--until` | 対象範囲（既定 `--since 1h`） |
| `--format` | `md`（既定、LLM-ready Markdown）/ `json`（構造化） |
| `--token-budget <N>` | 概算トークン上限（既定 4000）。超過分は粒度を粗くして収める |
| `--granularity` | `coarse`（既定、セッション単位）/ `fine`（操作単位まで） |

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

```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`

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

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

| フラグ | 説明 |
| --- | --- |
| `--since` / `--until` | 対象範囲（既定 `--since 24h`） |
| `--format` | `jsonl` / `json` |
| `--out <FILE>` | 出力ファイル |

## `purge`

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

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

| フラグ | 説明 |
| --- | --- |
| `--before <TIME>` | これより古いイベントを削除 |
| `--all` | 全削除（確認プロンプトあり） |

## `filter`

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

```bash
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
```

| サブコマンド | `[filter]` キー | 意味 |
| --- | --- | --- |
| `exclude-app (add\|remove) <BUNDLE_ID か NAME>` | `exclude_apps` | 不許可リスト（その他は捕捉） |
| `only-app (add\|remove) <BUNDLE_ID か NAME>` | `include_only_apps` | 許可リスト（設定時は列挙分のみ捕捉） |
| `exclude-site (add\|remove) <DOMAIN>` | `exclude_websites` | `browser.*` の URL host の不許可リスト |
| `only-site (add\|remove) <DOMAIN>` | `include_only_websites` | `browser.*` の URL host の許可リスト |

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

## `config`

```bash
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 項目検証して保存します。対応するキーと値は次のとおりです。

| キー | 設定できる値 |
| --- | --- |
| `capture.text_content` | `true`、`false` |
| `output.mode` | `stream`、`batch`、`both` |
| `output.batch_interval_s` | 0 より大きい符号なし整数 |
| `output.store` | `sqlite`、`jsonl` |
| `output.retention_hours` | 0 より大きい符号なし整数 |

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

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

スキーマは[設定リファレンス](/ja/reference/config)を参照。

## `mcp`

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

```bash
zanei mcp [--store <PATH>]
```

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

## `setup`

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

```bash
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` | `claude` / `codex` / `opencode` / `hermes` / `pi` / `claude-desktop` |
| `--scope` | `project`（既定。カレントリポジトリ）/ `user`（ユーザー全体）。opencode/pi の手動設定出力には影響しない |
| `--print` | 書き込み予定のファイル変更を、実際には書き込まず表示する。opencode と pi は、このフラグの有無にかかわらずファイルを書き込まない |

agent 別の挙動とセットアップ出力は [agent セットアップ](/ja/agents/setup)を参照。