Configuration CLI

This guide covers all configuration options available for the Photosphere CLI tool

Environment Variables

S3/AWS Configuration

Variable	Description	Example
AWS_ACCESS_KEY_ID	S3 access key ID	AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY	S3 secret access key	wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_REGION	S3 region	us-east-1
AWS_ENDPOINT	S3 endpoint URL (for non-AWS S3)	https://nyc3.digitaloceanspaces.com
S3_PROFILE	Select S3 profile to use	production

Other Environment Variables

Variable	Description	Default
PSI_ENCRYPTION_KEY	Encryption key for database access — a file path to a PEM key file or a vault secret name. Equivalent to passing -k on every command. Overridden by an explicit -k flag.	None
GOOGLE_API_KEY	Google API key for reverse geocoding	None

See Environment-Variables for the full list of supported environment variables.

Storage Connection Strings

The CLI supports multiple storage backends:

Type	Format	Example
Filesystem	fs:path/to/directory	fs:/var/photosphere/data
Filesystem (implicit)	path/to/directory	./my-photos
S3-compatible	s3:bucket-name/path	s3:my-bucket/photos

Encryption Keys

Encryption keys protect Photosphere databases. Pass them via the --key, --dest-key, or --source-key options, or set PSI_ENCRYPTION_KEY to avoid repeating -k on every command.

Key sources

Each key entry is resolved in order — whichever matches first wins:

1. File path — an absolute or relative path to a PEM key file (e.g. --key /path/to/my-photos.key)
2. Vault secret name — a named secret stored in the Photosphere vault (e.g. --key my-photos)

Multiple keys (comma-separated list)

All key options accept a comma-separated list:

--key key1.key,key2.key,key3.key

• The first key is the default key — used for writing new encrypted data and for reading legacy-format files.
• All keys are registered by their public-key hash so files encrypted with different keys in the same database can all be read.

See Encryption for full details on how encryption works and how to use psi encrypt / psi decrypt.

Related Configuration

• Configuration-Desktop - Desktop app config file (~/.config/photosphere/desktop.json) for UI preferences and recent items.
• Configuration-Digital-Ocean-Spaces - Digital Ocean Spaces setup for S3-compatible storage