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.

Building from Source

You need to install Bun to build from source code.

# Clone the repository
git clone git@github.com:ashleydavis/photosphere.git
cd photosphere

# Install dependencies
bun install

# Build the CLI tool
cd apps/cli
bun run build-linux   # For Linux
bun run build-win     # For Windows
bun run build-mac     # For macOS

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. Use Enter to see more files or Escape 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.

Cloud Storage (S3)

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