Cache
The dorsal cache command group allows you to manage the local metadata cache.
The cache is a SQLite db file located at .dorsal/cache.db in your home directory, and it is used to speed up local file operations.
This guide covers the seven sub-commands:
show: Display statistics about the local cache.path: Print the absolute path to the cache database file.build: Scan a directory to pre-populate the cache.prune: Remove stale records for files that are modified or deleted.optimize: Run a full maintenance routine (prune, vacuum, etc.).export: Export the entire cache to a file (JSON or JSON.GZ).clear: Permanently delete all data from the cache.
dorsal cache show
Displays information about the cache, including its location, size, and the number of records it contains.
Example
Run dorsal cache show to see a summary:
╭────────────────── Cache Summary ───────────────────╮
│ Database Path:/home/user/.dorsal/cache.db │
│ Database Size:7.4 MiB │
│ File Count:4,873 │
│ Hash Cache:245 │
╰────────────────────────────────────────────────────╯
Options
-
Output the summary as a raw JSON object:
CLI Docs
Usage: dorsal cache show [OPTIONS]
Displays statistics about the local file cache.
╭─ Options ───────────────────────────────────────────────────────────────────╮
│ --json Output the summary as a raw JSON object. │
│ --help Show this message and exit. │
╰─────────────────────────────────────────────────────────────────────────────╯
dorsal cache path
Print the absolute path to the cache database file.
Example
Options
-
Output the path as a raw JSON object:
CLI Docs
Usage: dorsal cache path [OPTIONS]
Prints the absolute path to the cache database file.
╭─ Options ───────────────────────────────────────────────────────────────────╮
│ --json Output the path as a raw JSON object. │
│ --help Show this message and exit. │
╰─────────────────────────────────────────────────────────────────────────────╯
dorsal cache build
Scans a directory and populates the cache with full metadata records.
Example
Scan a directory, and store all of its records in the cache by running dorsal cache build with the path of the directory you wish to scan:
The command will report its progress:
✅ Cache build complete.
- Total files processed: 25
- Loaded from cache: 25
- Newly added to cache: 0
Run with default settings, both dorsal cache build and dorsal dir scan have the same result (saving the metadata of all files to cache).
The main difference is the options and the terminal output.
Options
-
Scan all sub-directories recursively with
-ror--recursive: -
Force re-processing of all files, even if they are already in the cache, with
-for--force: -
Output the summary as a raw JSON object:
CLI Docs
Usage: dorsal cache build [OPTIONS] PATH
Scans a directory and populates the cache with full metadata records.
This command ensures that subsequent operations (like 'scan' or
'duplicates') on the same directory will be significantly faster by
pre-populating the cache.
╭─ Arguments ─────────────────────────────────────────────────────────────────╮
│ * path DIRECTORY The directory path to scan and populate the cache │
│ with. [required] │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│ --recursive -r / --no-recursive -R Scan subdirectories recursively. │
│ --force -f Force re-processing and │
│ re-caching of all files, even │
│ if they are already in the │
│ cache. │
│ --json Output the summary as a raw JSON │
│ object. │
│ --help Show this message and exit. │
╰─────────────────────────────────────────────────────────────────────────────╯
dorsal cache prune
Scans the cache and removes stale records.
A record is "stale" if the file it points to no longer exists or has been modified since it was cached.
Example
Output:
Pruning stale records from cache...
✅ Prune complete. Removed 12 stale records out of 1,433 scanned.
Options
-
Output the prune summary as a raw JSON object:
CLI Docs
Usage: dorsal cache prune [OPTIONS]
Scans the cache and removes stale records.
A record is considered stale if the file it points to no longer exists
or has been modified since it was cached.
╭─ Options ───────────────────────────────────────────────────────────────────╮
│ --json Output the prune summary as a raw JSON object. │
│ --help Show this message and exit. │
╰─────────────────────────────────────────────────────────────────────────────╯
dorsal cache optimize
Runs a full maintenance routine on the cache:
- Pruning stale records.
- Syncing record compression with the current config.
- Reclaiming disk space (VACUUM).
Example
Output:
Optimizing cache... (this may take a moment)
╭────── Cache Optimization Complete ─────╮
│ Records Removed: 12 │
│ Records Reprocessed: 0 │
│ │
│ Size Before Optimization: 1.2 MiB │
│ Size After Optimization: 1.1 MiB │
│ Disk Space Reclaimed: 100.5 KiB │
╰─────────────────────────────────────────╯
Options
-
Output the optimization summary as a raw JSON object:
CLI Docs
Usage: dorsal cache optimize [OPTIONS]
Runs a full maintenance routine on the cache.
This includes:
- Pruning stale records (for deleted or modified files).
- Syncing record compression with the current config.
- Reclaiming disk space (VACUUM).
╭─ Options ───────────────────────────────────────────────────────────────────╮
│ --json Output the optimization summary as a raw JSON object. │
│ --help Show this message and exit. │
╰─────────────────────────────────────────────────────────────────────────────╯
dorsal cache export
Exports the full contents of the local cache to a file. This is useful for backups, migrations, or offline data analysis.
Example
Export the cache to a compressed JSON file by running dorsal cache export:
Exporting cache to 'cache_backup.json.gz'...
✅ Successfully exported 7,099 records to '/home/user/.dorsal/export/cache-export-20251031-234053.json.gz'
Options
-
Specify a custom output path with
-oor--output: -
Specify the format (
jsonorjson.gz). If omitted, it's inferred from the output filename: -
Exclude full metadata records to create a smaller "hash-only" export:
CLI Docs
Usage: dorsal cache export [OPTIONS]
Exports the full contents of the local cache to a file.
╭─ Options ───────────────────────────────────────────────────────────────────╮
│ --output -o PATH Path to save the exported cache file. Defaults │
│ to the '.dorsal/export' directory. │
│ --format TEXT Output format ('json' or 'json.gz'). If not │
│ provided, it's inferred from the output file │
│ extension. │
│ --no-records Exclude full metadata records from the export │
│ to save space. │
│ --help Show this message and exit. │
╰─────────────────────────────────────────────────────────────────────────────╯
dorsal cache clear
Deletes the entire cache database file, permanently removing all cached data.
This action is irreversible and requires confirmation.
Example
Clear the cache by running dorsal cache clear:
Are you sure you want to delete the entire cache at /home/user/.dorsal/cache.db?
This action cannot be undone. [y/N]: y
Clearing cache...
✅ Cache cleared successfully.
Options
-
Bypass the interactive confirmation prompt with
-yor--yes:
CLI Docs
Usage: dorsal cache clear [OPTIONS]
Deletes the entire cache database file, permanently removing all cached data.
╭─ Options ───────────────────────────────────────────────────────────────────╮
│ --yes -y Bypass the confirmation prompt and clear the cache │
│ immediately. │
│ --help Show this message and exit. │
╰─────────────────────────────────────────────────────────────────────────────╯