Skip to content

keyenv/ruby-sdk

Repository files navigation

KeyEnv Ruby SDK

Official Ruby SDK for KeyEnv - Secure secrets management for development teams.

Installation

Add this line to your application's Gemfile:

gem 'keyenv'

And then execute:

bundle install

Or install it yourself:

gem install keyenv

Quick Start

require 'keyenv'

client = KeyEnv.new(token: ENV['KEYENV_TOKEN'])

# Load secrets into ENV
client.load_env(project_id: 'your-project-id', environment: 'production')
puts ENV['DATABASE_URL']

Usage

Initialize the Client

require 'keyenv'

# Using keyword argument
client = KeyEnv.new(token: 'your-service-token')

# Alternative syntax
client = KeyEnv.create('your-service-token')

# With custom timeout and caching
client = KeyEnv.new(token: 'your-token', timeout: 60, cache_ttl: 300)

Export Secrets

# Get all secrets as a list
secrets = client.export_secrets(project_id: 'proj_123', environment: 'production')
secrets.each do |secret|
  puts "#{secret.key}=#{secret.value}"
end

# Get secrets as a hash
env = client.export_secrets_as_hash(project_id: 'proj_123', environment: 'production')
puts env['DATABASE_URL']

# Load directly into ENV
count = client.load_env(project_id: 'proj_123', environment: 'production')
puts "Loaded #{count} secrets"

Manage Secrets

# Get a single secret
secret = client.get_secret(project_id: 'proj_123', environment: 'production', key: 'DATABASE_URL')
puts secret.value

# Set a secret (creates or updates)
client.set_secret(
  project_id: 'proj_123',
  environment: 'production',
  key: 'API_KEY',
  value: 'sk_live_...'
)

# Delete a secret
client.delete_secret(project_id: 'proj_123', environment: 'production', key: 'OLD_KEY')

Bulk Import

result = client.bulk_import(
  project_id: 'proj_123',
  environment: 'development',
  secrets: [
    KeyEnv::BulkSecretItem.new(key: 'DATABASE_URL', value: 'postgres://localhost/mydb'),
    KeyEnv::BulkSecretItem.new(key: 'REDIS_URL', value: 'redis://localhost:6379'),
    { 'key' => 'API_KEY', 'value' => 'sk_test_...' }  # Also accepts hashes
  ],
  overwrite: true
)
puts "Created: #{result.created}, Updated: #{result.updated}"

Generate .env File

env_content = client.generate_env_file(project_id: 'proj_123', environment: 'production')
File.write('.env', env_content)

List Projects and Environments

# List all projects
projects = client.list_projects
projects.each do |project|
  puts "#{project.name} (#{project.id})"
end

# Get project with environments
project = client.get_project(project_id: 'proj_123')
project.environments.each do |env|
  puts "  - #{env.name}"
end

Service Token Info

# Get current user or service token info
user = client.get_current_user

if user.auth_type == 'service_token'
  # Service tokens can access multiple projects
  puts "Projects: #{user.project_ids}"
  puts "Scopes: #{user.scopes}"
end

Error Handling

require 'keyenv'

begin
  secret = client.get_secret(project_id: 'proj_123', environment: 'production', key: 'MISSING_KEY')
rescue KeyEnv::NotFoundError => e
  puts "Secret not found: #{e.message}"
rescue KeyEnv::AuthenticationError => e
  puts "Authentication failed: #{e.message}"
rescue KeyEnv::Error => e
  puts "Error #{e.status}: #{e.message}"
end

Error Types

Error Description
KeyEnv::Error Base error class
KeyEnv::AuthenticationError Authentication failed (401)
KeyEnv::NotFoundError Resource not found (404)
KeyEnv::ValidationError Invalid request (422)
KeyEnv::RateLimitError Rate limit exceeded (429)
KeyEnv::ConnectionError Network/connection error
KeyEnv::TimeoutError Request timeout

Caching

For serverless environments or high-traffic applications, enable caching to reduce API calls:

# Cache secrets for 5 minutes
client = KeyEnv.new(token: 'your-token', cache_ttl: 300)

# Or use environment variable
ENV['KEYENV_CACHE_TTL'] = '300'
client = KeyEnv.new(token: 'your-token')

# Manually clear cache
client.clear_cache  # Clear all
client.clear_cache(project_id: 'proj_123')  # Clear project
client.clear_cache(project_id: 'proj_123', environment: 'production')  # Clear specific

API Reference

KeyEnv.new(token:, timeout:, cache_ttl:)

Create a new KeyEnv client.

Parameter Type Required Default Description
token String Yes - Service token
timeout Integer No 30 Request timeout (seconds)
cache_ttl Integer No 0 Cache TTL (seconds, 0 = disabled)

Methods

Method Description
get_current_user Get current user/token info
list_projects List all accessible projects
get_project(project_id:) Get project with environments
list_environments(project_id:) List environments in a project
list_secrets(project_id:, environment:) List secret keys (no values)
export_secrets(project_id:, environment:) Export secrets with values
export_secrets_as_hash(project_id:, environment:) Export as hash
get_secret(project_id:, environment:, key:) Get single secret
set_secret(project_id:, environment:, key:, value:) Create or update secret
delete_secret(project_id:, environment:, key:) Delete secret
bulk_import(project_id:, environment:, secrets:) Bulk import secrets
load_env(project_id:, environment:) Load secrets into ENV
generate_env_file(project_id:, environment:) Generate .env file content
list_permissions(project_id:, environment:) List permissions
set_permission(project_id:, environment:, user_id:, role:) Set permission
delete_permission(project_id:, environment:, user_id:) Delete permission
get_my_permissions(project_id:) Get current user's permissions

Requirements

  • Ruby 3.0+

Development

# Install dependencies
bundle install

# Run tests
bundle exec rspec

# Run linter
bundle exec rubocop

# Generate documentation
bundle exec rake yard

License

MIT

About

Ruby SDK for KeyEnv - Secrets management made simple

Resources

License

Stars

Watchers

Forks

Packages

 
 
 

Contributors

Languages