Installation

Tip

For most users, the Getting Started guide handles installation automatically. This page is a reference for all installation methods and options.

Goal

Install dotsecenv on your system and verify it’s working correctly.

Steps

1. Choose your installation method

   Install Script (recommended)

   The universal installer is the fastest way to install dotsecenv. It auto-detects your platform, downloads the correct binary, verifies checksums and GPG signatures, and installs shell completions, man pages, and the shell plugin automatically.

   curl -fsSL https://get.dotsecenv.com/install.sh | bash

   Install a specific version:

   curl -fsSL https://get.dotsecenv.com/install.sh | bash -s -- --version v1.2.3

   Customize with flags:

   curl -fsSL https://get.dotsecenv.com/install.sh | bash -s -- \
     --install-dir ~/.local/bin \
     --no-install-shell-plugin

   Or use environment variables (useful for CI/CD):

   VERSION=v1.2.3 INSTALL_DIR=/opt/bin \
     curl -fsSL https://get.dotsecenv.com/install.sh | bash

   Run with --help for all available options. CLI flags take precedence over environment variables, which take precedence over defaults.

   macOS (Homebrew)

   brew tap dotsecenv/tap
   brew install dotsecenv

   This automatically installs shell completions.

   macOS (Binary)

   Download the binary directly:

   # Apple Silicon (M1/M2/M3)
   curl -LO https://get.dotsecenv.com/darwin/dotsecenv_0.5.2_Darwin_arm64.tar.gz
   
   # Intel Mac
   curl -LO https://get.dotsecenv.com/darwin/dotsecenv_0.5.2_Darwin_x86_64.tar.gz
   
   # Verify and install
   curl -s https://get.dotsecenv.com/darwin/checksums.txt | sha256sum -c --ignore-missing
   tar -xzf dotsecenv_*.tar.gz
   sudo mv dotsecenv /usr/local/bin/

   Debian/Ubuntu

   Add the apt repository:

   # Trust the GPG key
   curl -fsSL https://get.dotsecenv.com/key.asc | \
     sudo gpg --dearmor -o /etc/apt/keyrings/dotsecenv.gpg
   
   # Add the repository
   echo "deb [signed-by=/etc/apt/keyrings/dotsecenv.gpg] \
     https://get.dotsecenv.com/apt/ ./" | \
     sudo tee /etc/apt/sources.list.d/dotsecenv.list
   
   # Install
   sudo apt-get update
   sudo apt-get install dotsecenv

   Fedora/RHEL

   Add the yum repository:

   cat <<EOF | sudo tee /etc/yum.repos.d/dotsecenv.repo
   [dotsecenv]
   name=DotSecEnv Repository
   baseurl=https://get.dotsecenv.com/yum/
   enabled=1
   gpgcheck=1
   repo_gpgcheck=1
   gpgkey=https://get.dotsecenv.com/key.asc
   EOF
   
   sudo dnf install dotsecenv

   Arch Linux

   Add to pacman:

   # Add to pacman.conf
   cat <<'EOF' | sudo tee -a /etc/pacman.conf
   [dotsecenv]
   Server = https://get.dotsecenv.com/arch/$arch
   SigLevel = Required DatabaseOptional
   EOF
   
   # Trust the key
   curl -fsSL https://get.dotsecenv.com/key.asc | sudo pacman-key --add -
   sudo pacman-key --lsign-key E60A1740BAEF49284D22EA7D3C376348F0921C59
   
   # Install
   sudo pacman -Sy dotsecenv

   mise

   If you use mise:

   mise use github:dotsecenv/dotsecenv

   Windows

   Work in Progress

   Windows support is still under development. Follow issue #8 for updates.

   Download the .zip for your architecture from the Releases page:

   • dotsecenv_vX.X.X_Windows_x86_64.zip for 64-bit Intel/AMD
   • dotsecenv_vX.X.X_Windows_arm64.zip for ARM64

   Extract and add the binary location to your PATH.

   GPG Requirement: Install Gpg4win for GPG support. When you run dotsecenv init config, it will detect GPG automatically and set the path. You can also manually configure it in your config file:

   gpg:
     program: "C:\\Program Files (x86)\\GnuPG\\bin\\gpg.exe"

   From Source

   Build from source (requires Go 1.25+):

   git clone https://github.com/dotsecenv/dotsecenv.git
   cd dotsecenv
   make build
   sudo mv bin/dotsecenv /usr/local/bin/

