Commands

Generated from capsule-cli/cli-surface.json, the committed command tree capsule-cli emits and mise run cli-surface-check keeps current. To change a description on this page, change the clap annotation it comes from and regenerate — this file is build output.

capsule

capsule <COMMAND>

Capsule CLI provides tools for managing your photos and albums:

• Authentication management
• Sync local and remote data
• Check status and list files
• Manage albums and collections

Command	Description
capsule auth	Authentication commands
capsule cull	Review a local library: flag assets, filter by flag, sweep rejects to trash
capsule demo	Run the offline end-to-end data-plane showcase (real cryptography, no network)
capsule import	Import files into a local Capsule library
capsule library	Manage the local library
capsule list	List the assets the sync feed has delivered
capsule match	Match metadata for current file
capsule push	Upload a local Capsule library to the server
capsule repair	Repair a local library in place, one signed correction per affected asset
capsule reset	Reset all local CLI data
capsule show	Show what an imported asset’s signed sidecar records: caption, rating, tags, GPS, timestamps
capsule status	Show current status
capsule sync	Sync local and remote data

capsule auth

capsule auth <COMMAND>

Authentication commands

Command	Description
capsule auth login	Login to Capsule
capsule auth logout	Logout from Capsule
capsule auth register	Create a Capsule account and sign in
capsule auth status	Show authentication status

capsule auth login

capsule auth login [OPTIONS]

Login to Capsule

Option	Description
--email <EMAIL>	Account email (prompted when omitted).
--password-stdin	Read the password from stdin instead of prompting, so the command works in scripts and CI where there is no terminal.

capsule auth logout

capsule auth logout

Logout from Capsule

capsule auth register

capsule auth register [OPTIONS]

Create a Capsule account and sign in

Option	Description
--email <EMAIL>	Account email (prompted when omitted).
--password-stdin	Read the password from stdin instead of prompting, so the command works in scripts and CI where there is no terminal.

capsule auth status

capsule auth status

Show authentication status

capsule cull

capsule cull --library <PATH> [OPTIONS]

Review a local library: flag assets, filter by flag, sweep rejects to trash

Option	Description
--library <PATH>	Required. Path to the Capsule library.
--passphrase-stdin	Read the library passphrase from stdin instead of prompting, so culling works in scripts and CI where there is no terminal.
--pick <ASSET_ID>	Flag an asset as a keeper (repeatable).
--neutral <ASSET_ID>	Clear an asset’s flag back to the never-flagged default (repeatable).
--reject <ASSET_ID>	Flag an asset for rejection (repeatable).
--filter <FLAG>	List the assets carrying one flag instead of only counting them. Values: pick, neutral, reject.
--sweep	Move every rejected asset to trash. The only destructive step, and soft per retention — swept assets stay restorable until the window elapses.
--retain-days <DAYS>	Retention window, in days, the sweep’s soft delete stamps. Default: 30.

capsule demo

capsule demo [OPTIONS]

Run the offline end-to-end data-plane showcase (real cryptography, no network)

Option	Description
--workdir <PATH>	Working directory for the demo libraries (a temp dir is used if omitted).
--image <PATH>	A real image/file to import (a small synthetic file is used if omitted).

capsule import

capsule import <PATH>... --library <PATH> [OPTIONS]

Import files into a local Capsule library

Argument	Description
<PATH>...	Required. Source file or directory to import. Repeatable: a split Takeout export extracted into several folders is imported by naming every part in one run, so a media file and a sidecar that landed in different parts are still paired.

Option	Description
--provider <PROVIDER>	Read the source as an export from this service instead of as a plain directory tree, so its out-of-band metadata (capture time, GPS, captions, favorites, album membership) is folded into the imported assets. Values: takeout.
--library <PATH>	Required. Path to the Capsule library.
--move	Move files instead of copying them.
--force	Re-import files even if they already exist (duplicate override).
--passphrase-stdin	Read the library passphrase from stdin instead of prompting, so imports work in scripts and CI where there is no terminal.
--push	Push the library to the server after importing — sugar for a capsule push run over the same library. The import itself stays offline.
--staged	Stage the follow-on push (--push) in tier order, gating the preview and original tiers on the connection class.

