op-loader

A TUI and CLI tool for managing 1Password secrets as environment variables.

Overview

op-loader provides a terminal UI for browsing your 1Password vaults and configuring which fields to inject as environment variables. Once configured, use the env subcommand to load secrets into your shell session.

Installation

Via Homebrew (macOS/Linux)

brew tap idiomattic/op-loader
brew install op-loader

Via Cargo

cargo install op-loader

Or build from source:

git clone https://github.com/idiomattic/op-loader
cd op-loader
cargo install --path .

Prerequisites

• 1Password CLI (op) must be installed and authenticated

Usage

TUI Mode

op-loader

Launch the interactive terminal UI to:

• Browse accounts and vaults
• Search items with fuzzy matching
• Select fields to map to environment variables
• Set default account/vault (persisted across sessions)

Navigation

Inject Environment Variables

eval "$(op-loader env inject -vv)"

Reads your configured mappings and outputs export statements. Add this to your shell rc file (.bashrc, .zshrc, etc.) to load secrets on shell startup.

To reduce repeated authentication prompts, you can cache resolved secrets per account for a short TTL (macOS only):

eval "$(op-loader env inject --cache-ttl 10m)"

Cache files are stored under $XDG_CACHE_HOME/op_loader (or ~/.cache/op_loader). On macOS, cached values are encrypted using a key stored in the system Keychain. DO NOT COMMIT THESE CACHE FILES TO VERSION CONTROL.

Caching strategy (macOS only):

• op-loader resolves each account’s secrets once per run and builds a JSON map of VAR -> value.
• The map is cached per account and reused for both export generation and template rendering.
• A per-account lock prevents duplicate op inject calls when multiple shells start in parallel; if the lock can’t be acquired within ~5 seconds, it falls back to a direct op inject.

This feature may be undesirable for some, but it is not any less-secure than having the secrets available in plaintext in your shell.

Unset Environment Variables

It may be desirable to clear all managed environment variables from your shell at times (perhaps when running a coding agent). To do so:

eval "$(op-loader env unset)"

This unsets all managed environment variables, but not vars otherwise exported in your shell.

Template Files

Some config files (like ~/.npmrc) don't support environment variable interpolation. Use templates to inject secrets directly into these files.

op-loader template add ~/.npmrc

This copies the file to ~/.config/op_loader/templates/ and adds a comment showing available variables. Edit the template to add {{VAR_NAME}} placeholders:

# op-loader: Available variables: {{GITHUB_TOKEN}}, {{NPM_TOKEN}}
//registry.npmjs.org/:_authToken={{NPM_TOKEN}}

Templates are rendered automatically when you run op-loader env inject, or manually with:

op-loader template render

Other template commands:

op-loader template list    # Show managed templates
op-loader template remove ~/.npmrc  # Stop managing a file

Cache Management

Clear cached op inject output (all accounts):

op-loader cache clear

Clear a single account cache:

op-loader cache clear --account <account_id>

Configuration

Show config file location:

op-loader config path

View current settings:

op-loader config get -k default_account_id

How It Works

1. Use the TUI to browse your 1Password vaults and select fields
2. Map fields to environment variable names (e.g., op://Personal/GitHub/token -> GITHUB_TOKEN)
3. Mappings are saved to the config file
4. Run eval "$(op-loader env inject)" to inject secrets into your shell

Configuration

Default config location: ~/.config/op_loader/default-config.toml

Available settings

• default_account_id: Auto-select this account on startup
• default_vault_per_account: Auto-select vault per account on startup
• inject_vars: Map of environment variable names to 1Password references
• templated_files: Map of file paths to template configurations

Privacy

All secrets are fetched directly from 1Password via the op CLI. No secrets are stored locally - only the references (e.g., op://vault/item/field) are saved in your config file. If you enable caching with --cache-ttl, plaintext op inject output is stored temporarily in the cache directory.

License

MIT