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
A path that is not under any known root is an error. A path that is under a known root but holds no known sources depends on how many paths you gave:
| Paths given | Behavior |
|---|---|
| One, no known sources | Error: no sources known at <path> |
| Several, at least one with sources | The others are skipped and named; the command runs on the rest and exits 0 |
| Several, none with sources | Error naming every path |
A skipped path is always stated, never silently dropped:
no sources known at /path/to/photos/2012 — skipped
Where the line appears follows the command’s own scope channel: stdout for
report commands (facts, coverage, survey), stderr for list commands
(ls, worklist), and in the ceremony before any confirmation for commands
that change state (exclude set/clear/set-object, cluster generate,
facts delete) — including under --yes and --dry-run. Display modes that
render a bare stream and carry no scope header of their own
(coverage --compact, survey --detail unique) state it on stderr, so what
is on stdout stays exactly what was asked for. A skipped path never appears
in the decision record.
Four commands never skip, because a location they name is load-bearing to the
question rather than one more place to look: both sides of compare, the
scope and --prefer paths of exclude duplicates, and survey --other.
These error as a single path does.
Paths you pass on the command line match the index whichever Unicode normalization form you type. Canon stores the form the disk gave it and matches your argument against that.
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
--include only changes what’s displayed; it 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
- roots story: Read a root’s resolution story as a map of places
- roots retire: Bind a resolved root’s story into a book and release the root
- 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
- Managing Sources: Control which sources are processed
- Archiving: Organize files into your canonical archive
- Maintenance: Clean up and maintain the database
- facts delete: Remove incorrect or unwanted metadata
- prune: Clean up stale, orphaned, or excluded data
- ledger reindex: Rebuild the extraction ledger from receipts