cull

Cull

Cull はローカルで動作する AI アート画像ライブラリアプリです。フォルダーをインポートし、閲覧、評価・選別、コレクションの作成、ビジョン分析・品質分析、埋め込みによる類似画像の検索、エクスポート・公開を行えます。

Cull は同じ操作を 4 つの方法で提供します。cull CLI、cull:// URL スキーム、GUI、MCP サーバーです。いずれも単一の Rust コアを薄くラップしています。基本的には CLI と URL スキームを使用してください。 MCP 接続が不要で、アプリを再起動しても利用できます。ヘッドレスで操作できない機能に対話的な制御が必要な場合にのみ、MCP を使用してください（「MCP が必要な場合」を参照）。

コアとなるルール（必ず守ってください）

画像を表示または確認するときは、必ず Cull を使用してください。open <image> や Preview は使わないでください。 ユーザーは Preview のウィンドウを望んでいません。画像を Cull のライブラリにインポートし、（以下の手順で）フォルダーを開いてアプリを前面に表示してください。アプリを前面に表示するのは問題ありませんが、画像ファイルを open で開いてはいけません。

ヘッドレスで Cull を操作する（デフォルトの方法）

バイナリは /Applications/Cull.app/Contents/MacOS/cull にあります。一度設定してください。

CULL="/Applications/Cull.app/Contents/MacOS/cull"

サブコマンドを指定しない場合は GUI が起動します。サブコマンドを指定すると、ヘッドレスで実行され、終了します。実行結果は、起動中のアプリが読み取るものと同じライブラリ DB に書き込まれます。機械可読な出力を得るには --json を追加してください。

複数の画像を表示・確認する — 最もよくあるタスクです。まずヘッドレスでインポートし、次に URL スキームでフォルダーを開いてアプリを前面に表示します。

$CULL --json import_folder --folder_path "/abs/path/to/batch"
open -a /Applications/Cull.app "cull://open?path=/abs/path/to/batch&view=grid"   # &view=loupe for single-image detail
open -a Cull                                            # ensure the window is frontmost

import_folder は安全に再実行できます。インポート済みのファイルはスキップされます。

実装済み CLI サブコマンド

これらはリリース済みバイナリで利用できます（cull --help で確認してください）。フィールド名は MCP ツールのパラメーターと一致しています。

コマンド	用途
import_folder --folder_path P / import_files --file_paths a,b	フォルダーまたは指定したファイルをライブラリに追加します
list_folders / list_images [--limit N --offset N] / list_collections	フォルダー、画像、コレクションの一覧を取得します
get_library_stats	ライブラリ全体の件数を取得します
list_export_presets / export_images --image_ids … --output_dir … --format …	プリセットの一覧取得、またはディスクへのエクスポート（--collection_id または --folder_path も指定できます）
get_embedding_model_download_info / download_embedding_model / generate_embeddings	埋め込みモデルの前提条件の確認と生成（非同期）
analyze_image_quality / get_image_quality / get_quality_count	品質分析の実行、スコアの取得、評価区分ごとの件数の取得
call_tool <tool> --params_json '{…}'	汎用の代替手段 — 任意の MCP 名のツールを JSON オブジェクトで呼び出します

call_tool は MCP 形式のパラメーターを受け付けるため、任意の MCP 操作をヘッドレスで試せます。

$CULL --json call_tool import_folder --params_json '{"folder_path":"/abs/path"}'
$CULL --json call_tool export_images --params_json '{"collection_id":"<id>","output_dir":"/tmp/out","format":"original"}'

URL スキーム（GUI 操作）

open -a /Applications/Cull.app "cull://<action>?<params>" — パスは URL エンコードし、複数のパスはカンマで区切ります。必ず -a /Applications/Cull.app を指定してください。 Cull の開発ビルドも cull:// スキームを登録するため、open "cull://…" のみを実行すると、古いコピーが開かれることがあります（URL を開こうとしても、何も起きないままになる場合があります）。GUI 操作はウィンドウを前面に表示します。アプリが起動していない場合は、macOS が起動します。