capsule library

capsule library <COMMAND>

Manage the local library

Command	Description
capsule library info	Show library information
capsule library init	Create a new Capsule library
capsule library rebuild	Rebuild the SQLite index from sidecar files

capsule library info

capsule library info <PATH>

Show library information

Argument	Description
<PATH>	Required. Path to the library.

capsule library init

capsule library init <PATH> [OPTIONS]

Create a new Capsule library

Argument	Description
<PATH>	Required. Directory for the new library.

Option	Description
--name <NAME>	Human-readable library name. Default: My Library.

capsule library rebuild

capsule library rebuild <PATH>

Rebuild the SQLite index from sidecar files

Argument	Description
<PATH>	Required. Path to the library.

capsule list

capsule list [OPTIONS]

List the assets the sync feed has delivered

Option	Description
--include-deleted	Include assets the server has tombstoned (deleted) as well as live ones.

capsule match

capsule match <PATH>

Match metadata for current file

Argument	Description
<PATH>	Required. Path to the file to match metadata for.

capsule push

capsule push --library <PATH> [OPTIONS]

Upload a local Capsule library to the server

Option	Description
--library <PATH>	Required. Path to the Capsule library to push.
--passphrase-stdin	Read the library passphrase from stdin instead of prompting, so pushes work in scripts and CI where there is no terminal.
--dry-run	Report what would be uploaded without opening a single upload session.
--force	Re-drive every blob regardless of what the server already holds.
--staged	Open the tier sessions in ladder order (index → preview → original), gating the above-index tiers on the connection class, instead of opening all eagerly.

capsule repair

capsule repair <COMMAND>

Repair a local library in place, one signed correction per affected asset

Command	Description
capsule repair capture-time	Re-read each original’s EXIF capture time and report every asset whose signed capture timestamp disagrees with it; with —apply, correct each one as a signed metadata update

capsule repair capture-time

capsule repair capture-time --library <PATH> [OPTIONS]

Re-read each original’s EXIF capture time and report every asset whose signed capture timestamp disagrees with it; with —apply, correct each one as a signed metadata update

Option	Description
--library <PATH>	Required. Path to the Capsule library.
--passphrase-stdin	Read the library passphrase from stdin instead of prompting, so the command works in scripts and CI where there is no terminal.
--apply	Write the corrections. Without this flag the pass only reports what it would change; each correction is an irreversible signed record on the asset’s chain.
--limit <COUNT>	Correct at most this many affected assets in one —apply run (the report still covers the whole library).

capsule reset

capsule reset [OPTIONS]

Reset all local CLI data

Option	Description
--config	Reset configuration.
--data	Reset data directory.
--cache	Reset cache directory.
--all	Reset all data.

capsule show

capsule show <ASSET> --library <PATH> [OPTIONS]

Show what an imported asset’s signed sidecar records: caption, rating, tags, GPS, timestamps

Argument	Description
<ASSET>	Required. The asset to show: its id, or a prefix of at least 8 hex characters of its SHA-256 content hash — the same digest shasum -a 256 prints for the source file.

Option	Description
--library <PATH>	Required. Path to the Capsule library.
--passphrase-stdin	Read the library passphrase from stdin instead of prompting, so the command works in scripts and CI where there is no terminal.

capsule status

capsule status

Show current status

capsule sync

capsule sync [OPTIONS]

Sync local and remote data

Option	Description
--force	Discard the saved cursor and re-drain the feed from the start. The per-album anti-rewind floor still applies, so this cannot resurrect stale entries.
--dry-run	Perform a dry run without making changes.