Canon Commands

Common Options

Most commands that operate on sources share these options:

Path scope — Limit a command to a specific directory by passing a path:

canon ls /path/to/photos
canon facts /path/to/photos
canon coverage /path/to/photos

Filters — Select sources using --where with boolean expressions:

canon ls --where 'source.ext=jpg'
canon facts --where 'source.size > 1000000'
canon cluster generate --where 'geo.country=Netherlands' --dest /archive

Multiple --where flags are combined with AND. See Filters for the full syntax.

--include — By default, query commands (ls, facts, coverage, worklist, compare) show sources from active source roots, hiding excluded and archived sources. Use --include to expand what you see:

canon ls --include excluded          # Also show excluded sources
canon ls --include archived          # Also show sources from archive roots
canon facts --include all            # Show everything

This is always safe — --include only changes what’s displayed, never modifies anything.

--allow — Commands that change state (cluster generate, apply, import-facts) skip certain sources by default (e.g., sources already in an archive). Use --allow to acknowledge you want to include them:

canon cluster generate --allow archived     # Include sources from archive roots
canon cluster generate --allow duplicates   # Include content already archived elsewhere
canon import-facts --allow archived         # Import facts for archive sources

The available --allow values are specific to each command. See individual command pages for details.

Command Reference

• Managing Roots: Add and manage storage locations
  • scan: Scan existing or new roots
  • roots: List, suspend, or remove roots
• Enriching: Import metadata from external tools
  • worklist: Output sources for external processing
  • import-facts: Import processor output
  • Writing Processors: Build custom extractors
• Querying: Explore your indexed files
  • ls: List sources matching filters
  • facts: Discover available metadata
  • compare: Compare directories by content
• Managing Sources: Control which sources are processed
  • exclude: Mark sources to skip during archiving
• Archiving: Organize files into your canonical archive
  • coverage: Check archive progress
  • cluster: Generate a manifest for archiving
  • apply: Execute the manifest to copy/move files
• Maintenance: Clean up and maintain the database
  • facts delete: Remove incorrect or unwanted metadata
  • prune: Clean up stale, orphaned, or excluded data