2. Verify the installation

   dotsecenv version

   You should see output like:

   version: v0.5.2
   commit: abc1234
   build at: 2025-01-15T10:30:00Z
   go version: go1.24.0
   crypto: GOFIPS140=v1.26.0 (FIPS 140-3 mode enabled)

3. Install shell completions (if not automatic)

   Bash

   # System-wide
   dotsecenv completion bash | sudo tee /etc/bash_completion.d/dotsecenv
   
   # Or user-level (add to ~/.bashrc)
   eval "$(dotsecenv completion bash)"

   Zsh

   # Add to ~/.zshrc
   eval "$(dotsecenv completion zsh)"

   Fish

   # Add to ~/.config/fish/config.fish
   dotsecenv completion fish | source

   PowerShell

   Work in Progress

   Windows support is still under development. Follow issue #8 for updates.

   # Add to your PowerShell profile ($PROFILE)
   dotsecenv completion powershell | Out-String | Invoke-Expression

Expected Result

After installation, you should be able to:

# Check version
dotsecenv version

# See available commands
dotsecenv --help

# Tab-complete commands (after shell restart)
dotsecenv <TAB>

Variations

Install Script Reference

The universal install script (install.sh) supports both CLI flags and environment variables for every setting. This makes it equally convenient for interactive use (curl | bash -s -- --flags) and automated CI/CD pipelines (ENV_VAR=value curl | bash).

Precedence order: CLI flags > environment variables > defaults.

Usage

# Piped (simplest)
curl -fsSL https://get.dotsecenv.com/install.sh | bash

# Piped with CLI flags
curl -fsSL https://get.dotsecenv.com/install.sh | bash -s -- [OPTIONS]

# Piped with environment variables
VERSION=v1.2.3 curl -fsSL https://get.dotsecenv.com/install.sh | bash

# Downloaded and run locally
curl -fsSL https://get.dotsecenv.com/install.sh -o install.sh
chmod +x install.sh
./install.sh --version v1.2.3

Options

Every setting can be configured via a CLI flag or an environment variable. CLI flags take precedence over environment variables.

Setting	CLI Flag	Env Var	Default	Description
Version	--version VERSION	VERSION	latest	Version to install (e.g., v1.2.3)
Install directory	--install-dir DIR	INSTALL_DIR	~/.local/bin	Binary install path
System install	--system	SYSTEM_INSTALL	0	Install everything system-wide
Shell plugin	--[no-]install-shell-plugin	INSTALL_SHELL_PLUGIN	1 (yes)	Install the shell plugin for zsh/bash/fish
Completions	--[no-]install-completions	INSTALL_COMPLETIONS	1 (yes)	Install shell completions for bash, zsh, and fish
Man pages	--[no-]install-man-pages	INSTALL_MAN_PAGES	1 (yes)	Install man pages
TF credentials helper	--[no-]install-tf-credentials-helper	INSTALL_TF_CREDENTIALS_HELPER	1 (yes)	Install the Terraform credentials helper
Verification	--[no-]verify	VERIFY	1 (yes)	Verify SHA-256 checksums and GPG signatures
Help	-h, --help	—	—	Show help and exit

What the Installer Does

1. Detects your platform — OS (Linux or macOS) and architecture (x86_64 or arm64)
2. Resolves the version — Queries the GitHub API for the latest release, or uses the version you specified
3. Downloads the release archive — From GitHub Releases
4. Verifies integrity — SHA-256 checksum verification and GPG signature verification (when gpg is available)
5. Installs the binary — To ~/.local/bin by default (or /usr/local/bin with --system)
6. Installs shell completions — For bash, zsh, and fish, placed in ~/.local/share/ by default (or system directories with --system)
7. Installs man pages — To ~/.local/share/man/man1/ by default (or system man directories with --system)
8. Installs the shell plugin — Clones to ~/.local/share/dotsecenv/plugin/ by default (or system share path with --system). Additionally integrates with detected plugin managers (Oh My Zsh, Zinit, Antidote, Oh My Bash, Fisher, Oh My Fish). Fish conf.d is linked automatically if fish is present.
9. Installs the Terraform credentials helper — To ~/.terraform.d/plugins/ by default (or system share path with --system). Skip with --no-install-tf-credentials-helper

