Zsh Doppler Plugin

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.

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
✅ Well Tested - Comprehensive test suite with 30+ tests

Quick Start

Get up and running in under 2 minutes:

Install (Oh My Zsh):

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

Enable by adding zsh-doppler to your plugins in ~/.zshrc:
```
plugins=(git zsh-doppler)
```

Add to your prompt:

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

Reload your shell:
```
source ~/.zshrc
```
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

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

Add zsh-doppler to your plugins list in ~/.zshrc:

plugins=(git zsh-doppler)

Restart your terminal or run:

source ~/.zshrc

Standalone Installation

Clone the repository:

git clone https://github.com/lsdcapital/zsh-doppler.git ~/.zsh-doppler

Add this line to your ~/.zshrc:

source ~/.zsh-doppler/zsh-doppler.plugin.zsh

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:

Install the plugin using any method above
Run the p10k setup helper:

doppler_p10k_setup

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 ...
)

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:

Variable	Default	Description
`DOPPLER_PROMPT_ENABLED`	`true`	Enable/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%config`	Format template
`DOPPLER_PROMPT_COLOR`	`cyan`	Color name (fallback)
`DOPPLER_COLOR_DEV`	`green`	Color for dev environments
`DOPPLER_COLOR_STAGING`	`yellow`	Color for staging environments
`DOPPLER_COLOR_PROD`	`red`	Color for production environments
`DOPPLER_COLOR_DEFAULT`	`cyan`	Color for unknown environments
`DOPPLER_P10K_AUTO_ADD`	`false`	Auto-add to p10k right prompt

Environment Pattern Matching

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

Color	Patterns	Examples
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 else	`ci`, `sandbox`, `demo`, `preview`

Powerlevel10k Configuration

Additional variables for Powerlevel10k users:

Variable	Default	Description
`POWERLEVEL9K_DOPPLER_FOREGROUND`	`cyan`	Text color
`POWERLEVEL9K_DOPPLER_BACKGROUND`	`none`	Background color
`POWERLEVEL9K_DOPPLER_VISUAL_IDENTIFIER_EXPANSION`	`🔐`	Icon
`POWERLEVEL9K_DOPPLER_PREFIX`	`[`	Text before (p10k)
`POWERLEVEL9K_DOPPLER_SUFFIX`	`]`	Text after (p10k)
`POWERLEVEL9K_DOPPLER_FORMAT`	Uses `DOPPLER_PROMPT_FORMAT`	P10k 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"

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

Environment variables (fastest): When using doppler run, reads $DOPPLER_PROJECT and $DOPPLER_CONFIG directly
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

Test the plugin:

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

Verify Doppler setup:

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

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

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

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
.github/workflows		.github/workflows
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
demo.png		demo.png
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
vitest.config.js		vitest.config.js
zsh-doppler.plugin.zsh		zsh-doppler.plugin.zsh

License

lsdcapital/zsh-doppler

Folders and files

Latest commit

History

Repository files navigation

Zsh Doppler Plugin

Features

Quick Start

Requirements

Installation

Oh My Zsh

Standalone Installation

Zinit

Zplug

Antigen

npm

Manual Installation

Powerlevel10k Installation

Usage

Standard Zsh Prompts

Powerlevel10k

Example Output

Configuration

Environment Pattern Matching

Powerlevel10k Configuration

Examples

Format Template

Performance

Caching Architecture

Data Sources

Troubleshooting

Plugin Not Showing

Performance Issues

Compatibility

Testing

Running Tests

Contributing

License

Related Projects

Support

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Languages

Packages