Skip to content

Command Reference

Jump to bottom Edit New page
Ashley Davis edited this page Jun 14, 2026 · 22 revisions

The Photosphere CLI (psi) is a command-line tool for managing your media file database.

Global Options

These options are available for most commands:

  • --db <name-or-path> - The directory that contains the media file database, or a database name from databases.toml (defaults to current directory). When a name is given, the path and linked secrets (S3, encryption, geocoding) are resolved automatically from ~/.config/photosphere/databases.toml. If the name is not found, fuzzy-matched suggestions are displayed (e.g. Did you mean: my-photo?).
  • -k, --key <keyfile-or-secret> - Encryption key(s); comma-separated list (first key is the default/write key). Each entry is either a file path to a PEM key file or a vault secret name. Same for --dest-key and --source-key where used. The PSI_ENCRYPTION_KEY environment variable provides the same capability as -k for scripted use. If a vault secret name is not found in interactive mode, you will be prompted to add the key by pasting PEM text or importing from a file; in non-interactive mode (--yes) the command exits with an error instead.
  • -v, --verbose - Enables verbose logging
  • -y, --yes - Non-interactive mode (use command line arguments and defaults)
  • --version - Print the psi version and exit

Commands

add (alias: a) - Add Media Files

Purpose: Add files and directories to the Photosphere media file database.

Usage:

psi add <files...> [options]  # or psi a <files...> [options]

Arguments:

  • <files...> - Media files or directories to add to the database (required)

Options:

  • --db <path> - The directory containing the media file database (defaults to current directory)
  • -k, --key <keyfile> - Path to the private key file for encryption
  • --tools - Enables output from media processing tools (ImageMagick, ffmpeg, etc.)
  • --dry-run - Scan and report without making changes
  • --workers <number> - Number of parallel workers
  • --cwd <path> - Override the current working directory
  • --session-id <id> - Session ID for tracking progress
  • -v, --verbose - Enables verbose logging
  • -y, --yes - Non-interactive mode (use command line arguments and defaults)

Examples:

psi add --db ~/photos ~/my-photos
psi add --db ~/photos ~/vacation-pics ~/family-photos
psi add --db . /path/to/photos --verbose

bug - Generate Bug Report

Purpose: Generate a bug report for GitHub with system information and logs.

Usage:

psi bug [options]

Options:

  • -v, --verbose - Enables verbose logging
  • -y, --yes - Non-interactive mode (use command line arguments and defaults)
  • --no-browser - Don't open the browser automatically

Examples:

psi bug
psi bug --no-browser

check (alias: chk) - Check Media Files

Purpose: Check which files have already been added to the media file database to avoid duplicates.

Usage:

psi check <files...> [options]  # or psi chk <files...> [options]

Arguments:

  • <files...> - Media files or directories to check against the database (required)

Options:

  • --db <path> - The directory containing the media file database (defaults to current directory)
  • -k, --key <keyfile> - Path to the private key file for encryption
  • --tools - Enables output from media processing tools (ImageMagick, ffmpeg, etc.)
  • --workers <number> - Number of parallel workers
  • --timeout <ms> - Timeout in milliseconds
  • --cwd <path> - Override the current working directory
  • -v, --verbose - Enables verbose logging
  • -y, --yes - Non-interactive mode (use command line arguments and defaults)

Examples:

psi check --db ~/photos ~/Pictures
psi check --db ~/photos image.jpg video.mp4
psi check --db ~/photos ~/Downloads/photos

compare (alias: cmp) - Database Comparison

Purpose: Compare two media file databases by analyzing their Merkle trees to identify differences

Usage:

psi compare [options]  # or psi cmp [options]

Options:

  • --db <path> - Source database directory (required)
  • --dest <path> - Destination database directory (required)
  • -k, --key <keyfile> - Source encryption key path(s); comma-separated list
  • --dk, --dest-key <keyfile> - Destination encryption key path(s); comma-separated list
  • --full - Show all differences without truncation
  • --max <number> - Maximum number of items per category to display (default: 10)
  • -v, --verbose - Enables verbose logging
  • -y, --yes - Non-interactive mode (use command line arguments and defaults)

Examples:

psi compare --db ~/photos --dest ~/backup/photos
psi compare --db ~/photos --dest s3:backup-bucket/photos
psi compare --db s3:source-bucket/photos --dest ~/local-copy
psi compare --db ~/photos --dest ~/backup --key source.key --dk backup.key

