Core

Command reference

A single binary, mailsubsystem <command> [options]. Run with no args or help for usage at the terminal.

Sync

Command	Description
`check`	Verify DB and IMAP connectivity.
`sync`	Full envelope sync + durable body sync (workers drain the body queue).
`sync-slow`	Only drain body queue (backfill bodies for rows missing `body_text`).
`status`	Show `imap_folders` and `emails` table state.
`sync-incremental`	Incremental sync (MODSEQ changes since last sync).
`sync-incremental --daemon`	Run incremental sync in a loop until Ctrl+C.
`sync-window [--days N] [--full]`	Sync envelopes for the last N days (or full if `--full`).
`daemon`	Unified daemon: incremental sync + periodic full + periodic slow.

Analyze

Command	Description
`analyze [--force] [message_id]`	AI analysis: batch (uses `ANALYZE_LIMIT`) or single email.
`test-llm --local`	Test connection to local LLM (LM Studio / Ollama).
`test-llm --frontier`	Test connection to a frontier provider (Gemini / OpenAI / Anthropic).
`show <message_id>`	Print AI fields stored in DB for that email.
`process-frontier-queue [--limit N]`	Re-analyze queued emails with frontier (default N=10).
`embed-backfill [--limit N]`	Generate embeddings for emails missing them (RAG; default N=50).

Locate & file

Command	Description
`resolve-orphans`	Find rows with `location=NULL` by Message-ID in other folders; update or mark deleted.
`locate [--force] [message_id]`	Agentic folder recommendation (batch or one).
`file [--dry-run]`	Apply location recommendations: create folder if needed, IMAP MOVE, update DB.

Maintenance

Command	Description
`backfill-message-tokens`	Backfill `message_tokens` (chars / 4) for emails with body content.
`backfill-message <message_id>`	Fetch one message from IMAP and backfill null fields.
`backfill-from-imap [--limit N]`	Fetch from IMAP to backfill `received_date`, `raw_email_content`, `body_text`, etc. (default N=100).

Example workflow

# One-time full sync and analyze
./target/release/mailsubsystem sync
./target/release/mailsubsystem analyze
./target/release/mailsubsystem embed-backfill --limit 100   # optional, for RAG
./target/release/mailsubsystem locate
./target/release/mailsubsystem file --dry-run              # preview
./target/release/mailsubsystem file                        # apply

# Daemon for ongoing sync only (analyze/locate/file still manual)
./target/release/mailsubsystem daemon

Configuration

Configuration is via environment variables. See the repository README and GAP_CLOSURE_SPEC.md for the full list. Most relevant groups:

Group	Examples	Purpose
IMAP	`ICLOUD_IMAP_SERVER`, `ICLOUD_USERNAME`, `ICLOUD_PASSWORD`	Mailbox connection (any IMAP server).
Database	`DATABASE_URL`, `DB_HOST`, `DB_NAME`	PostgreSQL connection and runtime persistence.
AI providers	`AI_PROVIDER`, `LOCAL_LLM_URL`, `GEMINI_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`	Local-first or hosted model routing.
Daemon & batches	`INCREMENTAL_SYNC_INTERVAL_SECS`, `ANALYZE_LIMIT`, `LOCATE_LIMIT`	Operational cadence and processing limits.