glebis/cull

Cull

Cull is a local AI-art image-library app: import folders, browse, rate/decide, build collections, run vision/quality analysis, find similar via embeddings, and export/publish.

Cull exposes the same operations four ways: the cull CLI, the cull:// URL scheme, the GUI, and an MCP server — all thin wrappers over one Rust core. Default to the CLI + URL scheme. They need no MCP connection and survive app restarts. Reach for the MCP only when interactive control is needed that the headless surface doesn't implement yet (see "When the MCP is needed").

The one core rule (do not skip)

To show or review images, use Cull — never open <image> or Preview. The user does not want Preview windows. Display by importing into Cull's library and fronting the app on the folder (below). Fronting the app is fine; opening image files with open is not.

Driving Cull headless (the default path)

The binary lives at /Applications/Cull.app/Contents/MacOS/cull. Set it once:

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

With no subcommand it launches the GUI; with a subcommand it runs headless and exits, writing to the same library DB the running app reads. Add --json for machine-readable output.

Show / review a batch — the most common task. Import (headless), then front the app on the folder via the URL scheme:

$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

Re-running import_folder is safe — already-imported files are skipped.

Implemented CLI subcommands

These are live in the shipped binary (cull --help to confirm). Field names match the MCP tool params.

| Command | Purpose | |---|---| | import_folder --folder_path P / import_files --file_paths a,b | Bring a folder / specific files into the library | | list_folders / list_images [--limit N --offset N] / list_collections | Enumerate folders / images / collections | | get_library_stats | Library-wide counts | | list_export_presets / export_images --image_ids … --output_dir … --format … | List presets / export to disk (also --collection_id or --folder_path) | | get_embedding_model_download_info / download_embedding_model / generate_embeddings | Embedding model prereq + build (async) | | analyze_image_quality / get_image_quality / get_quality_count | Run quality analysis / read scores / count by bucket | | call_tool <tool> --params_json '{…}' | Generic escape hatch — call any MCP-named tool with a JSON object |

call_tool accepts MCP-shaped params, so any MCP operation can be tried headless:

$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 scheme (GUI actions)

open -a /Applications/Cull.app "cull://<action>?<params>" — paths URL-encoded, multiple paths comma-separated. Always pass -a /Applications/Cull.app: dev builds of Cull also register the cull:// scheme, and a bare open "cull://…" may route to a stale copy (URL silently goes nowhere). GUI actions front the window; if the app isn't running, macOS launches it.

| Action | Example | |---|---| | open / navigate | cull://open?path=/abs/folder&view=grid (view=loupe, &focus=N, &fullscreen=true) | | search | cull://search?q=sunset | | similar | cull://similar?path=/abs/ref.jpg&top=5 | | rate / accept | cull://rate?path=/abs/img.jpg&stars=4 · cull://accept?path=/abs/img.jpg | | collection | cull://collection/add?name=picks&paths=/abs/a.jpg,/abs/b.jpg |

URL-scheme calls are fire-and-forget (no return value). When a result is needed, use the CLI (--json) or the MCP.

Recipes (CLI-first)

Loupe one image. open -a /Applications/Cull.app "cull://open?path=/abs/img.png&view=loupe".

Export the keepers. list_export_presets → export_images with --collection_id / --folder_path / --image_ids, an --output_dir, and --format.

Quality pass. analyze_image_quality (async — it returns a job; for CLI poll by re-reading) → get_quality_count for the distribution → get_image_quality per image.

Embeddings prerequisite. download_embedding_model (once) → generate_embeddings (async). Only then does similarity work (cull://similar?…, or find_similar over MCP).

When the MCP is needed (optional)

The headless CLI does not yet implement interactive curation and live navigation — those exist only as mcp__cull__* tools (or manual GUI). Reach for the MCP to:

• Navigate / show precisely from the agent: navigate_to_folder, show_image, show_collection (the URL scheme covers the common cases, but these give programmatic control and confirmation).
• Curate with round-trips: set_rating, set_decision, create_collection, add_to_collection, create_smart_collection.
• Search & vision with results: find_similar, search_by_object, detect_objects / get_detections, analyze_images, get_vision_metadata.
• Track async jobs: list_jobs / get_job / cancel_job.
• Publish: export_static_publish_package / serve_static_publish_package, clipboard-collection tools.

MCP mechanics. These tools are named mcp__cull__<tool> and in Claude Code are deferred — schemas aren't loaded, so a direct call fails. Load before calling, only what the recipe needs:

ToolSearch "select:mcp__cull__navigate_to_folder,mcp__cull__set_rating"

The MCP drops when Cull restarts. Quitting/relaunching the app kills its MCP server; it must be reconnected by the user via /mcp before any mcp__cull__* call works again. The CLI + URL scheme have no such dependency — prefer them, and fall back to MCP only for the interactive operations above.

Common mistakes

• Using open / Preview instead of Cull. The cardinal sin — review always happens in Cull (import_folder + cull://open, or the MCP show/navigate tools).
• Reaching for the MCP first. Default to the CLI + URL scheme; they're connection-free and restart-proof. MCP is the fallback for interactive curation.
• Assuming the MCP survived a Cull restart. It doesn't — the user must /mcp reconnect. Don't restart Cull mid-task if you depend on the MCP.
• Calling a deferred MCP tool before loading it. ToolSearch "select:mcp__cull__…" first.
• Treating async ops as synchronous. Embeddings, analysis, and large exports are jobs — poll, don't assume completion.
• Guessing params. Check cull <command> --help or load the MCP tool and read its schema.

Safety & limits

• Destructive ops need explicit intent. delete_collection and prune_audit_log remove data; confirm before running.
• Tokens are admin. create_token / rotate_token / revoke_token change access credentials — don't touch unless the user explicitly asks.