Managing Secrets

Photosphere stores sensitive credentials in a local secrets store 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, 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.

View a Secret

psi secrets view              # select from list
psi secrets view shared: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 shared:abc12345

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 shared: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 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 and uses the credentials automatically.

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.

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
• cli:s3 — S3 credentials configured via psi configure

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

Storage Location

The secrets 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 secrets store is shared between the desktop app and the CLI. Secrets created in one are available in the other.

The secrets 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 (secrets section)