CLI Reference

Complete reference for all dotsecenv commands. Use dotsecenv --help or dotsecenv <command> --help for inline help.

---

Global Options

These options work with all commands:

Option	Description
-c, --config PATH	Path to config file (default: ~/.config/dotsecenv/config)
-v, --vault PATH	Path to vault file or vault index (1-based)
-s, --silent	Silent mode (suppress warnings)
-h, --help	Show help for command

---

dotsecenv

Safe environment secrets management.

dotsecenv [flags]
dotsecenv [command]

A secure tool for managing environment secrets using GPG encryption. Secrets are stored in vault files and can be shared between team members.

Available Commands

Command	Description
init	Initialize configuration or vault files
login	Initialize user identity
secret	Manage secrets
vault	Manage vaults
validate	Validate vault and config
completion	Generate shell completion scripts
version	Show version information

---

init

Initialize configuration or vault files.

init config

Initialize a new configuration file.

dotsecenv init config [flags]

By default, creates a configuration file at the XDG config location (~/.config/dotsecenv/config). Use -c to specify a custom path.

The default configuration uses FIPS 186-5 compliant algorithm minimums: RSA 2048+, ECC P-384+, EdDSA Ed25519/Ed448.

Options:

Flag	Description
--gpg-program PATH	Set gpg.program to this path (without validation)
--no-gpg-program	Skip GPG detection (leave gpg.program empty)
--strict	Initialize config with strict mode enabled
--login FINGERPRINT	Initialize config with specified fingerprint

Examples:

# Create default config (FIPS-compliant by default)
dotsecenv init config

# Create config at custom location
dotsecenv init config -c ~/my-project/dotsecenv.yaml

# Skip GPG detection (for systems without GPG)
dotsecenv init config --no-gpg-program

# Set GPG path explicitly
dotsecenv init config --gpg-program /usr/local/bin/gpg

# Initialize with strict mode and login in one step
dotsecenv init config --strict --login E60A1740BAEF49284D22EA7D3C376348F0921C59

# Initialize with strict mode only
dotsecenv init config --strict

init vault

Initialize vault file(s).

dotsecenv init vault [flags]

Two modes of operation:

1. With -v PATH: Initialize a specific vault file at the given path
2. Without -v: Interactive mode using vaults from configuration

Note

Both -v and -c cannot be specified at the same time.

Examples:

# Initialize vault(s) from config
dotsecenv init vault

# Initialize specific vault
dotsecenv init vault -v ~/project/secrets/vault

---

login

Initialize user identity with the given GPG fingerprint.

dotsecenv login FINGERPRINT [flags]

The fingerprint should be the full 40-character GPG key fingerprint of the user who will be accessing secrets.

Examples:

# Login with specific fingerprint
dotsecenv login E60A1740BAEF49284D22EA7D3C376348F0921C59

# Auto-detect fingerprint (bash)
dotsecenv login $(gpg --list-secret-keys --keyid-format long | \
  grep -oP '(?<=sec\s{3}rsa4096/)[A-F0-9]+' | head -1)

---

secret

Manage secrets in the vault.

secret get

Retrieve a secret value from the vault.

dotsecenv secret get SECRET [flags]

Secret key formats:

• Namespaced: namespace::KEY_NAME (e.g., myapp::DATABASE_URL)
• Non-namespaced: KEY_NAME (e.g., DATABASE_URL, APP.DOMAIN.ORG)

Options:

Flag	Description
--all	Retrieve all values for the secret
--last	Retrieve the most recent value across all vaults
--json	Output as JSON

Examples:

# Get a secret
dotsecenv secret get DATABASE_PASSWORD

# Get namespaced secret
dotsecenv secret get prod::API_KEY

# Get all versions
dotsecenv secret get DATABASE_PASSWORD --all

# Get as JSON
dotsecenv secret get DATABASE_PASSWORD --json

# Get from specific vault
dotsecenv secret get -v 2 DATABASE_PASSWORD

secret put

Store an encrypted secret value.

dotsecenv secret put SECRET [flags]

Secret key formats:

• Namespaced: namespace::KEY_NAME (e.g., myapp::DATABASE_URL)
• Non-namespaced: KEY_NAME (e.g., DATABASE_URL, APP.DOMAIN.ORG)

