Managing Secrets

Photosphere stores sensitive credentials in a local vault at ~/.config/photosphere/vault/. Secrets are persisted as plain-text JSON files, one per secret, with file permissions restricted to the owner.

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.

Desktop App

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

Secret List

The page displays all secrets in the vault, 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 from the vault. If any database entries reference the secret, a warning is shown listing the affected databases so you can update them first.

CLI

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

List Secrets

psi vault list

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

Add a Secret

psi vault add

Interactive prompts for name, type, and value.

View a Secret

psi vault view shared:abc12345

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

Edit a Secret

psi vault edit shared:abc12345

Prompts for a new value with the option to keep the current one.

Delete a Secret

psi vault delete shared:abc12345

Deletes the secret after confirmation.

Import an Encryption Key

psi vault import

Imports a .key / .key.pub PEM file pair into the vault as an encryption key secret.

Shared Secrets and Database Linking

Secrets intended to be linked to database entries use the naming convention shared:<id>, where <id> is an 8-character alphanumeric identifier. When you create a secret through the database form (desktop or CLI psi dbs add), this naming is handled automatically.

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

When a database entry has a linked secret (e.g. encryptionKeyId: "abc12345"), opening that database resolves shared:abc12345 from the vault and uses the credentials automatically.

CLI-Only Secrets

The CLI also stores its own secrets under different naming conventions:

• cli:encryption:<name> — encryption keys created via psi init --key <name> --generate-key or psi vault import
• cli:s3 — S3 credentials configured via psi configure

These are separate from shared secrets and are not linked to database entries.

Storage Location

The vault directory is:

~/.config/photosphere/vault/

Each secret is stored as a JSON file named after the (percent-encoded) secret name with a .json extension. For example, shared:abc12345 is stored as shared%3Aabc12345.json.

File permissions are set to 0600 (owner read/write only) and the directory to 0700 (owner only).

The vault is shared between the desktop app and the CLI. Secrets created in one are available in the other.

The vault directory can be overridden with the PHOTOSPHERE_VAULT_DIR environment variable (useful for testing).

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 (vault section)