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.
Upload a local Capsule library to the server. An asset handed to another device with capsule peer delegate is left to that device while its hand-off is open
Read the password from stdin instead of prompting, so the command works in scripts and CI where there is no terminal.
--oidc
Sign in through the server’s identity provider in a browser instead of with a password. The server must allow loopback redirects (OIDC_ALLOW_LOOPBACK_REDIRECT=true).
--no-browser
With —oidc, print the sign-in address without opening a browser.
--device
With —oidc, sign in from another device: print an address and a code instead of using a browser here.
--json
Print the outcome as one JSON document on stdout; prompts, progress and, with —oidc, the sign-in address and code go to stderr.
Evict cached thumbnails, previews and fetched originals, least recently viewed first, until the cache fits the budget the current connection class allows. Pinned representations, device-owned originals and the library’s own media are never evicted
Evict cached thumbnails, previews and fetched originals, least recently viewed first, until the cache fits the budget the current connection class allows. Pinned representations, device-owned originals and the library’s own media are never evicted
Option
Description
--library <PATH>
Required. Path to the Capsule library.
--json
Print the run as one JSON document on stdout: the plan it ran under and each evicted representation.
Copy every object off a camera into the library: each is received and hash-checked into a staging area under the library, then imported like a card reader’s files. Nothing on the camera is changed, and an interrupted run resumes where it stopped
Copy every object off a camera into the library: each is received and hash-checked into a staging area under the library, then imported like a card reader’s files. Nothing on the camera is changed, and an interrupted run resumes where it stopped
Option
Description
--address <HOST[:PORT]>
The camera’s address on the network, as HOST or HOST:PORT (port 15740 when omitted); the camera shows it on its Wi-Fi or “Remote/PC connection” screen. Without it, the one camera capsule camera discover finds is used, and none or several refuse the run.
--library <PATH>
Required. Path to the Capsule library.
--passphrase-stdin
Read the library passphrase from stdin instead of prompting, so imports work in scripts and CI where there is no terminal.
--json
Print the run as one JSON document on stdout: the camera, the identity presented to it, every object received or left on the camera and why, and the import’s report.
Subscribe to an album on another server, so this account’s server pulls it. The capability token from the share invite is read from stdin as one line, never from the command line. Posting one for an album already subscribed renews it
Subscribe to an album on another server, so this account’s server pulls it. The capability token from the share invite is read from stdin as one line, never from the command line. Posting one for an album already subscribed renews it
Option
Description
--issuer <HOST>
Required. The album’s home server, which minted the capability (e.g. home.example).
--json
Print the subscription as one JSON document on stdout: whether it was created, and its peer, album, scope, jti, issue, expiry and subscription instants and liveness.
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: delete each source once the server holds it, which needs --push. Without it every source is kept.
--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.
--json
Print the run as one JSON document on stdout: the totals, including how many originals arrived without derivatives and why, and each file’s outcome. Not combined with --push; run capsule push --json for the push report.
List a library’s timeline, albums or stacks, as the TUI’s library browser shows them
Option
Description
--library <PATH>
Required. Path to the Capsule library.
--view <VIEW>
Which view to list. Values: timeline, albums, stacks. Default: timeline.
--passphrase-stdin
Read the library passphrase from stdin instead of prompting, so the command works in scripts and CI where there is no terminal.
--json
Print the view as one JSON document on stdout: the timeline’s assets, every album with its labels and assets, or every stack with its labels and members.
Take hand-off files another device of this account sealed for this one, then upload every hand-off this device holds under its own session, deleting each copy once the server holds it. A hand-off that can never succeed is quarantined: kept, not retried, listed by capsule peer status and deleted only by capsule peer discard
Seal assets’ uploads for another device of this account to upload later. Each asset is written to a hand-off file the other device takes with capsule peer accept, or with --peer handed over the LAN peering channel to capsule peer accept --listen; this device keeps every original until its own check finds the server holds it
Delete a quarantined hand-off this device holds for another device. Only a quarantined copy can be discarded; it may be the account’s only copy of the asset, so recover it first if its origin device is lost
Stop retrying a delete made after a hand-off that capsule peer status keeps reporting as not applied because the library holds neither the asset nor its tombstone. Local only: the server keeps the asset as it holds it. Refused while the library still holds the asset’s chain, since capsule peer status can then send the delete
Send this library’s assets to another device of this account over the LAN peering channel: dial its capsule peer pull --listen, verify it over mutual TLS as a device of this account, and serve it one backup artifact sealed for that session. The other device skips what it already holds and refuses what it has purged
Take assets another device of this account sends with capsule peer offer: listen on ADDR, verify the device over mutual TLS, pull its backup artifact and write every asset that is new or a forward update. An asset this device has purged is refused, and the run is refused before listening if the purge record cannot be read
Show this device’s handed-off assets: take the other device’s acknowledgements, take back uploads that are overdue or whose device was revoked, and release what the server holds. A delete made after a hand-off is held until the server holds the asset, then sent. Also lists every hand-off this device quarantined
Take hand-off files another device of this account sealed for this one, then upload every hand-off this device holds under its own session, deleting each copy once the server holds it. A hand-off that can never succeed is quarantined: kept, not retried, listed by capsule peer status and deleted only by capsule peer discard
Option
Description
--library <PATH>
Required. Path to this device’s Capsule library.
--from <FILE>
A hand-off file to take (repeatable); without one, only the held hand-offs upload.
--listen <ADDR>
Also take hand-offs over the LAN peering channel: listen on ADDR (e.g. 0.0.0.0:7420) for the other device’s capsule peer delegate --peer, verify it over mutual TLS as a device of this account, pull each hand-off it sealed for this device, and acknowledge each over the same channel once it is persisted. Only local-network peers are admitted. The address bound is printed on stderr.
--listen-timeout <SECONDS>
Seconds --listen waits for a peer to connect and verify; a verified session is not cut by it, but runs to its end at a minimum transfer rate. Default: 300.
--staged
Open the tier sessions in ladder order, gating the above-index tiers on the connection class, as capsule push --staged does.
--passphrase-stdin
Read the library passphrase from stdin instead of prompting, so the command works in scripts and CI where there is no terminal.
--json
Print the run as one JSON document on stdout: each hand-off taken with its acknowledgement (and, over the channel, the peer it came from and whether the peer took the acknowledgement), each refused, and what became of each held hand-off (removed, kept, failed and kept, or permanently refused and quarantined), each failure with a stable kind, the server’s code when it gave one, and the detail.
Seal assets’ uploads for another device of this account to upload later. Each asset is written to a hand-off file the other device takes with capsule peer accept, or with --peer handed over the LAN peering channel to capsule peer accept --listen; this device keeps every original until its own check finds the server holds it
Option
Description
--library <PATH>
Required. Path to the Capsule library holding the assets.
--to <DEVICE_ID>
The device to hand the uploads to: its id in this account’s device directory. Required with --out; with --peer, the device the channel verifies must be this one.
--asset <ASSET_ID>
Required. An asset to hand off (repeatable).
--out <DIR>
Directory the hand-off files are written to.
--peer <HOST:PORT>
Hand the uploads over the LAN peering channel instead of files: dial the other device’s capsule peer accept --listen at HOST:PORT, verify it over mutual TLS as a device of this account, and serve it each hand-off to pull and acknowledge over the same channel. Only a local-network address is dialed.
--deadline-hours <HOURS>
Hours to wait for the server to hold the assets before taking the uploads back. Default: 24.
--passphrase-stdin
Read the library passphrase from stdin instead of prompting, so the command works in scripts and CI where there is no terminal.
--json
Print the run as one JSON document on stdout: the delegate, each asset handed off, with its file or whether the delegate acknowledged it over the channel, and its content address, and each that was not, with a stable kind, the server’s code when it gave one, and the detail.
Delete a quarantined hand-off this device holds for another device. Only a quarantined copy can be discarded; it may be the account’s only copy of the asset, so recover it first if its origin device is lost
Argument
Description
<HAND_OFF>
Required. The quarantined hand-off’s content address, as capsule peer status lists it.
Option
Description
--library <PATH>
Required. Path to this device’s 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.
--json
Print the discarded hand-off as one JSON document on stdout: its content address, its asset and the kind it had been quarantined for.
Stop retrying a delete made after a hand-off that capsule peer status keeps reporting as not applied because the library holds neither the asset nor its tombstone. Local only: the server keeps the asset as it holds it. Refused while the library still holds the asset’s chain, since capsule peer status can then send the delete
Argument
Description
<ASSET_ID>
Required. The asset, as capsule peer status lists it.
Option
Description
--library <PATH>
Required. Path to the Capsule library holding the assets.
--passphrase-stdin
Read the library passphrase from stdin instead of prompting, so the command works in scripts and CI where there is no terminal.
--json
Print the run as one JSON document on stdout: the asset and how many outbox entries were dropped.
Send this library’s assets to another device of this account over the LAN peering channel: dial its capsule peer pull --listen, verify it over mutual TLS as a device of this account, and serve it one backup artifact sealed for that session. The other device skips what it already holds and refuses what it has purged
Option
Description
--library <PATH>
Required. Path to the Capsule library holding the assets.
--peer <HOST:PORT>
Required. The other device’s capsule peer pull --listen address. Only a local-network address is dialed.
--to <DEVICE_ID>
The device the channel must verify; refused if the device at --peer is another.
--asset <ASSET_ID>
An asset to send (repeatable); without one, every asset in the library is sent.
--passphrase-stdin
Read the library passphrase from stdin instead of prompting, so the command works in scripts and CI where there is no terminal.
--json
Print the run as one JSON document on stdout: the device the channel verified, the artifact’s content address, size and assets, how many bytes the other device pulled, and each failure with a stable kind and the detail.
Take assets another device of this account sends with capsule peer offer: listen on ADDR, verify the device over mutual TLS, pull its backup artifact and write every asset that is new or a forward update. An asset this device has purged is refused, and the run is refused before listening if the purge record cannot be read
Option
Description
--library <PATH>
Required. Path to this device’s Capsule library.
--listen <ADDR>
Required. The address to listen on (e.g. 0.0.0.0:7420). Only local-network peers are admitted. The address bound is printed on stderr.
--listen-timeout <SECONDS>
Seconds to wait for a peer to connect and verify; a verified session is not cut by it, but runs to its end at a minimum transfer rate. Default: 300.
--passphrase-stdin
Read the library passphrase from stdin instead of prompting, so the command works in scripts and CI where there is no terminal.
--json
Print the run as one JSON document on stdout: the peer, each artifact pulled, the assets applied, quarantined (the peer sent stale state), tombstoned (purged here), identical (already held) and incomplete, each failure and each refused connection with a stable kind and the detail.
Show this device’s handed-off assets: take the other device’s acknowledgements, take back uploads that are overdue or whose device was revoked, and release what the server holds. A delete made after a hand-off is held until the server holds the asset, then sent. Also lists every hand-off this device quarantined
Option
Description
--library <PATH>
Required. Path to the Capsule library holding the assets.
--ack <FILE>
An acknowledgement file capsule peer accept wrote (repeatable).
--passphrase-stdin
Read the library passphrase from stdin instead of prompting, so the command works in scripts and CI where there is no terminal.
--json
Print the run as one JSON document on stdout: each delegation with its state, each refused acknowledgement with a stable kind and the detail, each quarantined hand-off with its file, the stable kind of its refusal, the server’s code when it gave one, and the detail, and each delete made after a hand-off with the records between the hand-off and it (held, sent, failed and kept, or refused and not retried).
Upload a local Capsule library to the server. An asset handed to another device with capsule peer delegate is left to that device while its hand-off is open
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.
--asset <ASSET_ID>
Push only this asset (repeatable); every asset in the library when omitted. Retries the assets a run reported failed without re-importing them or re-checking the ones that reached custody.
--json
Print the run as one JSON document on stdout: the totals and each asset’s outcome (verified, failed with its error, delegated to another device, or planned on a dry run).
--path-cost <COST>
What the path costs; on metered or constrained the push is staged and the preview and original tiers wait. Values: unmetered, metered, constrained.
--path-interface <INTERFACE>
The interface the path runs over. Values: wired, wifi, cellular, other.
--power <POWER>
The power source; low-power holds the preview and original tiers back. Values: external, battery, low-power.
--thermal <STATE>
The thermal state; serious holds the preview and original tiers back, critical sends nothing. Values: nominal, fair, serious, critical.
--background-deadline <SECONDS>
Run as a background task the OS ends this many seconds from now; under a minute holds the preview and original tiers back.
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
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); only meaningful with —apply.
Show how the server signs people in: its identity provider, and whether it accepts passwords, from its public server-info record
Option
Description
--json
Print the record as one JSON document on stdout: the server’s id, whether it has an identity provider (oidc) and whether it refuses passwords (password_disabled).
Issue a view-only share link for an album or one asset, and print the URL to send
Option
Description
--library <PATH>
Required. Path to the Capsule library.
--album <ALBUM_ID>
Share every asset of this album that is not in trash.
--asset <ASSET_ID>
Share this one asset.
--expires-at <TIMESTAMP>
When the link stops opening, as an RFC 3339 timestamp (e.g. 2026-12-31T23:59:59Z).
--passphrase-stdin
Read the library passphrase from stdin instead of prompting, so the command works in scripts and CI where there is no terminal.
--protect
Protect the link with a passphrase the recipient must enter as well as open the URL.
--link-passphrase-stdin
With —protect, read the link passphrase from stdin instead of prompting (the line after the library passphrase when —passphrase-stdin is also given).
--json
Print the issued link as one JSON document on stdout: its opaque id, URL, how many assets it covers, whether it is passphrase-protected, and its expiry.
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.
--json
Print the asset as one JSON document on stdout: every sidecar field, null where unset, and its provenance history record by record.
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.
--library <PATH>
The library to re-announce from when the server has rebuilt this library’s index: with it, a sync that meets a stale cursor runs capsule sync reannounce itself.
--passphrase-stdin
Read the library passphrase from stdin instead of prompting (with --library).
--json
Print the run as one JSON document on stdout: how many changes were applied across how many albums and pages, whether the server had rebuilt the index, and the re-announce report when --library ran one.
Give the server back the signed manifests this library holds and its feed no longer lists, after it rebuilt this library’s index. Manifests only: no bytes are uploaded
Give the server back the signed manifests this library holds and its feed no longer lists, after it rebuilt this library’s index. Manifests only: no bytes are uploaded
Option
Description
--library <PATH>
Required. Path to the Capsule library whose manifests are re-announced.
--passphrase-stdin
Read the library passphrase from stdin instead of prompting, so the command works in scripts and CI where there is no terminal.
--dry-run
Report what would be re-announced without sending anything.
--json
Print the run as one JSON document on stdout: the totals and each asset’s answer (restored, already indexed, missing blobs, refused, or planned on a dry run).
Move assets to the trash: sign a delete carrying a retention window and send it to the server. Soft: each asset stays restorable until its window elapses
Restore assets from the trash: sign a trash-restore and send it to the server. An asset whose retention window has closed cannot be restored, and is not retried
Move assets to the trash: sign a delete carrying a retention window and send it to the server. Soft: each asset stays restorable until its window elapses
Option
Description
--library <PATH>
Required. Path to the Capsule library.
--asset <ASSET_ID>
Required. The asset to move to the trash (repeatable).
--retain-days <DAYS>
Retention window, in days, a fresh delete signs. An asset already in the trash (for example by capsule cull --sweep) is resent with the window it was deleted with; --json reports that window as retention_until. Default: 30.
--passphrase-stdin
Read the library passphrase from stdin instead of prompting, so the command works in scripts and CI where there is no terminal.
--json
Print the run as one JSON document on stdout: the totals and each asset’s outcome (applied, or failed with a stable kind and the server’s code).
Restore assets from the trash: sign a trash-restore and send it to the server. An asset whose retention window has closed cannot be restored, and is not retried
Option
Description
--library <PATH>
Required. Path to the Capsule library.
--asset <ASSET_ID>
Required. The asset to restore (repeatable).
--passphrase-stdin
Read the library passphrase from stdin instead of prompting, so the command works in scripts and CI where there is no terminal.
--json
Print the run as one JSON document on stdout: the totals and each asset’s outcome (applied, or failed with a stable kind such as retention_elapsed, the server’s code and the retention floor).