Getting Started - ashleydavis/photosphere GitHub Wiki
The Photosphere CLI (psi
) is a command-line tool for managing your media file database.
Installation
Get the latest release from GitHub:
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 [email protected]: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
With encryption:
psi init --key ~/my-key --generate-key
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 compares file lengths, modification times and ultimately file hashes to detect any changes since the files were added.
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 backup matches the original:
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. Launch the Web UI
View and manage your media through a local version of the web interface:
psi ui
The UI will automatically open in your default browser. Use --no-open
to prevent auto-opening.
10. 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: Asset IDs can be found through the web UI when viewing asset details, or using psi list
.
Database Structure
Photosphere organizes your media into:
- Original files: Full resolution originals
- Display versions: Web-optimized versions
- Thumbnails: Small preview images
- Metadata: EXIF data, timestamps, and custom tags
The database directory structure:
my-photos/
├── .db/ # Database metadata
├── assets/ # Original media files
├── display/ # Optimized versions
├── thumb/ # Thumbnails
└── metadata/ # BSON metadata for media files.
Encryption
To protect your media with encryption:
-
Generate a key on first init:
psi init --key ~/my-key --generate-key
-
Use the same key for all operations:
psi add ~/new-photos/ --key ~/my-key.pem psi ui --key ~/my-key.pem psi export abc123-def4-5678-9012-345678901234 ./output.jpg --key ~/my-key.pem
-
Encrypt on replication:
psi replicate --key ~/my-key --generate-key --dest s3:my-bucket/my-photos
If you use encryption please don't lose your encryption key. If you lose it you lose access to your encrypted database.
My advice: As soon as you generate a key store it safely in your password manager.
Cloud Storage (S3)
Photosphere supports S3-compatible storage for both local and cloud deployments. You can use AWS S3, DigitalOcean Spaces, MinIO, or any S3-compatible service.
For detailed instructions on setting up Digital Ocean Spaces, see Configuration-Digital-Ocean-Spaces.
Configuring S3 Credentials
Use the config
command to set up your AWS credentials and set your Google API key for reverse geocoding:
# Configure credentials
psi config
You can also set AWS credentials using environment variables:
export AWS_ACCESS_KEY_ID=<your-access-key-id>
export AWS_SECRET_ACCESS_KEY=<your-secret-key>
export AWS_DEFAULT_REGION=us-east-1 # Set this to us-east-1 for Digital Ocean.
export AWS_ENDPOINT=https://syd1.digitaloceanspaces.com # If using Digital Ocean, replace with the endpoint for your DO data center.
Authentication Setup
When running Photosphere as a server, you can configure Auth0 for user authentication. For detailed instructions on setting up Auth0 and configuring the necessary environment variables, see Configuration-Auth0.
Using S3 Storage
Once configured, you can use S3 paths directly in commands:
# Replicate a local database to S3
psi replicate --db my-photos --dest s3:my-bucket/photos
# Initialize an empty database in S3
psi init --db s3:my-bucket/photos
# Add files to S3-backed database
psi add --db s3:my-bucket/photos ~/Pictures/*.jpg
# Launch UI for S3 database
psi ui --db s3:my-bucket/photos
Clearing Configuration
To remove all configuration files:
psi config --clear
This will prompt for confirmation before deleting all credential files.