Exit Codes:

  • 0 - Comparison completed successfully (regardless of differences found)

database-id - Show Database ID

Purpose: Print the unique UUID of the database. Each database is assigned a UUID when initialised; this ID is stored in the merkle tree and can be used to distinguish databases from one another.

Usage:

psi database-id [options]

Options:

  • --db <path> - The directory containing the media file database (defaults to current directory)
  • -k, --key <keyfile> - Path to the private key file for encryption
  • -v, --verbose - Enables verbose logging
  • -y, --yes - Non-interactive mode (use command line arguments and defaults)

Examples:

psi database-id --db ~/photos
psi database-id --db .

Output: Prints the database UUID to stdout.

dbs (alias: d) - Database List Management

Purpose: Manage the list of configured databases stored in ~/.config/photosphere/databases.toml. Each entry has a name, path, and optional links to shared secrets (S3 credentials, encryption keys, geocoding API keys).

dbs list (aliases: dbs l, dbs ls)

List all configured databases (name and path).

psi dbs list
psi dbs l
psi d ls

dbs add

Interactively add a new database entry with optional secret linking.

psi dbs add

Options:

  • --yes - Skip interactive prompts
  • --name <name> - Database name
  • --description <desc> - Description
  • --path <path> - Database path
  • --s3-cred <name> - Vault secret name for S3 credentials
  • --encryption-key <name> - Vault secret name for encryption key
  • --geocoding-key <name> - Vault secret name for geocoding API key

dbs view (alias: dbs v)

Show all fields of a database entry. If neither --name nor --path is given, an interactive prompt lists all configured databases to choose from. Name lookup is case-insensitive.

psi dbs view
psi dbs v --name my-photos
psi dbs view --path /data/photos

dbs edit (alias: dbs e)

Edit fields of a database entry with current values pre-populated. If --name is omitted, an interactive prompt lists all configured databases to choose from.

psi dbs edit
psi dbs e --name my-photos
psi dbs edit --name my-photos --yes --new-name renamed
psi dbs edit --name my-photos --yes --description "Updated description"
psi dbs edit --name my-photos --yes --path /new/path

Options:

  • --yes - Skip interactive prompts (requires --name)
  • --name <name> - Database name to edit (identifier)
  • --new-name <name> - New database name
  • --description <desc> - New description
  • --path <path> - New database path
  • --s3-cred <name> - Vault secret name for S3 credentials
  • --encryption-key <name> - Vault secret name for encryption key
  • --geocoding-key <name> - Vault secret name for geocoding API key

dbs remove

Remove a database entry from the list (does not delete database files). If neither --name nor --path is given, an interactive prompt lists all configured databases to choose from.

psi dbs remove
psi dbs remove --name my-photos
psi dbs remove --path /data/photos
psi dbs remove --name my-photos --yes   # skip confirmation

Options:

  • --yes - Skip confirmation prompt
  • --name <name> - Database name
  • --path <path> - Database path

dbs clear

Remove all database entries from the list (does not delete database files).

psi dbs clear

dbs send

Share a database configuration (with resolved secrets) to another device over the LAN.

psi dbs send
psi dbs send --name my-photos
psi dbs send --path /data/photos

If neither --name nor --path is given, an interactive prompt lists all configured databases to choose from. You can review and edit the database fields and choose which linked secrets to include before sending. A security warning is displayed before proceeding.

The command searches for a receiver on the LAN (60-second timeout, Ctrl+C to cancel). When a receiver is found, you enter the 4-digit pairing code shown on the receiver's screen.

See Sharing-Credentials for details on the security architecture.

dbs receive

Receive a database configuration from another device over the LAN.

psi dbs receive

Starts a receiver, generates and displays a 4-digit pairing code, and waits for a sender (60-second timeout, Ctrl+C to cancel). When a sender delivers the payload, you can review and edit the name, description, path, and choose which secrets to import before saving.

If an incoming secret name already exists in your vault, you will be prompted to resolve the conflict: reuse the existing secret, replace it with the incoming one, or save the incoming one under a new name. In non-interactive mode (--yes), conflicts are resolved by reusing the existing secret.

See Sharing-Credentials for details on the security architecture.

