Keyring Provider

The Keyring provider stores secrets in your system’s native credential store. Recommended for local development.

Supported Platforms

• macOS: Keychain
• Windows: Credential Manager
• Linux: Secret Service (GNOME Keyring, KWallet)

Installation

Linux only - install if missing:

# Debian/Ubuntu
$ sudo apt-get install gnome-keyring

# Fedora
$ sudo dnf install gnome-keyring

# Arch
$ sudo pacman -S gnome-keyring

Configuration

URI Format

keyring://[folder_prefix]

• folder_prefix: Optional path prefix supporting {project}, {profile}, and {key} placeholders. Defaults to secretspec/{project}/{profile}/{key}.

Examples

# Use default keyring storage
$ secretspec set DATABASE_URL --provider keyring

# Custom folder prefix (e.g., to share secrets across projects — see below)
$ secretspec set DATABASE_URL --provider "keyring://shared/{profile}/{key}"

Usage

# Set a secret
$ secretspec set DATABASE_URL
Enter value for DATABASE_URL: postgresql://localhost/mydb
✓ Secret DATABASE_URL saved to keyring

# Get a secret
$ secretspec get DATABASE_URL
postgresql://localhost/mydb

# Run with secrets
$ secretspec run -- npm start

# Use with profiles
$ secretspec set API_KEY --profile production
$ secretspec run --profile production -- npm start

Shared Secrets

By default, secrets are stored under secretspec/{project}/{profile}/{key}, which isolates them per project. To share secrets across projects, use a custom folder prefix via the URI:

~/.config/secretspec/config.toml

[defaults.providers]
shared = "keyring://secretspec/shared/{profile}/{key}"

The URI supports {project}, {profile}, and {key} placeholders. By omitting {project}, multiple projects can read and write the same keyring entry:

# secretspec.toml (in project-A and project-B)
[profiles.default]
ARTIFACTORY_USER = { description = "Artifactory user", providers = ["shared"] }

Both projects will resolve ARTIFACTORY_USER from keyring service secretspec/shared/default/ARTIFACTORY_USER.