アクション	例
開く／移動	cull://open?path=/abs/folder&view=grid（view=loupe、&focus=N、&fullscreen=true）
検索	cull://search?q=sunset
類似画像	cull://similar?path=/abs/ref.jpg&top=5
評価／採用	cull://rate?path=/abs/img.jpg&stars=4 · cull://accept?path=/abs/img.jpg
コレクション	cull://collection/add?name=picks&paths=/abs/a.jpg,/abs/b.jpg

URL スキームの呼び出しは結果を待たずに実行されます（戻り値はありません）。結果が必要な場合は CLI（--json）または MCP を使用してください。

レシピ（CLI 優先）

画像を1枚ルーペ表示します。 open -a /Applications/Cull.app "cull://open?path=/abs/img.png&view=loupe"。

採用した画像をエクスポートします。 list_export_presets → export_images を、--collection_id / --folder_path / --image_ids、--output_dir、--format とともに実行します。

品質チェックを行います。 analyze_image_quality（非同期でジョブが返されます。CLI では再読み込みしてポーリングします）→ 分布を確認する get_quality_count → 画像ごとの get_image_quality。

埋め込みの前提条件です。 download_embedding_model（一度だけ）→ generate_embeddings（非同期）。この後に初めて、類似度検索（cull://similar?…、または MCP 経由の find_similar）が使えるようになります。

MCP が必要な場合（任意）

ヘッドレス CLI では、インタラクティブな選別やライブナビゲーションはまだ実装されていません。これらは mcp__cull__* ツール（または手動の GUI）でのみ利用できます。次の場合は MCP を使用してください。

• エージェントから正確に移動／表示する場合：navigate_to_folder、show_image、show_collection（URL スキームで一般的なケースに対応できますが、これらを使うとプログラムから操作して確認できます）。
• 往復操作を伴う選別を行う場合：set_rating、set_decision、create_collection、add_to_collection、create_smart_collection。
• 結果を伴う検索とビジョン処理を行う場合：find_similar、search_by_object、detect_objects / get_detections、analyze_images、get_vision_metadata。
• 非同期ジョブを追跡する場合：list_jobs / get_job / cancel_job。
• 公開する場合：export_static_publish_package / serve_static_publish_package、クリップボードコレクション用ツール。

MCP の仕組み。 これらのツール名は mcp__cull__<tool> です。Claude Code では遅延読み込みされるため、スキーマが読み込まれておらず、直接呼び出すと失敗します。呼び出す前に、レシピで必要なツールだけを読み込んでください。

ToolSearch "select:mcp__cull__navigate_to_folder,mcp__cull__set_rating"

Cull を再起動すると MCP は切断されます。 アプリを終了／再起動すると MCP サーバーが停止します。以降 mcp__cull__* の呼び出しを再び使うには、ユーザーが /mcp で再接続する必要があります。CLI と URL スキームにはこの依存関係がありません。そちらを優先し、上記のインタラクティブな操作に限って MCP を使用してください。

よくある間違い

• Cull ではなく open / Preview を使う。 これは最大の誤りです。レビューは必ず Cull で行ってください（import_folder + cull://open、または MCP の表示／ナビゲーション用ツール）。
• 最初に MCP を使おうとする。 まず CLI + URL スキームを使ってください。これらは接続不要で、再起動の影響も受けません。MCP はインタラクティブな選別を行う場合の代替手段です。
• Cull の再起動後も MCP が使えると思い込む。 使えません。ユーザーが /mcp で再接続する必要があります。MCP に依存している作業の途中で Cull を再起動しないでください。
• 読み込む前に遅延読み込みの MCP ツールを呼び出す。 先に ToolSearch "select:mcp__cull__…" を実行してください。
• 非同期操作を同期操作として扱う。 埋め込み、分析、大規模なエクスポートはジョブです。完了を決めつけず、ポーリングしてください。
• パラメーターを推測する。 cull <command> --help を確認するか、MCP ツールを読み込んでスキーマを確認してください。

安全性と制限

• 破壊的な操作には明示的な意図が必要です。 delete_collection と prune_audit_log はデータを削除します。実行前に確認してください。
• トークンは管理者権限です。 create_token / rotate_token / revoke_token はアクセス認証情報を変更します。ユーザーから明示的に依頼された場合を除き、操作しないでください。