Caesim

Caesim is a safe image-library trimming CLI. It scans a folder, finds images that match a rule or Vision label, and moves matches into a review folder instead of deleting them.

Install

cargo install --path .

Or download and install the ready made package

Quick Start

Preview a run first:

caesim cut ./photos --rule screenshots --dry-run

Move matches into ./photos/cut:

caesim cut ./photos --rule screenshots

Use a custom destination:

caesim cut ./photos --rule landscape --destination ./review

Search by Vision label:

caesim cut ./photos --find receipt --dry-run

Caesim writes a JSON report after each run. By default it is saved in your XDG cache directory (or $HOME/.cache/caesim) so it does not clutter the scanned folder. Report filenames are now prefixed with the run id, for example: 1779436443-Random_Images.caesim-report.json. You can still override the path with --report.

You can restore a previous cut from that report with:

caesim cut undo --report ./photos/.caesim-report.json

Rules

Current local rules:

• screenshots
• duplicates
• explicit
• landscape
• portrait

explicit uses Google SafeSearch signals when Vision mode is enabled. --find <label> also enables Vision mode for label searches such as receipt or cars.

Useful options:

• --dry-run: preview without moving files
• --destination <folder>: choose the review folder
• --cut-dir <name>: change the default cut folder name
• --report <file>: choose the report path

Vision Mode

Vision mode requires a local Caesim session, credits, Google credentials, and the Python Vision backend dependencies.

caesim vision
caesim login
caesim credits balance

If needed, install the Python dependency:

pip install -r requirements.txt

You can point Caesim at a custom backend with CAESIM_VISION_BACKEND.

Accounts and AI Assist

For Supabase environment variables and session setup, see DEVELOPER.md.

Common commands:

caesim signup --email you@example.com
caesim login --email you@example.com
caesim whoami
caesim credits balance
caesim logout

caesim ai-assist starts an interactive assistant that turns cleanup requests into safe caesim cut commands.

Payments

The Supabase schema now includes a Stripe-ready payment foundation:

• public.users carries billing metadata such as stripe_customer_id.
• public.credit_ledger records every credit delta with source metadata.
• public.payment_events stores idempotent payment events for later webhook replay.
• The credit gateway exposes an admin-only payment action so a future Stripe webhook can reuse the same mutation path.

See supabase/README.md and supabase/functions/credit-gateway/README.md for the request shape.

Version Bumps

To bump the release version in one step, run:

./scripts/bump-version.sh 0.1.6

This updates Cargo.toml, Cargo.lock, and debian/changelog, then runs the version checks and a build.

Documentation

• CONTRIBUTING.md for contributor workflow and pull request expectations.
• DEVELOPER.md for architecture, implementation notes, and release details.