Installation

Prerequisites

Before installing Photosphere CLI, you need to install the required media processing tools:

1. Install FFmpeg

FFmpeg is required for video processing and metadata extraction.

Windows:

• Download from https://ffmpeg.org/download.html#build-windows
• Extract to a folder (e.g., C:\ffmpeg)
• Add C:\ffmpeg\bin to your PATH environment variable

macOS:

# Using Homebrew (recommended)
brew install ffmpeg

# Using MacPorts
sudo port install ffmpeg

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install ffmpeg

Linux (CentOS/RHEL/Fedora):

# Fedora
sudo dnf install ffmpeg

# CentOS/RHEL (enable EPEL repository first)
sudo yum install epel-release
sudo yum install ffmpeg

2. Install ImageMagick

ImageMagick is required for image processing and thumbnail generation.

Windows:

• Download from https://imagemagick.org/script/download.php#windows
• Run the installer and ensure "Install development headers and libraries for C and C++" is checked
• Make sure ImageMagick is added to your PATH

macOS:

# Using Homebrew (recommended)
brew install imagemagick

# Using MacPorts
sudo port install ImageMagick

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install imagemagick

Linux (CentOS/RHEL/Fedora):

# Fedora
sudo dnf install ImageMagick

# CentOS/RHEL
sudo yum install ImageMagick

3. Verify Installation

Check that both tools are installed and accessible:

ffmpeg -version
ffprobe -version
magick -version
# or on older systems:
convert -version

All commands should return version information without errors.

Install Photosphere CLI

Step 1: Download

1. Go to the Photosphere releases page
2. Download the appropriate binary for your platform:
   • Linux: psi-linux-x64 or psi-linux-arm64
   • Windows: psi-windows-x64.exe
   • macOS: psi-macos-x64 or psi-macos-arm64

Step 2: Make Executable (Linux/macOS)

After downloading, you need to make the binary executable:

# Rename for convenience (optional)
mv psi-linux-x64 psi        # Linux
mv psi-macos-x64 psi        # macOS

# Make executable
chmod +x psi

# Verify permissions
ls -la psi

You should see permissions like -rwxr-xr-x.

Step 3: Remove Quarantine (macOS Only)

macOS blocks unsigned binaries by default. Remove the quarantine attribute:

xattr -c ./psi

This is safe for trusted software like Photosphere CLI.

Step 4: Move to PATH (Optional)

For system-wide access, move the binary to a directory in your PATH:

# Linux/macOS
sudo mv psi /usr/local/bin/

# Or create a local bin directory
mkdir -p ~/bin
mv psi ~/bin/
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Windows: Move psi.exe to a folder in your PATH, or add its location to your PATH environment variable.

Verify Installation

Test that everything works:

# Check that Photosphere CLI is working
psi --version

# Verify required tools are detected
psi tools

The psi tools command will check that FFmpeg and ImageMagick are properly installed and accessible.

Quick Start

Now you're ready to use Photosphere CLI:

# Create a new photo database
psi init ~/my-photos

# Add some photos
psi add ~/my-photos ~/Pictures/*.jpg

# Launch the web interface
psi ui ~/my-photos