Getting Started CLI

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

Installation

Start here: install the CLI before anything else. See Installation-CLI for download links, the correct binary names, and platform-specific setup steps.

Required Tools

Photosphere requires ImageMagick and FFmpeg to import photos and videos. See the Required-Tools page for platform-specific installation instructions and troubleshooting.

Quick Start

1. Initialize a Database

Create a new Photosphere database in your desired directory:

mkdir my-photos
cd my-photos
psi init

For encrypting your database, see Encryption.

2. Add Media Files

Add photos and videos to your database:

# Add individual files
psi add ~/Pictures/vacation.jpg ~/Videos/birthday.mp4

# Add entire directories
psi add ~/Pictures/2024/

3. View Database Summary

Check a summary of what's in your database:

psi summary

This shows total files, size, and database hash for verification.

4. List Database Contents

Browse the files in your database with interactive pagination:

psi list

This shows all files sorted by date (newest first) with their asset IDs, filenames, dimensions, and other metadata. Press Enter (or any key) to show the next page, and Ctrl+C to exit. The asset IDs shown can be used with the export command.

5. Verify Database Integrity

Check that your files haven't been corrupted or modified:

psi verify

This is the quickest option: it checks file size and timestamp first, and only verifies file content (hashes) if those don't match the expected values.

To rehash and compare every media file against its expected hash:

psi verify --full

This is the longest option: it reads each media file, rehashes the content, and compares against the expected hash for the valid version of the file.

6. Create a Backup

Replicate your database to create a backup:

psi replicate --dest ~/backup/my-photos

This creates an exact copy that can be used for backup or migration.

7. Compare Databases

Verify that your local database matches the replica:

psi compare --dest ~/backup/my-photos

This uses the merkle tree to quickly identify any differences between databases.

8. Repair Database Issues

If files become corrupted or missing, you can repair them from a backup database:

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

# Force full verification and repair
psi repair --source ~/backup/my-photos --full

The repair command will:

• Compare files between your database and the source backup
• Restore any missing files from the backup
• Replace corrupted files with clean versions from the backup
• Verify file integrity after repair

Important: Always create regular backups with psi replicate so you have a clean source to repair from.

9. Export Specific Assets

Export individual assets from your database by their unique ID:

# Export original file
psi export abc123-def4-5678-9012-345678901234 ./exported-photo.jpg

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

# Export web-optimized display version
psi export abc123-def4-5678-9012-345678901234 ./output.jpg --type display

# Export thumbnail version
psi export abc123-def4-5678-9012-345678901234 ./thumbs/ --type thumb

Finding Asset IDs: Use psi list to see asset IDs.

Managing Databases

Register your databases with psi dbs so that commands can reference them by name and auto-resolve linked secrets (S3 credentials, encryption keys, geocoding API keys).

psi dbs add              # register a database interactively
psi dbs list             # list all configured databases
psi summary --db my-photos   # use a database by name (secrets auto-resolved)

See Managing-Databases for full details.

Where to Store Your Database

A Photosphere database can live on your local filesystem or on S3-compatible cloud storage. The recommended setup is:

1. Keep your primary database on your local disk. It is fast and works offline.
2. Replicate it to the cloud (psi replicate --dest s3:...) for an encrypted, off-site backup. Re-run replicate to keep the backup up to date.
3. On space-limited devices, create a partial (lazy) replica (psi replicate --dest ... --partial). It stores only metadata and thumbnails; full-size originals are pulled from the cloud on demand, keeping the on-device footprint small.

flowchart TD
    local[("Local database<br/>(full, primary)")]
    cloud[("Cloud backup<br/>(full, encrypted)")]
    device[("Space-limited device<br/>(partial lazy replica)")]

    local -->|"psi replicate"| cloud
    cloud -->|"psi replicate --partial"| device
    device -.->|"pull originals on demand"| cloud

Loading

Cloud Storage (S3)

For setup and configuration of S3-compatible cloud storage (AWS S3, DigitalOcean Spaces, MinIO, credentials, and usage), see Configuration-Cloud-Storage.