Keys are case-insensitive and normalized when stored:

• Namespace part: lowercase
• Key name part: UPPERCASE

The secret value is read from stdin. Use -v to specify which vault to store the secret in.

Examples:

# Store a secret (pipe from echo)
echo "my-secret-value" | dotsecenv secret put DATABASE_PASSWORD

# Store a namespaced secret
echo "prod-password" | dotsecenv secret put prod::DATABASE_PASSWORD

# Store interactively (type value, then Ctrl+D)
dotsecenv secret put API_KEY

# Store from file
cat ~/.ssh/private_key | dotsecenv secret put SSH_PRIVATE_KEY

# Store in specific vault
echo "value" | dotsecenv secret put -v ./vault SECRET_NAME

secret share

Share a secret with another identity.

dotsecenv secret share SECRET FINGERPRINT [flags]

The secret will be re-encrypted so the target identity can decrypt it.

Options:

Flag	Description
--all	Share the secret in all vaults where it exists

Examples:

# Share a single secret
dotsecenv secret share DATABASE_PASSWORD E60A1740BAEF49284D22EA7D3C376348F0921C59

# Share in all vaults
dotsecenv secret share DATABASE_PASSWORD E60A1740... --all

# Share namespaced secret
dotsecenv secret share prod::API_KEY FINGERPRINT

secret revoke

Revoke access to a secret from an identity.

dotsecenv secret revoke SECRET FINGERPRINT [flags]

This removes the ability for the specified identity to decrypt the secret.

Caution

Revoking access only affects future values. The revoked identity can still decrypt previously shared values. Always rotate secrets after revoking access.

Options:

Flag	Description
--all	Revoke access from all vaults where the secret is shared

Examples:

# Revoke access to a secret
dotsecenv secret revoke DATABASE_PASSWORD FINGERPRINT

# Revoke from all vaults
dotsecenv secret revoke DATABASE_PASSWORD FINGERPRINT --all

# Then rotate the secret
echo "new-value" | dotsecenv secret put DATABASE_PASSWORD

secret forget

Mark a secret as deleted in the vault.

dotsecenv secret forget SECRET [flags]

This adds a deletion marker to the secret. The secret will no longer be returned by secret get and will be shown as deleted in vault list.

Note

The deletion is a soft delete — the secret’s history is preserved in the vault file. Use vault defrag to permanently remove deleted secrets.

Examples:

# Mark a secret as deleted
dotsecenv secret forget DATABASE_PASSWORD

# Delete from specific vault
dotsecenv secret forget -v 2 prod::API_KEY

# Delete using vault path
dotsecenv secret forget -v ./project/vault SECRET_NAME

Behavior after deletion:

• secret get SECRET — Returns error: “secret has been deleted”
• secret get --all — Skips values from vaults where the secret is deleted
• secret get --last — Does not consider deleted secrets
• vault list — Shows (deleted) next to the secret name

---

vault

Manage vaults.

vault list

List all configured vaults and the secrets they contain.

dotsecenv vault list [flags]

Options:

Flag	Description
--json	Output as JSON

Examples:

# List all vaults and secrets
dotsecenv vault list

# Output as JSON
dotsecenv vault list --json

# List specific vault
dotsecenv vault list -v 1

Sample output:

Vault 1 (~/.config/dotsecenv/vault):
  - DATABASE_PASSWORD
  - OLD_SECRET (deleted)
  - prod::API_KEY

vault defrag

Analyze vault fragmentation and optionally defragment.

dotsecenv vault defrag [flags]

Prompts to select a vault if multiple are configured. Use --dry-run to only show stats without making changes.

Options:

Flag	Description
--dry-run	Show fragmentation stats without defragmenting
--json	Output as JSON
-y, --yes	Skip confirmation prompt

Examples:

# Preview defragmentation
dotsecenv vault defrag --dry-run

# Defragment with confirmation
dotsecenv vault defrag

# Defragment without confirmation
dotsecenv vault defrag --yes

# Output stats as JSON
dotsecenv vault defrag --dry-run --json

vault identity add

Add an identity to one or more vaults.

dotsecenv vault identity add FINGERPRINT [flags]

The identity must have their GPG public key imported into your keyring first.