Automatic Secret Resolution: When --db is used with any command, Photosphere checks databases.toml for a matching entry (by path or by name). If found, linked secrets are auto-resolved, no need for separate --key or S3 config flags.

# Register a database
psi dbs add
# Then use it by name, secrets are auto-resolved
psi summary --db my-photos
psi add --db my-photos ~/new-pics

decrypt - Decrypt Database in Place

Purpose: Decrypt the database at --db in place. Reads the encrypted database, rewrites all files as plain, and removes .db/encryption.pub. There is no destination path.

Usage:

psi decrypt [options]

Options:

  • --db <path> - Database directory to decrypt (defaults to current directory)
  • -k, --key <keyfile> - Key path(s) for reading the encrypted database; comma-separated list
  • -v, --verbose - Enables verbose logging
  • -y, --yes - Non-interactive mode (required for scripted use)

Examples:

psi decrypt --db ~/encrypted-photos --key my-photos.key --yes
psi decrypt --db ~/encrypted --key key1.key,key2.key --yes

Exit Codes:

  • 0 - Decrypt completed successfully
  • 1 - Decrypt failed (missing key, I/O error, etc.)

encrypt - Encrypt or Re-encrypt Database in Place

Purpose: Encrypt or re-encrypt the database at --db in place. Use for: (1) plain database → encrypted, (2) re-encrypt an already encrypted database with a new default key, or (3) rewrite an already encrypted database with the same key list to convert files to the current format. The new public key is written to .db/encryption.pub only after the entire database has been re-encrypted. There is no destination path.

Usage:

psi encrypt [options]

Options:

  • --db <path> - Database directory to encrypt or re-encrypt (defaults to current directory)
  • -k, --key <keyfile> - Key path(s); comma-separated; first key is the default write key and legacy-read key, all keys are available for reading current-format files
  • -g, --generate-key - Generate key(s) if they don't exist
  • -v, --verbose - Enables verbose logging
  • -y, --yes - Non-interactive mode (required for scripted use)

Examples:

# Plain database → encrypted (in place)
psi encrypt --db ~/photos --key my.key --generate-key --yes

# Re-encrypt with a new key (in place)
psi encrypt --db ~/photos --key new.key,old.key --yes

# Rewrite in place using the same key
psi encrypt --db ~/photos --key my.key --yes

Exit Codes:

  • 0 - Encrypt completed successfully
  • 1 - Encrypt failed (key mismatch, I/O error, etc.)

examples - Show Usage Examples

Purpose: Display usage examples for all CLI commands categorized by command type.

Usage:

psi examples [options]

Options:

  • -y, --yes - Non-interactive mode (use command line arguments and defaults)

Examples:

psi examples

export (alias: exp) - Export Asset by ID

Purpose: Export a specific asset from the database by its unique ID to a specified path. Supports exporting original files, display versions, or thumbnails.

Usage:

psi export <asset-id> <output-path> [options]  # or psi exp <asset-id> <output-path> [options]

Arguments:

  • <asset-id> - The unique ID of the asset to export (required)
  • <output-path> - The path where the asset should be exported (required)

Options:

  • --db <path> - The directory containing the media file database (defaults to current directory)
  • -k, --key <keyfile> - Path to the private key file for encryption
  • -t, --type <type> - Type of asset to export: original, display, or thumb (default: original)
  • -v, --verbose - Enables verbose logging
  • -y, --yes - Non-interactive mode (use command line arguments and defaults)

Asset Types:

  • original - The original uploaded file (default)
  • display - Web-optimized version for viewing
  • thumb - Thumbnail version for previews

Examples:

# Export original asset to specific file
psi export --db ~/photos abc123-def4-5678-9012-345678901234 ./exported-photo.jpg

# Export original asset to directory (keeps original filename)
psi export --db ~/photos abc123-def4-5678-9012-345678901234 ./exports/

# Export display version
psi export --db ~/photos xyz789-abc1-2345-6789-012345678901 ~/Downloads/my-photo.jpg --type display

# Export thumbnail to directory (creates filename_thumb.jpg)
psi export --db ~/photos abc123-def4-5678-9012-345678901234 ./thumbs/ --type thumb

# Export from encrypted database
psi export --db ~/photos abc123-def4-5678-9012-345678901234 ./output.jpg --key my-key.pem

