Skip to content

Command Reference

Jump to bottom Edit New page
Ashley Davis edited this page Mar 12, 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 <path> - The directory that contains 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(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

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

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

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

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)

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

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

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)
  • -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

Exit Codes:

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

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)

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.)

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)

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.)

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.)

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

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

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

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

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

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

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