Installation CLI

Installing the Photosphere CLI

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

Prerequisites

Before installing, install the required media processing tools (FFmpeg and ImageMagick). See Required-Tools for platform-specific instructions.

Step 1: Download

1. Go to the Photosphere releases page.
2. Find the latest numbered version (or the latest nightly build).
3. Download the archive for your platform:

Platform	File
Linux (x64)	photosphere-cli-linux-x64.tar.gz
macOS (Apple Silicon)	photosphere-cli-macos-arm64.tar.gz
macOS (Intel)	photosphere-cli-macos-x64.tar.gz
Windows (x64)	photosphere-cli-windows-x64.zip
Windows (x64, older CPUs)	photosphere-cli-windows-x64-baseline.zip

Each archive contains the psi executable (psi.exe on Windows).

Windows baseline build: Use photosphere-cli-windows-x64-baseline.zip only if the standard build fails to start on an older CPU that lacks modern instruction sets. Otherwise use photosphere-cli-windows-x64.zip.

Step 2: Extract

Linux/macOS:

tar -xzf photosphere-cli-linux-x64.tar.gz     # Linux
tar -xzf photosphere-cli-macos-arm64.tar.gz   # macOS Apple Silicon
tar -xzf photosphere-cli-macos-x64.tar.gz     # macOS Intel

Windows: Extract the .zip archive (right-click → Extract All, or use your preferred tool).

Step 3: Make Executable (Linux/macOS)

# Make executable
chmod +x psi

# Verify permissions
ls -la psi

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

Step 4: Remove Quarantine (macOS Only)

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

xattr -c ./psi

Step 5: 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

# Check that the Photosphere CLI is working
psi --version

# Verify required tools are detected
psi tools

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

Next Steps

• Getting-Started-CLI - Detailed guide for using the Photosphere CLI
• Command-Reference - Complete list of CLI commands