Getting Started CLI

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

Installation

Get the latest release from GitHub:

• https://github.com/ashleydavis/photosphere/releases

Find the latest numbered version or if you are feeling lucky find the latest nightly build.

Download the appropriate tar or zip for your platform, unpack it and put the psi executable in your path:

• Linux: psi
• Windows: psi.exe
• macOS: psi

Set permissions

Important: After downloading, make sure the binary has execute permissions:

# On Linux/macOS
chmod +x psi

# Verify permissions
ls -la psi

The binary should show execute permissions like -rwxr-xr-x for the user.

macOS Additional Step: If you encounter "cannot be opened because the developer cannot be verified" or similar security warnings, you need to remove the quarantine attributes that macOS adds to downloaded files:

# Remove quarantine attributes on macOS
xattr -c ./psi

This is required because macOS Gatekeeper automatically quarantines downloaded binaries that aren't code-signed by a registered Apple developer. The xattr -c command removes these extended attributes, allowing the binary to run normally. This is safe for trusted binaries like the Photosphere CLI.

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

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.

Cloud Storage (S3)

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