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 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