Zsh Doppler Plugin

January 13, 2026 · View on GitHub

Tests License: MIT GitHub stars GitHub issues

A lightweight Zsh plugin that displays your current Doppler project and configuration in your shell prompt from environment variables. Perfect for developers working with multiple Doppler environments who want to keep track of their current context.

Demo

Features

  • ⚡ Lightning Fast - Reads from Doppler CLI configuration and environment variables
  • 🚀 CI/CD Perfect - Works seamlessly in Docker, CI/CD, and production environments
  • 🎯 Auto-detection - Shows when DOPPLER_PROJECT and DOPPLER_CONFIG are set or configured
  • 🎨 Smart Colors - Environment-based colors (green for dev, yellow for staging, red for prod)
  • 🔧 Highly Customizable - Configure colors, format, prefix/suffix, and more
  • 🔌 Compatible - Works with Oh My Zsh, Prezto, or standalone Zsh
  • 💎 Powerlevel10k - Full custom segment support with instant prompt compatibility
  • 🛡️ Reliable - Graceful fallbacks and error handling
  • ⚠️ Production Warning - Visual alert when entering production directories
  • ✅ Well Tested - Comprehensive test suite with 57 tests

Quick Start

Get up and running in under 2 minutes:

  1. Install (Oh My Zsh):

    git clone https://github.com/lsdcapital/zsh-doppler.git ~/.oh-my-zsh/custom/plugins/zsh-doppler

  2. Enable by adding zsh-doppler to your plugins in ~/.zshrc:

    plugins=(git zsh-doppler)

  3. Add to your prompt:

    PROMPT='${DOPPLER_PROMPT_INFO} %~ $ '   # Left side
# or
RPROMPT='${DOPPLER_PROMPT_INFO}'        # Right side

  4. Reload your shell:

    source ~/.zshrc

  5. Configure Doppler in your project directory:

    doppler setup

Now your prompt shows [project/config] with environment-aware colors! 🎉

Powerlevel10k users: Run doppler_p10k_setup after installation for p10k-specific instructions.

Requirements

  • Zsh
  • Doppler CLI (optional, for directory-based configuration)
  • Environment variables DOPPLER_PROJECT and DOPPLER_CONFIG (automatically set by doppler run) or directory-based Doppler configuration

Installation

Oh My Zsh

  1. Clone this repository to your Oh My Zsh custom plugins directory:
git clone https://github.com/lsdcapital/zsh-doppler.git ~/.oh-my-zsh/custom/plugins/zsh-doppler
  1. Add zsh-doppler to your plugins list in ~/.zshrc:
plugins=(git zsh-doppler)
  1. Restart your terminal or run:
source ~/.zshrc

Standalone Installation

  1. Clone the repository:
git clone https://github.com/lsdcapital/zsh-doppler.git ~/.zsh-doppler
  1. Add this line to your ~/.zshrc:
source ~/.zsh-doppler/zsh-doppler.plugin.zsh
  1. Restart your terminal or run:
source ~/.zshrc

Zinit

zinit light lsdcapital/zsh-doppler

Zplug

zplug "lsdcapital/zsh-doppler"

Antigen

antigen bundle lsdcapital/zsh-doppler

npm

npm install -g @lsdcapital/zsh-doppler

Then add to your ~/.zshrc:

source "$(npm root -g)/@lsdcapital/zsh-doppler/zsh-doppler.plugin.zsh"

Manual Installation

Simply download zsh-doppler.plugin.zsh and source it in your ~/.zshrc:

source /path/to/zsh-doppler.plugin.zsh

Powerlevel10k Installation

If you're using Powerlevel10k (which overrides standard prompts), follow these steps:

  1. Install the plugin using any method above
  2. Run the p10k setup helper:
doppler_p10k_setup
  1. Add doppler to your prompt elements in ~/.p10k.zsh:
# Add to right side prompt
typeset -g POWERLEVEL9K_RIGHT_PROMPT_ELEMENTS=(
  doppler  # Add this line
  status
  command_execution_time
  # ... your existing elements ...
)
  1. Restart your terminal or run: p10k reload

Usage

Standard Zsh Prompts

Add ${DOPPLER_PROMPT_INFO} to your PROMPT or RPROMPT:

# Left prompt
PROMPT='${DOPPLER_PROMPT_INFO} %~ $ '

# Right prompt
RPROMPT='${DOPPLER_PROMPT_INFO}'

# With existing elements
PROMPT='%F{green}%n@%m%f ${DOPPLER_PROMPT_INFO}%F{blue}%~%f $ '

Powerlevel10k

Run the setup helper to add the doppler segment:

doppler_p10k_setup

Then add doppler to your prompt elements in ~/.p10k.zsh:

typeset -g POWERLEVEL9K_RIGHT_PROMPT_ELEMENTS=(
  doppler  # Add here
  status
  # ... other elements
)

Example Output

[myproject/dev] ~/code/myapp $

Colors change automatically based on environment: dev (green), staging (yellow), prod (red).

Configuration

Customize the plugin behavior with these environment variables:

VariableDefaultDescription
DOPPLER_PROMPT_ENABLEDtrueEnable/disable the plugin
DOPPLER_PROMPT_PREFIX[Text before Doppler info
DOPPLER_PROMPT_SUFFIX]Text after Doppler info
DOPPLER_PROMPT_SEPARATOR/Separator between project and config
DOPPLER_PROMPT_FORMAT%project%separator%configFormat template
DOPPLER_PROMPT_COLORcyanColor name (fallback)
DOPPLER_COLOR_DEVgreenColor for dev environments
DOPPLER_COLOR_STAGINGyellowColor for staging environments
DOPPLER_COLOR_PRODredColor for production environments
DOPPLER_COLOR_DEFAULTcyanColor for unknown environments
DOPPLER_P10K_AUTO_ADDfalseAuto-add to p10k right prompt
DOPPLER_PROD_WARNINGtrueShow warning when entering prod directories
DOPPLER_PROD_WARNING_MESSAGE⚠️ PRODUCTION ENVIRONMENTCustom warning message

