Skip to content

Command Reference

Jump to bottom Edit New page
Ashley Davis edited this page Apr 20, 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.json (defaults to current directory). When a name is given, the path and linked secrets (S3, encryption, geocoding) are resolved automatically from ~/.config/photosphere/databases.json
  • -m, --meta <db-metadata-dir> - The directory to store media file database metadata (default: <current-dir>/.db)
  • -k, --key <keyfile> - Path(s) to private key file(s) for encryption; comma-separated list (first key is the default/write key). Same for --dest-key and --source-key where used.
  • -v, --verbose - Enables verbose logging
  • -y, --yes - Non-interactive mode (use command line arguments and defaults)

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)
  • -m, --meta <db-metadata-dir> - The directory to store media file database metadata (default: <current-dir>/.db)
  • -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 add --db ~/photos ~/my-photos
psi add --db ~/photos ~/vacation-pics ~/family-photos
psi add --db . /path/to/photos --verbose

bug-report - Generate Bug Report

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

Usage:

psi bug-report [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-report
psi bug-report --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)
  • -m, --meta <db-metadata-dir> - The directory to store media file database metadata (default: <current-dir>/.db)
  • -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 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)
  • -s, --src-meta <dir> - Source metadata directory override
  • -d, --dest-meta <dir> - Destination metadata directory override
  • --sk, --source-key <keyfile> - Source encryption key path(s); comma-separated list
  • --dk, --dest-key <keyfile> - Destination encryption key path(s); comma-separated list
  • -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 --sk source.key --dk backup.key
psi compare --db ~/photos --dest ~/backup --output comparison-report.json

Exit Codes:

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

configure (alias: cfg) - Configure Cloud Storage

Purpose: Configure S3 credentials for cloud storage.

Usage:

psi configure [options]  # or psi cfg [options]

Options:

  • -p, --profile <name> - The profile name to configure (default: "default")
  • -c, --clear - Clear all S3 configuration files
  • -y, --yes - Non-interactive mode

Examples:

psi configure (or psi cfg)
psi configure --profile production (or psi cfg --profile production)
psi configure --clear (or psi cfg --clear)

Post-configuration usage: Once configured, you can use S3 storage paths like:

  • psi replicate --dest s3:my-bucket/photos
  • psi init --db s3:my-bucket/photos
  • psi add --db s3:my-bucket/photos ~/Pictures/ (for non-default profiles, add --profile production)

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 - Database List Management

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

dbs list

List all configured databases (name and path).

psi dbs list

dbs add

Interactively add a new database entry with optional secret linking.

psi dbs add

dbs view <name>

Show all fields of a database entry (looked up by name, case-insensitive).

psi dbs view my-photos

dbs edit <name>

Edit fields of a database entry with current values pre-populated.

psi dbs edit my-photos

dbs remove <name>

Remove a database entry from the list (does not delete database files).

psi dbs remove my-photos
psi dbs remove my-photos --yes   # skip confirmation

Options:

  • --yes - Skip confirmation prompt (for remove)

dbs send [name]

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

psi dbs send
psi dbs send my-photos

If the name is omitted, 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.

See Sharing-Credentials for details on the security architecture.

Automatic Secret Resolution: When --db is used with any command, Photosphere checks databases.json 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

debug hash-cache - Display Hash Cache Information

Purpose: Display information about the local and database hash caches for debugging purposes.

Usage:

psi debug hash-cache [options]

Options:

  • --db <path> - The directory containing the media file database (defaults to current directory)
  • -m, --meta <db-metadata-dir> - The directory to store media file database metadata (default: <current-dir>/.db)
  • -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)
  • -t, --type <type> - Cache type to display: 'local', 'database', or 'both' (default: 'both')

Examples:

psi debug hash-cache --db .
psi debug hash-cache --db . -t local
psi debug hash-cache --db ~/photos -t database

debug merkle-tree - Visualize Merkle Tree

Purpose: Visualize the merkle tree structure of the media file database for debugging purposes.

Usage:

psi debug merkle-tree [options]

Options:

  • --db <path> - The directory containing the media file database (defaults to current directory)
  • -m, --meta <db-metadata-dir> - The directory to store media file database metadata (default: <current-dir>/.db)
  • -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 debug merkle-tree --db .
psi debug merkle-tree --db ~/photos

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)
  • -m, --meta <db-metadata-dir> - The directory to store media file database metadata (default: <current-dir>/.db)
  • -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...> - Media files to analyze (required)