Options:

Flag	Description
--all	Add identity to all configured vaults

Examples:

# Add identity to default vault
dotsecenv vault identity add E60A1740BAEF49284D22EA7D3C376348F0921C59

# Add to all vaults
dotsecenv vault identity add FINGERPRINT --all

# Add to specific vault
dotsecenv vault identity add -v 2 FINGERPRINT

vault identity list

List all identities in the configured vaults.

dotsecenv vault identity list [flags]

Options:

Flag	Description
--json	Output as JSON

Examples:

# List identities
dotsecenv vault identity list

# Output as JSON
dotsecenv vault identity list --json

---

validate

Validate the vault and configuration files.

dotsecenv validate [flags]

Checks for:

• Config file syntax and validity
• Vault header integrity
• Identity entries
• Secret entries and signatures

Options:

Flag	Description
--fix	Attempt to fix any issues found

Examples:

# Validate configuration and vault
dotsecenv validate

# Validate and fix issues
dotsecenv validate --fix

# Validate specific vault
dotsecenv validate -v ./project/vault

Sample output:

✓ Config file: valid
✓ Vault header: valid
✓ Identity entries: 2 valid
✓ Secret entries: 5 valid
✓ All signatures verified

---

completion

Generate shell completion scripts for dotsecenv.

dotsecenv completion [bash|zsh|fish]

Bash

# Load for current session
source <(dotsecenv completion bash)

# Install permanently (Linux)
dotsecenv completion bash > /etc/bash_completion.d/dotsecenv

# Install permanently (macOS with Homebrew)
dotsecenv completion bash > $(brew --prefix)/etc/bash_completion.d/dotsecenv

Zsh

# Enable shell completion if not already enabled
echo "autoload -U compinit; compinit" >> ~/.zshrc

# Install completions
dotsecenv completion zsh > "${fpath[1]}/_dotsecenv"

# Restart shell

Fish

# Load for current session
dotsecenv completion fish | source

# Install permanently
dotsecenv completion fish > ~/.config/fish/completions/dotsecenv.fish

---

version

Show version information.

dotsecenv version [flags]

Options:

Flag	Description
--json	Output as JSON

Example output:

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

JSON output (--json):

{
  "version": "v0.2.1",
  "commit": "abc1234",
  "builtAt": "2025-01-15T10:30:00Z",
  "goBuildVersion": "go1.24.0",
  "crypto": {
    "GOFIPS140": "v1.0.0",
    "fips140Enabled": true
  }
}

---

Environment Variables

Variable	Description
DOTSECENV_CONFIG	Override config file path
GNUPGHOME	Override GPG home directory

---

Exit Codes

Code	Meaning
0	Success
1	General error
2	Invalid arguments
3	Config/vault not found
4	GPG error
5	Secret not found
6	Permission denied
7	Validation failed

---

Configuration File

Default location: ~/.config/dotsecenv/config (or $XDG_CONFIG_HOME/dotsecenv/config)

# Vault file path(s)
vault:
  - ~/.config/dotsecenv/vault

# Or with names:
vault:
  - name: personal
    path: ~/.config/dotsecenv/vault
  - name: work
    path: ~/work/secrets/vault

# Active user fingerprint
fingerprint: E60A1740BAEF49284D22EA7D3C376348F0921C59

# Approved algorithms (minimum strength)
approved_algorithms:
  - rsa:3072
  - ecdsa:p384
  - eddsa:ed25519

# Strict mode: treat warnings as errors
strict: false

# GPG executable path (absolute path required if specified)
gpg:
  program: /usr/bin/gpg

GPG Program Configuration

The gpg.program option specifies the path to the GPG executable:

Scenario	Behavior
gpg.program specified	Must be an absolute path to an existing, executable program
gpg.program empty/omitted	Infers gpg from PATH, prints warning to stderr
Strict mode + empty	Error: must be explicitly configured

Examples:

# Explicit path (recommended for strict mode)
gpg:
  program: /usr/bin/gpg

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

# Omit to infer from PATH (prints warning)
gpg:
  program: ""

---

See Also

• Getting Started — Quick setup guide
• First Secret Tutorial — Store your first secret
• Share a Secret — Team sharing workflow
• How-To Guides — Common tasks