easy_creds

Interactive TUI for syncing encrypted Rails credentials with 1Password. Works inside Rails projects or as a standalone CLI.

💎 RubyGems  |  📖 Documentation  |  GitHub  |  Changelog

Features

• Full-screen TUI navigator — browse all credential keys, generate values, pull from 1Password, or enter manually, all from one interface
• Push / pull diff — see exactly what changed before committing to 1Password
• Local overlay — keep machine-specific secrets in a gitignored _local.yml.enc that merges on top of the base credentials at boot
• Onboarding wizard — scaffold an example.yml for any new project from bundled or custom templates
• Provider abstraction — 1Password CLI ships in v1; the seam is open for other providers

Requirements

• Ruby ≥ 3.2
• 1Password CLI (op) installed and signed in
• Rails ≥ 7.0 (for Rails usage) — or any directory for standalone usage

Installation

Add to your Gemfile:

gem 'easy_creds'

Then run:

bundle install
bin/rails easy_creds:install   # install overlay initializer + gitignore rules

Quick start (Rails)

# First time — scaffold example.yml
bin/rails easy_creds:onboard

# Day-to-day — open TUI
bin/rails credentials:sync

Quick start (standalone CLI)

# First time — gem setup + pick vault
easy_creds init

# Per-project onboarding
cd /path/to/project
easy_creds onboard

# Open sync TUI
easy_creds sync

CLI reference

Command	Description
easy_creds sync [ENV]	Open interactive TUI loop
easy_creds init	First-time gem setup (global dir, vault)
easy_creds onboard	Per-project example.yml wizard
easy_creds install	Install overlay initializer + gitignore rules
easy_creds doctor	Health check (op CLI, sign-in, vault, project)
easy_creds template list	List available templates
easy_creds version	Print gem version

Rake tasks (Rails)

Task	Description
rails credentials:sync	Open TUI sync loop
rails easy_creds:install	Install overlay initializer + gitignore
rails easy_creds:onboard	Per-project onboarding wizard

TUI keyboard shortcuts

Key	Action
↑ / ↓ or k / j	Navigate keys
PgUp / PgDn	Jump 10
Home / End	First / last
g	Generate value (default)
G	Generate alt value
b	Batch generate AR encryption keys (3 keys)
t	Use template placeholder
o	Fill from 1Password
m	Enter manually (hidden input)
c	Clear / reset to unset
T	Template all unset
R	Generate all suggested
O	Fill all unset from 1Password
s	Save and write .yml.enc
q	Quit (confirm if unsaved)
? / h	Toggle help panel

Value generation. Inside a Rails project, g / b / R derive secrets with Rails itself — rails secret for secret_key_base / devise_secret_key / crypt_secret, and rails db:encryption:init for the three active_record_encryption.* keys. If the shell-out fails or you run standalone (outside a Rails app), generation falls back to SecureRandom. G (alt) always uses SecureRandom.

Local overlay

The overlay merges a gitignored config/credentials/<env>_local.yml.enc on top of the base credentials at boot. Useful for machine-specific overrides (e.g. a local database URL).

# Open the local overlay editor
bin/rails credentials:sync   # → choose Local → Edit (inline)
# or
easy_creds sync development  # → Local → Edit

The overlay key (<env>_local.key) is never pushed to 1Password.

Configuration

# config/initializers/easy_creds.rb  (optional)
EasyCreds.configure do |config|
  config.global_dir       = '~/.easy_creds'       # default
  config.default_provider = :onepassword           # default
  config.default_vault    = nil                    # prompted on first run
  config.default_template = :rails_fullstack       # default
end

Precedence (low → high): built-in defaults → ~/.easy_creds/config.yml → <project>/config/easy_creds.yml → EasyCreds.configure { }.

Templates

Three bundled templates:

Name	Use case
rails-fullstack	Full Rails app (DB, AR encryption, OAuth, S3)
rails-api	API-only Rails (DB, AR encryption, OAuth)
microservice-minimal	Minimal service (DB URL, one API key)

Save a custom template:

easy_creds template save myapp --from config/credentials/example.yml

Development

cd ~/git/cowork/gems/easy_creds
bundle install
bundle exec rake test          # run test suite
bundle exec exe/easy_creds version
bundle exec exe/easy_creds doctor

License

MIT