Environment Pattern Matching

Colors are automatically assigned based on config name patterns (case-insensitive):

ColorPatternsExamples
Green (dev)dev*, development*, local*dev, dev-us, development, local
Yellow (staging)stag*, staging*, test*, uat*, qa*staging, stg, test, uat, qa
Red (prod)prod*, production*, live*, prd*prod, production, prd, live
Cyan (default)ci*, sandbox*, and everything elseci, sandbox, demo, preview

Powerlevel10k Configuration

Additional variables for Powerlevel10k users:

VariableDefaultDescription
POWERLEVEL9K_DOPPLER_FOREGROUNDcyanText color
POWERLEVEL9K_DOPPLER_BACKGROUNDnoneBackground color
POWERLEVEL9K_DOPPLER_VISUAL_IDENTIFIER_EXPANSION🔐Icon
POWERLEVEL9K_DOPPLER_PREFIX[Text before (p10k)
POWERLEVEL9K_DOPPLER_SUFFIX]Text after (p10k)
POWERLEVEL9K_DOPPLER_FORMATUses DOPPLER_PROMPT_FORMATP10k format template

Examples

# Minimal config-only display
export DOPPLER_PROMPT_FORMAT="%config"
export DOPPLER_PROMPT_PREFIX="env:"
export DOPPLER_PROMPT_SUFFIX=" "
# Output: env:dev

# Custom separators
export DOPPLER_PROMPT_PREFIX="("
export DOPPLER_PROMPT_SUFFIX=")"
export DOPPLER_PROMPT_SEPARATOR=" → "
# Output: (myproject → dev)

# Custom environment colors
export DOPPLER_COLOR_DEV="blue"
export DOPPLER_COLOR_PROD="magenta"

Production Warning

When you cd into a directory configured for a production environment, the plugin displays a warning banner:

⚠️  PRODUCTION ENVIRONMENT (myproject/prod)

This helps prevent accidental operations in production. The warning appears when:

  • You cd into a directory with a production Doppler config
  • The config name matches production patterns (prod*, production*, live*, prd*)

The warning does not repeat when:

  • Moving between subdirectories of the same production directory
  • Already in the production directory context
# Disable production warnings
export DOPPLER_PROD_WARNING=false

# Customize the warning message
export DOPPLER_PROD_WARNING_MESSAGE="🔴 DANGER: PRODUCTION"

Format Template

The DOPPLER_PROMPT_FORMAT variable supports these placeholders:

  • %project - Doppler project name
  • %config - Doppler config name
  • %separator - The separator character/string

Performance

The plugin is designed for minimal prompt latency:

Caching Architecture

The plugin uses a precmd hook to populate $DOPPLER_PROMPT_INFO once per command, avoiding file I/O on every keystroke. This means:

  • Use ${DOPPLER_PROMPT_INFO} in prompts (cached, instant)
  • Avoid $(doppler_prompt_info) (executes on every redraw)

Data Sources

  1. Environment variables (fastest): When using doppler run, reads $DOPPLER_PROJECT and $DOPPLER_CONFIG directly
  2. YAML file: When configured via doppler setup, reads ~/.doppler/.doppler.yaml using fast awk-based parsing

The plugin never calls the Doppler CLI during prompt rendering, ensuring consistent performance regardless of network or API conditions.

Troubleshooting

Plugin Not Showing

  1. Test the plugin:

    doppler_prompt_test    # Check Doppler CLI and configuration
doppler_prompt_config  # View current plugin settings

  2. Verify Doppler setup:

    doppler configure      # Check directory configuration
doppler --version      # Ensure CLI is installed

  3. Check prompt substitution is enabled:

    setopt prompt_subst

Performance Issues

  • Ensure you're using ${DOPPLER_PROMPT_INFO} (cached) not $(doppler_prompt_info) (executes every keystroke)
  • Verify ~/.doppler/.doppler.yaml file exists and is readable (created by doppler setup)
  • Check YAML parsing: cat ~/.doppler/.doppler.yaml | grep $(pwd) to verify directory config exists

Compatibility

This plugin works with:

  • ✅ Oh My Zsh
  • ✅ Prezto
  • ✅ Standalone Zsh
  • ✅ Powerlevel10k - Full custom segment support
  • ✅ Powerlevel9k - Compatible with p10k segment API
  • ✅ Any Zsh framework that supports plugins

Tested with:

  • macOS (Zsh 5.8+)
  • Linux (Zsh 5.1+)
  • Doppler CLI 3.0+

Note: Requires Zsh 5.1+ due to use of ${var:l} lowercase parameter expansion.

Testing

The plugin includes a comprehensive test suite with color logic, prompt formatting, configuration, and performance regression detection.

Running Tests

pnpm install  # Install dependencies
pnpm test     # Run all tests
pnpm run test:coverage  # With coverage report

Tests execute actual Zsh functions to ensure real-world compatibility. See test files in tests/ for implementation details.

Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature-name
  3. Make your changes
  4. Run the test suite: pnpm test
  5. Test with different Zsh configurations
  6. Submit a pull request

License

MIT License - see LICENSE file for details.

  • Doppler CLI - Official Doppler command-line tool
  • Oh My Zsh - Framework for managing Zsh configuration

Support