Install Paths

Component	Default (user)	--system (macOS)	--system (Linux)
Binary	~/.local/bin/	/usr/local/bin/	/usr/local/bin/
Completions	~/.local/share/	/usr/local/share/	/usr/share/
Man pages	~/.local/share/man/man1/	/usr/local/share/man/man1/	/usr/local/share/man/man1/
Shell plugin	~/.local/share/dotsecenv/plugin/	/usr/local/share/dotsecenv/plugin/	/usr/share/dotsecenv/plugin/
TF helper	~/.terraform.d/plugins/	/usr/local/share/terraform/plugins/	/usr/share/terraform/plugins/

Examples

CI/CD: Install specific version, skip interactive components:

VERSION=v1.2.3 INSTALL_SHELL_PLUGIN=0 INSTALL_MAN_PAGES=0 \
  curl -fsSL https://get.dotsecenv.com/install.sh | bash

Custom install directory with Terraform helper:

curl -fsSL https://get.dotsecenv.com/install.sh | bash -s -- \
  --install-dir /opt/dotsecenv/bin \
  --install-tf-credentials-helper

Minimal install (binary only):

curl -fsSL https://get.dotsecenv.com/install.sh | bash -s -- \
  --no-install-shell-plugin \
  --no-install-completions \
  --no-install-man-pages

Download and inspect before running:

curl -fsSL https://get.dotsecenv.com/install.sh -o install.sh
less install.sh  # review the script
bash install.sh --version v1.2.3

Requires curl or wget

The install script works with either curl or wget. At least one must be available on your system.

Installing a Specific Version

Download a specific version from GitHub releases:

VERSION="0.5.2"
curl -LO "https://github.com/dotsecenv/dotsecenv/releases/download/v${VERSION}/dotsecenv_${VERSION}_Linux_x86_64.tar.gz"

Verifying Package Signatures

All packages are signed with the dotsecenv release key:

pub   rsa4096 2025-12-19 [SC] [expires: 2027-12-19]
      E60A1740BAEF49284D22EA7D3C376348F0921C59
uid   DotSecEnv Releases <release@dotsecenv.com>

Verify the key from multiple sources:

# OpenPGP Keyserver
gpg --keyserver keys.openpgp.org --recv-keys E60A1740BAEF49284D22EA7D3C376348F0921C59

# Keybase
curl https://keybase.io/dotsecenv/pgp_keys.asc | gpg --import

Verifying macOS Notarization

All macOS binaries are code-signed with an Apple Developer ID certificate and notarized by Apple. This ensures Gatekeeper allows the binary to run without security warnings.

Verify code signature:

codesign --verify --verbose /usr/local/bin/dotsecenv
# Expected: valid on disk

Verify notarization status:

spctl --assess --verbose /usr/local/bin/dotsecenv
# Expected: accepted
# source=Notarized Developer ID

View signature details:

codesign -dv --verbose=4 /usr/local/bin/dotsecenv

Homebrew Users

If you installed via Homebrew, the binary is located at $(brew --prefix)/bin/dotsecenv. Homebrew casks automatically handle quarantine removal, so Gatekeeper warnings are bypassed.

Uninstalling

Homebrew

brew uninstall dotsecenv
brew untap dotsecenv/tap

apt

sudo apt-get remove dotsecenv
sudo rm /etc/apt/sources.list.d/dotsecenv.list

Binary

sudo rm /usr/local/bin/dotsecenv

Note

Uninstalling dotsecenv does not remove your vault or config files. To remove all data:

rm -rf ~/.config/dotsecenv

---

Next Steps

• First Secret — Store and use your first secret
• Getting Started — Complete initial setup