Managing Secrets

Photosphere stores sensitive credentials in a secrets vault. By default the vault uses the OS keychain — macOS Keychain, Windows Credential Vault, or the Linux Secret Service (GNOME Keyring / KWallet) — so secret values are protected by the operating system's own credential store rather than plain files on disk.

Secrets are used to store S3 credentials, encryption key pairs, and API keys. They can be linked to database entries so that credentials are resolved automatically when a database is opened.

Secret Types

Type	Description	Fields
S3 credentials	Credentials for S3-compatible object storage	Region, Access Key ID, Secret Access Key, Endpoint (optional)
Encryption key	RSA key pair for encrypting and decrypting databases	Private key PEM, Public key PEM
API key	API keys for external services (e.g. geocoding)	API key value

Each secret also has a human-readable label so you can identify it at a glance.

Vault Types

Photosphere supports two vault backends, selected with the PHOTOSPHERE_VAULT_TYPE environment variable.

Value	Description
keychain	Default. Stores secrets in the OS keychain.
plaintext	Stores secrets as JSON files under ~/.config/photosphere/vault/. Useful for testing or environments where a keychain daemon is not available.

# Force plaintext vault (e.g. in a script or CI environment)
export PHOTOSPHERE_VAULT_TYPE=plaintext

Keychain backend

Each platform uses a different tool to talk to the OS keychain:

Platform	Tool	Notes
macOS	/usr/bin/security	Built into every macOS installation. No extra setup required.
Linux	secret-tool	Talks to any Secret Service API daemon (GNOME Keyring, KWallet, etc.). Install with sudo apt install libsecret-tools on Debian/Ubuntu.
Windows	PowerShell + Windows.Security.Credentials.PasswordVault	Built into Windows 8 and later. Requires PowerShell on PATH.

If the required tool is missing, Photosphere will print an actionable error message and exit rather than failing silently.

Identifying Photosphere entries in the OS keychain UI

All secrets are stored with the service name photosphere and with the secret name prefixed by psi- (e.g. psi-s3test01). This prefix makes Photosphere entries easy to identify when browsing the OS keychain directly (Keychain Access on macOS, Credential Manager on Windows, or the GNOME Keyring viewer on Linux).

Plaintext backend

When PHOTOSPHERE_VAULT_TYPE=plaintext, secrets are stored as JSON files:

~/.config/photosphere/vault/

Each secret is stored as a JSON file named after the (percent-encoded) secret name with a .json extension. For example, a secret named abc12345 is stored as abc12345.json. File permissions are set to 0600 (owner read/write only) and the directory to 0700 (owner only).

The secrets directory can be overridden with the PHOTOSPHERE_VAULT_DIR environment variable.

Desktop App

Open the secrets management page from the left sidebar by clicking Manage Secrets.

Secret List

The page displays all secrets, grouped by type. For each secret you can see its label and type. Secret values are not shown in the list.

Adding a Secret

Click Add Secret and choose the secret type. Fill in the fields:

• S3 credentials — label, region, access key ID, secret access key, and optional endpoint URL (for non-AWS S3-compatible services like DigitalOcean Spaces or MinIO).
• Encryption key — label, then paste or import PEM-encoded private and public keys. You can also generate a new RSA-4096 key pair directly.
• API key — label and the API key value.

Secrets can also be created inline when adding or editing a database entry — choose + Create new in the secret picker without leaving the database form.

Editing a Secret

Click the edit icon to update any field of a secret. The label and values can be changed; the type cannot be changed after creation.

Deleting a Secret

Click the delete icon to remove a secret. If any database entries reference the secret, a warning is shown listing the affected databases so you can update them first.

CLI

The psi secrets command group provides secret management from the command line.

List Secrets

psi secrets list

Displays all secrets with their name and type. Values are masked.

Add a Secret

psi secrets add

Interactive prompts for name, type, and value.

Secret names must be unique. If you try to add a secret with a name that is already in use, the command will error and no secret will be added.

When a secret name is not found (for example, when passing --key my-photos and no secret with that name exists), the CLI displays fuzzy-matched suggestions — e.g. Did you mean: my-photo, my-photos-old? — to help correct typos.

View a Secret

psi secrets view                          # select from list
psi secrets view --name abc12345

Shows the full value of a secret (with a confirmation prompt, since this displays sensitive data).

Edit a Secret

psi secrets edit                                        # select from list
psi secrets edit --name abc12345
psi secrets edit --name abc12345 --yes --new-name new-label
psi secrets edit --name abc12345 --yes --value new-value

Prompts for a new name (pre-filled with the current name) and a new value (leave blank to keep the current one). Either or both can be changed.

Delete a Secret

psi secrets delete                          # select from list
psi secrets delete --name abc12345

Deletes the secret after confirmation.

Import an Encryption Key

psi secrets import
psi secrets import --yes --private-key /path/to/key.key

Imports a .key / .key.pub PEM file pair as an encryption key secret. You are prompted for the secret name; the filename (without extension) is offered as the default. If the .pub file is not found alongside the private key, the public key is derived automatically.

Shared Secrets and Database Linking

Secrets linked to database entries are stored with an 8-character alphanumeric name (e.g. abc12345) that is generated automatically when you create them through psi dbs add or the desktop database form.

The desktop app and the CLI psi dbs add command both let you pick existing secrets or create new ones inline during database registration.

When a database entry has a linked secret (e.g. encryptionKey: "abc12345"), opening that database looks up abc12345 in the vault and uses the credentials automatically — no -k flag needed.

Default S3 Fallback

When an S3 path is accessed and no database entry with linked credentials is found, psi looks for a vault secret named default:s3. This secret is created automatically the first time you go through the lazy interactive S3 setup prompt. It appears in psi secrets list and can be edited or deleted like any other secret.

If AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables are set, the default:s3 vault secret is not consulted — the AWS SDK uses the environment variables directly.

Sharing

You can share individual secrets to another device over the LAN. This is useful for transferring credentials without manually copying vault files.

• Desktop: Click Share on a secret to send it, or Receive Secret to receive one from another device.
• CLI: Use psi secrets send and psi secrets receive.

See Sharing-Credentials for full details on how LAN sharing works and its security architecture.

Related Pages

• Managing-Databases — managing the database list that links to these secrets
• Encryption — how database encryption works
• Configuration-Cloud-Storage — S3 storage setup
• Command-Reference — full CLI command reference (secrets section)