Output Behavior:

  • File destination: If output path is a file, exports directly to that location
  • Directory destination: If output path is a directory:
    • original type: Uses original filename
    • display/thumb types: Adds suffix to filename (e.g., photo_display.jpg, photo_thumb.jpg)

Finding Asset IDs: Asset IDs can be found through:

  • The web UI (in asset details)
  • Database queries via API
  • The psi list command

Exit Codes:

  • 0 - Export completed successfully
  • 1 - Export failed (asset not found, storage error, etc.)

hash - Compute File Hash

Purpose: Compute the hash of a file using the same algorithm as the database. Useful for verifying file integrity or checking whether a file matches a known hash value.

Usage:

psi hash <file-path> [options]

Arguments:

  • <file-path> - Path to the file to hash (supports local filesystem, s3: URIs, and encrypted storage)

Options:

  • -k, --key <keyfile> - Path to the private key file for encrypted storage
  • -v, --verbose - Enables verbose logging (shows storage type and normalized path)
  • -y, --yes - Non-interactive mode

Examples:

psi hash photo.jpg
psi hash s3:my-bucket/photos/photo.jpg
psi hash encrypted-photo.jpg --key my-photos.key

Output Information:

  • File - The file path
  • Hash - Hex-encoded hash of the file contents
  • Date - Last modified timestamp
  • Size - File size in bytes

info (alias: inf) - Analyze Media Files

Purpose: Display detailed information about media files including EXIF data, metadata, and technical specifications.

Usage:

psi info <files...> [options]  # or psi inf <files...> [options]

Arguments:

  • <files...> - File path(s), asset ID(s), or hash(es) to analyze (required). When looking up by asset ID or hash, --db is required.

Options:

  • --db <path> - The directory containing the media file database (only needed for asset ID or hash lookups)
  • --tools - Enables output from media processing tools (ImageMagick, ffmpeg, etc.)
  • --cwd <path> - Override the current working directory
  • -v, --verbose - Enables verbose logging
  • -y, --yes - Non-interactive mode (use command line arguments and defaults)

Examples:

psi info photo.jpg video.mp4
psi info /path/to/media/* --verbose

Output Information: For each file, displays:

  • File path and database status (✓ In database / ○ Not in database)
  • Media type (IMAGE/VIDEO)
  • Dimensions (width × height for images/videos)
  • Duration (MM:SS format for videos)
  • Date taken (from EXIF data)
  • GPS coordinates (if available)
  • Frame rate (for videos)
  • Audio presence (for videos)

init (alias: i) - Initialize Database

Purpose: Creates a new Photosphere media file database.

Usage:

psi init [options]  # or psi i [options]

Options:

  • --db <path> - The directory that will contain the media file database (defaults to current directory)
  • -g, --generate-key - Generate encryption keys if they don't exist
  • -k, --key <keyfile> - Path to the private key file for encryption
  • --tools - Enables output from media processing tools (ImageMagick, ffmpeg, etc.)
  • --session-id <id> - Session ID for tracking progress
  • -v, --verbose - Enables verbose logging
  • -y, --yes - Non-interactive mode (use command line arguments and defaults)

Example:

psi init --db ~/photos
psi init --db ~/photos --generate-key --verbose

list (aliases: ls, l) - List Database Files

Purpose: List all files in the database sorted by date (newest first) with interactive pagination. Provides an easy way to browse database contents and find asset IDs.

Usage:

psi list [options]  # or psi ls [options]  or psi l [options]

Options:

  • --db <path> - The directory containing the media file database (defaults to current directory)
  • -k, --key <keyfile> - Path to the private key file for encryption
  • --page-size <size> - Number of files to display per page (default: 20)
  • -v, --verbose - Enables verbose logging
  • -y, --yes - Non-interactive mode (use command line arguments and defaults)

Examples:

psi list --db .
psi list --db ~/photos
psi list --db ~/photos --page-size 10

Interactive Controls:

  • Enter - Show next page of results
  • Escape - Exit the list view
  • Ctrl+C - Exit the list view

Output Information: For each file, displays:

  • Asset ID (for use with export and other commands)
  • Original filename
  • Date taken (from metadata, newest first)
  • File size (if available)
  • Content type (image/jpeg, video/mp4, etc.)
  • Dimensions (width × height for images/videos)
  • Original path (where the file was imported from)

Usage Notes:

  • Files are automatically sorted by photo date in descending order (newest first)
  • Use the asset IDs shown in the output with the psi export command
  • Page size can be adjusted for better viewing on different terminal sizes
  • Works with encrypted databases when provided with the appropriate key

origin - Show Origin Database

Purpose: Display the origin database path stored in the database config (.db/config.json). The origin is used as the default destination for sync, replicate, repair, and compare when --dest is not provided.

Usage:

psi origin [options]

Options:

  • --db <path> - The directory containing the media file database (defaults to current directory)
  • -k, --key <keyfile> - Path to the private key file for encryption
  • -v, --verbose - Enables verbose logging
  • -y, --yes - Non-interactive mode (use command line arguments and defaults)

Examples:

psi origin --db ~/photos
psi origin --db .

Output: Prints the origin path, or (not set) if no origin has been configured.

remove (alias: rm) - Remove Asset by ID

Purpose: Remove a specific asset from the database by its unique ID. This command deletes the asset files (original, display, thumbnail) from storage and marks them as deleted in the merkle tree.

Usage:

psi remove <asset-id> [options]  # or psi rm <asset-id> [options]

Arguments:

  • <asset-id> - The unique ID of the asset to remove (required)

Options:

  • --db <path> - The directory containing the media file database (defaults to current directory)
  • -k, --key <keyfile> - Path to the private key file for encryption
  • -v, --verbose - Enables verbose logging
  • -y, --yes - Non-interactive mode (use command line arguments and defaults)

Examples:

# Remove asset from database
psi remove --db ~/photos a1b2c3d4-e5f6-7890-abcd-ef1234567890

# Remove asset from current directory database
psi remove --db . f1e2d3c4-b5a6-7890-cdef-ab1234567890

# Remove asset with verbose output
psi remove --db ~/photos 12345678-9abc-def0-1234-567890abcdef --verbose

# Remove asset from encrypted database
psi remove --db ~/photos a1b2c3d4-e5f6-7890-abcd-ef1234567890 --key my-key.pem

What Gets Removed:

  • Original file - The original uploaded asset
  • Display file - Web-optimized version (if exists)
  • Thumbnail file - Thumbnail version (if exists)
  • Metadata file - BSON metadata file
  • Database entry - Asset record from metadata collection

Merkle Tree Updates:

  • All removed files are marked as deleted in the merkle tree
  • Tree integrity is maintained for verification and synchronization
  • Deleted entries remain in the tree for audit trail purposes

Finding Asset IDs: Asset IDs can be found through:

  • The web UI (in asset details)
  • The psi list command
  • Database queries via API

Safety Notes:

  • Irreversible operation - Removed assets cannot be recovered unless restored from backup
  • No confirmation prompt - The command executes immediately
  • Backup recommended - Consider using psi replicate to create backups before removal

Exit Codes:

  • 0 - Removal completed successfully
  • 1 - Removal failed (asset not found, storage error, etc.)

repair - Database Repair

Purpose: Repair database integrity by restoring corrupted or missing files from a source database. This command can fix issues detected by the verify command.

Usage:

psi repair [options]

Options:

  • --db <path> - The directory containing the media file database to repair (defaults to current directory)
  • --source <path> - The source database directory to repair from (required)
  • -k, --key <keyfile> - Path to the private key file for encryption
  • --sk, --source-key <keyfile> - Path to source encryption key file
  • --full - Force full verification (bypass cached hash optimization)
  • -v, --verbose - Enables verbose logging
  • -y, --yes - Non-interactive mode (use command line arguments and defaults)

Examples:

# Repair corrupted files from a backup database
psi repair --db ~/photos --source ~/backup/photos

# Force full repair verification of all files
psi repair --db ~/photos --source ~/backup/photos --full


# Repair with encryption keys
psi repair --db ~/photos --source ~/backup/photos --key target.key --source-key backup.key

Repair Process: The repair command will:

  1. Compare files between target and source databases
  2. Detect missing files and restore them from source
  3. Identify corrupted files (using hash comparison) and replace them
  4. Verify repairs by computing hashes of restored files
  5. Update metadata to reflect repaired state

Output Information:

  • Files processed - Total number of files checked
  • Unmodified - Files that were already correct
  • Modified - Files that had metadata changes but correct content
  • New - Files found in target but not tracked in database
  • Removed - Files missing from target storage
  • Repaired - Files successfully restored from source
  • Unrepaired - Files that could not be repaired

Prerequisites:

  • Source database must be accessible and contain the files to restore
  • Source database should be verified as intact before using for repair
  • Both databases should have compatible structure and metadata

Exit Codes:

  • 0 - Repair completed successfully
  • 1 - Repair failed or had errors

replicate (alias: rep) - Database Replication

Purpose: Replicate an media file database from source to destination location with incremental sync capabilities.

Usage:

psi replicate [options]  # or psi rep [options]

Options:

  • --db <path> - Source database directory (defaults to current directory)
  • --dest <path> - Destination directory for replicated database (required)
  • --partial - Create a partial replica (see below)
  • --full - Force full replication (opposite of --partial)
  • -p, --path <path> - Replicate only files matching this path
  • --force - Skip confirmation and allow mismatched database IDs
  • -k, --key <keyfile> - Path to source encryption key file
  • --dk, --dest-key <keyfile> - Path to destination encryption key file
  • -g, --generate-key - Generate encryption keys if they don't exist
  • --tools - Enables output from media processing tools (ImageMagick, ffmpeg, etc.)
  • -v, --verbose - Enables verbose logging
  • -y, --yes - Non-interactive mode (use command line arguments and defaults)

Examples:

psi replicate --db ~/photos --dest ~/backup/photos
psi replicate --db ~/photos --dest s3:backup-bucket/photos
psi replicate --db s3:source-bucket/photos --dest ~/local-backup
psi replicate --db ~/photos --dest ~/backup --key source.key --dest-key backup.key
psi replicate --db ~/photos --dest ~/backup --generate-key
psi replicate --db ~/photos --dest ~/local-cache --partial

Partial replication (--partial):

A partial replica stores only the database's structural files (Merkle trees and sort-index metadata), it does not copy asset, display, or thumb files, and does not copy shard data. This makes the initial copy very fast and keeps the destination's disk footprint minimal.

When the backend serves a partial database, any missing file is fetched transparently from the origin (the source path stored in .db/config.json) and cached locally on first access. From the GUI's perspective the database behaves identically to a full one, photos load as they are viewed, without any manual intervention.

To later convert a partial replica into a full one, run a normal replicate in the opposite direction:

psi replicate --db ~/photos --dest ~/local-cache   # fills in all missing files

See Database-Format §7 for a detailed description of the lazy-pull mechanism.

Exit Codes:

  • 0 - Replication completed successfully
  • 1 - Replication failed or had errors

root-hash - Show Root Hash

Purpose: Print the aggregate root hash of the database. The root hash is a single hash that summarises the entire contents of the merkle tree; it changes whenever any file is added, removed, or modified.

Usage:

psi root-hash [options]

Options:

  • --db <path> - The directory containing the media file database (defaults to current directory)
  • -k, --key <keyfile> - Path to the private key file for encryption
  • -v, --verbose - Enables verbose logging
  • -y, --yes - Non-interactive mode (use command line arguments and defaults)

Examples:

psi root-hash --db ~/photos
psi root-hash --db .

Output: Prints the root hash hex string to stdout. You can compare this value between two databases (e.g. using psi compare) to quickly determine whether they are identical.

set-origin - Set Origin Database

Purpose: Set the origin database path in the database config (.db/config.json). Once set, commands like sync, replicate, repair, and compare will use this path as the default --dest when none is provided.

Usage:

psi set-origin <path> [options]

Arguments:

  • <path> - Path or URI of the origin database (required)

Options:

  • --db <path> - The directory containing the media file database (defaults to current directory)
  • -k, --key <keyfile> - Path to the private key file for encryption
  • -v, --verbose - Enables verbose logging
  • -y, --yes - Non-interactive mode (use command line arguments and defaults)

Examples:

psi set-origin ~/backup/photos --db ~/photos
psi set-origin s3:my-bucket/photos --db ~/photos

summary (alias: sum) - Database Summary

Purpose: Display a summary of the Photosphere media file database including total files, size, and tree hash.

Usage:

psi summary [options]  # or psi sum [options]

Options:

  • --db <path> - The directory containing the media file database (defaults to current directory)
  • -k, --key <keyfile> - Path to the private key file for encryption
  • -v, --verbose - Enables verbose logging
  • -y, --yes - Non-interactive mode (use command line arguments and defaults)

Examples:

psi summary --db .
psi summary --db ~/photos
psi summary --db ~/photos --verbose

sync - Database Synchronization

Purpose: Synchronize changes between two databases. Unlike replicate (which is one-directional), sync transfers changes in both directions so that both databases end up with the same content.

Usage:

psi sync [options]

Options:

  • --db <path> - Source database directory (defaults to current directory)
  • --dest <path> - Destination database directory (defaults to the origin set via psi set-origin)
  • -k, --key <keyfile> - Path to source encryption key file
  • --dk, --dest-key <keyfile> - Path to destination encryption key file
  • -v, --verbose - Enables verbose logging
  • -y, --yes - Non-interactive mode (use command line arguments and defaults)

Examples:

psi sync --db ./photos --dest ./backup
psi sync --db . --dest s3:bucket/photos
psi sync --db ~/photos --dest ~/backup --key source.key --dest-key backup.key

How it differs from replicate:

  • replicate copies files one-way from source to destination.
  • sync transfers changes bidirectionally so both databases end up with the same content.

Origin default: If --dest is omitted, sync uses the origin path stored in the database config (set via psi set-origin). If no origin is configured, you will be prompted to choose a destination interactively.

Exit Codes:

  • 0 - Sync completed successfully
  • 1 - Sync failed or had errors

tools - Check Required Tools

Purpose: Check the status of all required media processing tools (ImageMagick, ffmpeg, ffprobe).

Usage:

psi tools [options]

Options:

  • -y, --yes - Non-interactive mode (use command line arguments and defaults)

Examples:

psi tools

Output Information:

  • ImageMagick: Status and version information
  • FFmpeg: Status and version information
  • FFprobe: Status and version information
  • Installation prompts: Guidance for installing missing tools

upgrade - Upgrade Database

Purpose: Upgrade a Photosphere media file database to the latest format. Run this after updating psi if you have a database created with an older version.

Usage:

psi upgrade [options]

Options:

  • --db <path> - The directory containing the media file database (defaults to current directory)
  • -k, --key <keyfile> - Path to the private key file for encryption
  • -v, --verbose - Enables verbose logging
  • -y, --yes - Non-interactive mode (skip confirmation prompt)

Examples:

psi upgrade --db ~/photos
psi upgrade --db ~/photos --key my-photos.key
psi upgrade --db ~/photos --yes

What it does: The upgrade command migrates the database from an older format to the current version. This may include:

  • Reorganizing file layouts (e.g. moving files between directories)
  • Rebuilding the merkle tree in the current format
  • Migrating metadata to the current BSON structure
  • Encrypting .db/ metadata files if the database is encrypted

You will be shown the current and target database versions and asked to confirm before any changes are made (unless --yes is given). It is strongly recommended to back up your database before upgrading.

Exit Codes:

  • 0 - Upgrade completed successfully (or database was already up to date)
  • 1 - Upgrade failed

secrets (aliases: sec, s) - Secret Management

Purpose: Manage secrets stored in the Photosphere secrets store. By default secrets are stored in the OS keychain; plain-text JSON files under ~/.config/photosphere/vault/ are used only when PHOTOSPHERE_VAULT_TYPE=plaintext is set. Secrets are used to store encryption keys, S3 credentials, API keys, and other sensitive data.

secrets add

Interactively add a new secret.

psi secrets add

Options:

  • --name <name> - Secret name
  • --type <type> - Secret type
  • --value <value> - Secret value
  • --yes - Skip interactive prompts

secrets list (aliases: secrets l, secrets ls)

List all secrets (values are masked).

psi secrets list
psi secrets l
psi sec ls

secrets view (alias: secrets v)

Show the full value of a named secret (with confirmation prompt). If --name is omitted, an interactive prompt lists all secrets to choose from.

psi secrets view
psi secrets v --name abc12345

secrets edit (alias: secrets e)

Edit an existing secret's name or value. If --name is omitted, an interactive prompt lists all secrets to choose from.

psi secrets edit
psi secrets e --name abc12345
psi secrets edit --name abc12345 --yes --new-name new-label
psi secrets edit --name abc12345 --yes --value new-value

Options:

  • --yes - Skip interactive prompts (requires --name and --new-name or --value)
  • --name <name> - Secret name to edit (identifier)
  • --new-name <name> - New secret name
  • --value <value> - New secret value
  • --value-file <path> - Read the new secret value from a file

secrets remove

Remove a named secret (with confirmation prompt). If --name is omitted, an interactive prompt lists all secrets to choose from.

psi secrets remove
psi secrets remove --name old-key

secrets clear

Remove all secrets from the vault.

psi secrets clear

secrets import

Import a PEM private key as an encryption key secret. The secret name is taken from the file name with any .key suffix stripped. The public key is always derived from the private key.

psi secrets import
psi secrets import --yes --private-key /path/to/key.key
Option Description
--private-key <path> Path to the PEM private key file (.key)
--yes Skip interactive prompts (requires --private-key)

secrets send

Share a secret to another device over the LAN.

psi secrets send
psi secrets send --name abc12345

If --name is omitted, an interactive prompt lists all vault secrets to choose from. A security warning is displayed before proceeding.

The command searches for a receiver on the LAN (60-second timeout, Ctrl+C to cancel). When a receiver is found, you enter the 4-digit pairing code shown on the receiver's screen.

See Sharing-Credentials for details on the security architecture.

secrets receive

Receive a secret from another device over the LAN.

psi secrets receive

Starts a receiver, generates and displays a 4-digit pairing code, and waits for a sender (60-second timeout, Ctrl+C to cancel). When a sender delivers the payload, you can review the secret type and edit the name before saving.

See Sharing-Credentials for details on the security architecture.

Secret Naming Conventions:

  • All secrets use plain, user-chosen names; there are no auto-generated IDs. When a secret is created inline through psi dbs add or the desktop database form, its name is inferred from the database name and secret type: <dbname>:s3, <dbname>:encryption, or <dbname>:geocoding. You are prompted for an alternative only if the inferred name is already taken.

Name lookup: When a secret name is not found, the CLI displays fuzzy-matched suggestions (e.g. Did you mean: my-photo, my-photos-old?) to help correct typos.

verify (alias: ver) - Database Verification

Purpose: Verify the integrity of the Photosphere media file database by checking file hashes against cached values.

Usage:

psi verify [options]  # or psi ver [options]

Options:

  • --db <path> - The directory containing the media file database (defaults to current directory)
  • --full - Force full verification (bypass cached hash optimization)
  • -p, --path <path> - Verify only files matching this path
  • --workers <number> - Number of parallel workers
  • --timeout <ms> - Timeout in milliseconds
  • --cwd <path> - Override the current working directory
  • -k, --key <keyfile> - Path to the private key file for encryption
  • --tools - Enables output from media processing tools (ImageMagick, ffmpeg, etc.)
  • -v, --verbose - Enables verbose logging
  • -y, --yes - Non-interactive mode (use command line arguments and defaults)

Examples:

psi verify --db .
psi verify --db ~/photos
psi verify --db ~/photos --full

Exit Codes:

  • 0 - Verification completed successfully
  • 1 - Verification failed or errors encountered

hash-cache - Show Hash Cache Info

Purpose: Display information about the local hash cache.

Usage:

psi hash-cache [options]

Options:

  • -v, --verbose - Enables verbose logging
  • -y, --yes - Non-interactive mode

mcp - Start MCP Server

Purpose: Start an MCP (Model Context Protocol) server over stdio so Claude-compatible clients can access your databases. The server starts with no database open; the client selects one at runtime via the list_databases and open_database tools (there is no --db flag). See Claude-Integration.

Usage:

psi mcp [options]

Options:

  • --cwd <path> - Override the current working directory
  • -v, --verbose - Enables verbose logging
  • -y, --yes - Non-interactive mode

news - Show News and Updates

Purpose: Display the latest update notification and all news items for Photosphere.

Usage:

psi news [options]

Options:

  • -v, --verbose - Enables verbose logging
  • -y, --yes - Non-interactive mode

version - Show Version Information

Purpose: Display version information for psi and its dependencies, including the database format version, build details, dependency versions (ImageMagick, ffmpeg, ffprobe), and relevant directory paths.

Usage:

psi version

Examples:

psi version

Output Information:

  • Photosphere version - The psi CLI version
  • Database version - The current database format version
  • Commit / Build date / Type - Build metadata (when running a released build)
  • Dependencies - Versions of ImageMagick, ffmpeg, and ffprobe (or "Not found" if missing)
  • Directories - Paths to the config directory, keys directory, temp directory, log files, and hash cache
Add a custom footer
Add a custom sidebar

Clone this wiki locally