Kreds: Streamlined Rails Credentials Access

Kreds is a simpler, shorter, and safer way to access Rails credentials, with a few extra features built in. Rails credentials are a convenient way to store secrets, but retrieving them could be more intuitive — that's where Kreds comes in.

Key Features:

• Simplified credential access with clear error messages
• Environment variable fallback support
• Environment-scoped credentials access
• Blank value detection and prevention

Before and After:

# Instead of this (long, silent failures if value is missing):
Rails.application.credentials[:recaptcha][:site_key]
# => nil

# Or this (long, unclear errors):
Rails.application.credentials[:captcha][:site_key]
# => undefined method `[]' for nil:NilClass (NoMethodError)

# Or even this (longer, still unclear errors):
Rails.application.credentials.fetch(:recaptcha).fetch(:key)
# => key not found: :key (KeyError)

# You can write this (shorter, human-readable errors):
Kreds.fetch!(:recaptcha, :site_key)
# => Blank value in credentials: [:recaptcha][:site_key] (Kreds::BlankCredentialsError)
Kreds.fetch!(:captcha, :site_key)
# => Credentials key not found: [:captcha] (Kreds::UnknownCredentialsError)

Gem Usage:

• Installation
• Credential Fetching
• Environment-Scoped Credentials
• Environment Variables
• Debug and Inspection

Community Resources:

• Getting Help and Contributing
• License
• Code of Conduct

Add Kreds to your Gemfile:

gem "kreds"

And then execute:

bundle install

Kreds.fetch!(*keys, var: nil, &block)

Fetches credentials from the Rails credentials store.

Parameters:

• *keys - Variable number of symbols representing the key path
• var - Optional environment variable name as fallback
• &block - Optional block to execute if fetch fails

Returns: The credential value

Raises:

• Kreds::UnknownCredentialsError - if the key path doesn't exist
• Kreds::BlankCredentialsError - if the value exists but is blank

# Basic usage
Kreds.fetch!(:aws, :s3, :credentials, :access_key_id)

# With environment variable fallback
Kreds.fetch!(:aws, :access_key_id, var: "AWS_ACCESS_KEY_ID")

# With block
Kreds.fetch!(:api_key) do
  raise MyCustomError, "API key not configured"
end

Kreds.env_fetch!(*keys, var: nil, &block)

Fetches credentials scoped by the current Rails environment (e.g., :production, :staging, :development).

Parameters: Same as fetch!

Returns: The credential value from Rails.application.credentials[Rails.env] followed by the provided key path

Raises: Same exceptions as fetch!

# Looks in credentials[:production][:recaptcha][:site_key] in production
Kreds.env_fetch!(:recaptcha, :site_key)

Kreds.var!(name, &block)

Fetches a value directly from environment variables.

Parameters:

• name - Environment variable name
• &block - Optional block to execute if variable is missing/blank

Returns: The environment variable value

Raises:

• Kreds::UnknownEnvironmentVariableError - if the variable doesn't exist
• Kreds::BlankEnvironmentVariableError - if the variable exists but is blank

# Direct environment variable access
Kreds.var!("AWS_ACCESS_KEY_ID")

# With block
Kreds.var!("THREADS") { 1 }

Kreds.show

Useful for debugging and exploring available credentials in the Rails console.

Returns: Hash containing all credentials

Kreds.show
# => { aws: { access_key_id: "...", secret_access_key: "..." }, ... }

Have a question or need assistance? Open a discussion in our discussions section for:

• Usage questions
• Implementation guidance
• Feature suggestions

Found a bug? Please create an issue with:

• A clear description of the problem
• Steps to reproduce the issue
• Your environment details (Rails version, Ruby version, etc.)

Ready to contribute? You can:

• Fix bugs by submitting pull requests
• Improve documentation
• Add new features (please discuss first in our discussions section)

Before contributing, please read the contributing guidelines

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the Kreds project is expected to follow the code of conduct.