Shell Integration

Configure shell completions and prompt integration for envctl. See your current project and environment at a glance.

Shell Completions

envctl provides tab completions for commands, flags, project names, and environment names. Generate completions for your shell:

Bash

Add to your ~/.bashrc:

# envctl completions
eval "$(envctl completion bash)"

Or generate a file for system-wide completions:

$ envctl completion bash > /etc/bash_completion.d/envctl

Zsh

Add to your ~/.zshrc:

# envctl completions
eval "$(envctl completion zsh)"

If you use a completions directory, generate a file:

$ envctl completion zsh > "${fpath[1]}/_envctl"

Note

If completions don't work immediately, you may need to run compinit or start a new shell session.

Fish

Add to your ~/.config/fish/config.fish:

# envctl completions
envctl completion fish | source

Or generate a file:

$ envctl completion fish > ~/.config/fish/completions/envctl.fish

Prompt Integration

Display your current envctl project and environment in your shell prompt. This helps you stay aware of which secrets context you're working in.

Built-in Prompt Command

envctl includes a fast prompt helper that outputs the current context:

$ envctl prompt
myapp/dev

If you're not in an envctl project, it outputs nothing. This makes it safe to include in your prompt unconditionally.

Bash

Add to your ~/.bashrc:

# Add envctl context to prompt
__envctl_prompt() {
    local ctx
    ctx=$(envctl prompt 2>/dev/null)
    if [[ -n "$ctx" ]]; then
        echo "[$ctx] "
    fi
}

PS1='$(__envctl_prompt)\u@\h:\w\$ '

This shows:

[myapp/dev] user@host:~/projects/myapp$

Zsh

Add to your ~/.zshrc:

# Add envctl context to prompt
autoload -Uz add-zsh-hook

__envctl_prompt() {
    local ctx
    ctx=$(envctl prompt 2>/dev/null)
    if [[ -n "$ctx" ]]; then
        echo "[$ctx] "
    fi
}

setopt PROMPT_SUBST
PROMPT='$(__envctl_prompt)%n@%m:%~%# '

Fish

Add to your ~/.config/fish/config.fish:

# Add envctl context to prompt
function fish_prompt
    set -l ctx (envctl prompt 2>/dev/null)
    if test -n "$ctx"
        echo -n "[$ctx] "
    end
    echo -n (whoami)'@'(hostname)':'(prompt_pwd)'$ '
end

Performance

The envctl prompt command is optimized to be fast (~5ms), but if you notice slowdown, consider using Starship which caches the result.

Starship Integration

Starship is a popular cross-shell prompt that supports custom modules. envctl works well with Starship's custom command feature.

Basic Setup

Add to your ~/.config/starship.toml:

[custom.envctl]
command = "envctl prompt"
when = "envctl prompt"
format = "[$output]($style) "
style = "bold green"

This displays your envctl context in green when you're in a project directory.

Environment-Aware Styling

Color-code by environment to make prod stand out:

[custom.envctl]
command = "envctl prompt"
when = "envctl prompt"
format = "[$output]($style) "
style = "bold green"

[custom.envctl_prod]
command = "envctl prompt | grep -q '/prod$' && envctl prompt"
when = "envctl prompt | grep -q '/prod$'"
format = "[$output]($style) "
style = "bold red"

With Symbol

Add a symbol to make it visually distinct:

[custom.envctl]
command = "envctl prompt"
when = "envctl prompt"
symbol = "🔐 "
format = "[$symbol$output]($style) "
style = "bold cyan"

Result:

🔐 myapp/dev ~/projects/myapp

Detecting the Environment

For more advanced styling, use envctl prompt --format:

$ envctl prompt --format json
{"project":"myapp","environment":"dev"}

$ envctl prompt --format env
ENVCTL_PROJECT=myapp
ENVCTL_ENV=dev

This allows scripts to parse the output and apply different styling per environment.

Environment Variables

envctl sets these variables when you run envctl env shell or use the VS Code extension:

Variable Description
ENVCTL_PROJECT Current project name
ENVCTL_ENV Current environment (dev, staging, prod)
ENVCTL_ACTIVE Set to "1" when secrets are loaded

You can use these in your prompt without calling envctl prompt:

# Bash/Zsh - use env vars directly
__envctl_prompt() {
    if [[ -n "$ENVCTL_PROJECT" ]]; then
        echo "[$ENVCTL_PROJECT/$ENVCTL_ENV] "
    fi
}

This is faster since it doesn't spawn a subprocess, but only works when secrets are loaded via envctl env shell.

Troubleshooting

Completions not working

  • Ensure you've started a new shell or sourced your config
  • For Zsh, verify completion is enabled: autoload -Uz compinit && compinit
  • Check that envctl is in your PATH: which envctl

Prompt is slow

  • Use the environment variable method instead of envctl prompt
  • Consider using Starship which has built-in caching
  • Check daemon status: envctl daemon status

Prompt shows nothing

  • Verify you're in a project directory: envctl status
  • Check for errors: envctl prompt (without redirecting stderr)

Related