Options:

  • -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
  • -m, --meta <db-metadata-dir> - The directory to store media file database metadata (default: <current-dir>/.db)
  • -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)

Example:

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

list (alias: ls) - 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]

Options:

  • --db <path> - The directory containing the media file database (defaults to current directory)
  • -m, --meta <db-metadata-dir> - The directory to store media file database metadata (default: <current-dir>/.db)
  • -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)
  • -m, --meta <db-metadata-dir> - The directory to store media file database metadata (default: <current-dir>/.db)
  • -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)
  • -m, --meta <db-metadata-dir> - The directory to store media file database metadata (default: <current-dir>/.db)
  • -k, --key <keyfile> - Path to the private key file for encryption
  • -s, --source-meta <dir> - Source metadata directory override
  • --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)
  • -m, --meta <dir> - Source metadata directory override
  • -k, --key <keyfile> - Path to source encryption key file
  • -d, --dest-meta <dir> - Destination metadata directory override
  • --dk, --dest-key <keyfile> - Path to destination encryption key file
  • -g, --generate-key - Generate encryption keys if they don't exist
  • -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)
  • -m, --meta <db-metadata-dir> - The directory to store media file database metadata (default: <current-dir>/.db)
  • -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 - Secret Management

Purpose: Manage secrets stored in the Photosphere secrets store (~/.config/photosphere/vault/). Secrets are stored as plain-text JSON files and are used to store encryption keys, S3 credentials, API keys, and other sensitive data.

secrets add

Interactively add a new secret.

psi secrets add

secrets list

List all secrets (values are masked).

psi secrets list

secrets view <name>

Show the full value of a named secret (with confirmation prompt).

psi secrets view cli:encryption:my-photos
psi secrets view shared:abc12345

secrets edit <name>

Edit an existing secret's value.

psi secrets edit cli:encryption:my-photos

secrets delete <name>

Delete a named secret (with confirmation prompt).

psi secrets delete cli:encryption:old-key

secrets import

Import a .key / .key.pub PEM key pair file.

psi secrets import

secrets send [name]

Share a secret to another device over the LAN.

psi secrets send
psi secrets send shared:abc12345

If the 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:

  • cli:encryption:<name> — Encryption keys created via the CLI
  • cli:s3 — S3 credentials configured via psi configure
  • shared:<id> — Shared secrets linked to database entries (S3, encryption, API keys)

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)
  • -m, --meta <db-metadata-dir> - The directory to store media file database metadata (default: <current-dir>/.db)
  • -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 verify --db .
psi verify --db ~/photos
psi verify --db ~/photos --full
psi verify --db ~/photos --output verification-report.json

Exit Codes:

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

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

Storage Support

The CLI supports multiple storage backends:

  • Local filesystem: Standard file paths
  • S3-compatible storage: s3:bucket-name:/path format
  • Encrypted storage: Works with encryption keys for secure storage

Prerequisites

The CLI automatically checks for required tools (ImageMagick, FFmpeg) and prompts for installation if needed.

Error Handling

  • All commands provide colored output for better readability
  • Progress indicators show real-time status
  • Safe interruption (Ctrl-C) with graceful cleanup
  • Detailed error messages with verbose logging option

Typical Workflow

  1. Initialize a database: psi init --db ~/my-photos (or psi i --db ~/my-photos)
  2. Add media files: psi add --db ~/my-photos ~/source-photos (or psi a --db ~/my-photos ~/source-photos)
  3. View database summary: psi summary --db ~/my-photos (or psi sum --db ~/my-photos)
  4. List database contents: psi list --db ~/my-photos (or psi ls --db ~/my-photos)
  5. Verify database integrity: psi verify --db ~/my-photos (or psi ver --db ~/my-photos)
  6. Create backup/replica: psi replicate --db ~/my-photos --dest ~/backup/photos (or psi rep --db ~/my-photos --dest ~/backup/photos)
  7. Configure cloud storage (optional): psi configure (or psi cfg)
  8. Analyze specific files: psi info photo.jpg (or psi inf photo.jpg)
  9. Export specific assets: psi export --db ~/my-photos <asset-id> ./exports/ (or psi exp --db ~/my-photos <asset-id> ./exports/)
  10. Remove unwanted assets: psi remove --db ~/my-photos <asset-id> (or psi rm --db ~/my-photos <asset-id>)

This CLI provides a complete workflow for managing media databases from initialization through replication, verification, analysis, export, and removal.

Add a custom footer
Add a custom sidebar

Clone this wiki locally