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
identity	Manage GPG identities
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)
--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 login fingerprint
dotsecenv init config --login E60A1740BAEF49284D22EA7D3C376348F0921C59

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

When using -v with a configuration file present, dotsecenv validates the path against configured vaults. If restrict_to_configured_vaults is enabled, specifying a path not in your config results in an error. Otherwise, a warning is displayed.

Examples:

# Initialize vault(s) from config
dotsecenv init vault

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

---

login

Initialize your dotsecenv identity by selecting a GPG key. This creates a cryptographically signed proof that you control the secret key, stored in your configuration.

dotsecenv login [FINGERPRINT] [flags]

Arguments:

• FINGERPRINT (optional): GPG key fingerprint. If not provided, you’ll be prompted to select from available secret keys.

What happens:

1. Validates the GPG key exists and you have the secret key
2. Creates a signed login proof (timestamp + fingerprint + signature)
3. Stores the proof in your configuration file

This signed proof ensures that only someone with access to the secret key can configure dotsecenv to use it.

Examples:

# Interactive key selection (recommended)
dotsecenv login

# Specify fingerprint directly
dotsecenv login E60A1740BAEF49284D22EA7D3C376348F0921C59

---

identity

Manage GPG identities.

dotsecenv identity [command]

identity create

Generate a new GPG key for use with dotsecenv.

dotsecenv identity create [flags]

This command simplifies GPG key creation by providing sensible defaults while allowing customization for power users.

While dotsecenv’s philosophy aligns with Unix/POSIX tool composition, we felt that providing a simplified wrapper for GPG key generation is a net positive for users unfamiliar with GPG.

Options:

Flag	Description
--name	Your full name (prompts if not provided)
--email	Your email address (prompts if not provided)
--algo	Key algorithm: ED25519, RSA4096, P384 (default), P521
--template	Output GPG batch template instead of generating key
--no-passphrase	Create key without passphrase protection (for CI/automation only)

Key expiration:

Generated keys expire after 2 years by default. This is a security best practice - keys should be rotated periodically. If you need a different expiration, use --template to get the GPG batch template and modify the Expire-Date field before generating.

Supported algorithms:

Algorithm	Description
P384 (default)	NIST P-384 ECDSA curve
P521	NIST P-521 ECDSA curve
ED25519	EdDSA with Ed25519 curve
RSA4096	RSA 4096-bit key

Algorithm validation:

The requested algorithm must be allowed by your configuration’s approved_algorithms setting. If you request an algorithm that isn’t enabled, you’ll see an error:

Error: algorithm 'ED25519' is not allowed by your configuration

Your config only allows:
  - ECC (minimum 384 bits, curves: P-384, P-521)
  - RSA (minimum 2048 bits)

To use ED25519, add it to your config's approved_algorithms.
See https://dotsecenv.com/concepts/compliance/ for more details.

This ensures that generated keys comply with your organization’s cryptographic policies. See the Compliance page for more information.

About the --template flag:

Instead of generating the key directly, output a GPG batch template file. This allows you to:

• Review and customize the template before generation
• Execute key generation directly with GPG for maximum security
• Generate the key on an air-gapped machine
• Reduce attack surface by avoiding secret material handling in dotsecenv

Examples:

# Interactive key generation with defaults (P384)
dotsecenv identity create

# Specify name and email via flags
dotsecenv identity create --name "John Doe" --email "john@example.com"

# Use RSA 4096-bit key (if allowed by config)
dotsecenv identity create --algo RSA4096

# Output template for manual generation
dotsecenv identity create --template --name "John Doe" --email "john@example.com"
# Save this template to a file and run:
#   gpg --batch --generate-key key-params.txt

# CI/automation: create passwordless key (requires --name and --email)
dotsecenv identity create --name "CI Bot" --email "ci@example.com" --no-passphrase

---

secret

Manage secrets in the vault.

secret get

Retrieve a secret value from the vault, or list all secret keys.

dotsecenv secret get [SECRET] [flags]

Two modes of operation:

1. List mode (no arguments): Lists all secret keys from configured vaults
2. Get mode (with SECRET argument): Retrieves the secret value

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 (requires SECRET)
--last	Retrieve the most recent value across all vaults (requires SECRET)
--json	Output as JSON

Examples:

# List all secrets from all vaults
dotsecenv secret get

# List secrets from a specific vault
dotsecenv secret get -v 2

# List secrets as JSON
dotsecenv secret get --json

# Get a secret value
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

List mode output:

DATABASE_PASSWORD
prod::API_KEY
OLD_SECRET (deleted)

List mode JSON output (--json):

[
  {
    "key": "DATABASE_PASSWORD",
    "vault": "~/.local/share/dotsecenv/vault"
  },
  {
    "key": "prod::API_KEY",
    "vault": "~/.local/share/dotsecenv/vault"
  },
  {
    "key": "OLD_SECRET",
    "vault": "~/.local/share/dotsecenv/vault",
    "deleted": true
  }
]

secret store

Store an encrypted secret value.

dotsecenv secret store 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 store DATABASE_PASSWORD

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

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

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

# Store in specific vault
echo "value" | dotsecenv secret store -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 store 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 describe.

Note

The deletion is a soft delete — the secret’s history is preserved in the vault file. Use vault doctor (which offers defragmentation) 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 describe — Shows (deleted) next to the secret name

---

vault

Manage vaults.

vault describe

Describe all configured vaults showing their identities and secrets.

dotsecenv vault describe [flags]

Options:

Flag	Description
--json	Output as JSON

Examples:

# Describe all vaults
dotsecenv vault describe

# Output as JSON
dotsecenv vault describe --json

# Describe specific vault
dotsecenv vault describe -v 1

Sample output:

Vault 1 (~/.local/share/dotsecenv/vault):
  Identities:
    - Alice <alice@example.com> (ABC123...)
    - Bob <bob@example.com> (DEF456...)
  Secrets:
    - DATABASE_PASSWORD
    - OLD_SECRET (deleted)
    - prod::API_KEY

vault doctor

Run health checks on vaults and the GPG environment, and fix issues.

dotsecenv vault doctor [flags]

Performs the following checks:

• GPG agent availability - verifies gpg-agent is running
• Vault format version - checks if vaults need upgrading to the latest format
• Vault fragmentation - checks if vaults would benefit from defragmentation

After displaying health check results, the command offers to fix any issues found (upgrade outdated vaults, defragment fragmented vaults).

CI Environment Detection

In CI environments (CI=true, GITHUB_ACTIONS, GITLAB_CI, JENKINS_URL, CIRCLECI, etc.), interactive prompts are automatically skipped to avoid blocking pipelines. Use --json for machine-readable output in CI.

Options:

Flag	Description
--json	Output as JSON

Examples:

# Run health checks
dotsecenv vault doctor

# Output as JSON (useful for CI)
dotsecenv vault doctor --json

# Check specific vault
dotsecenv vault doctor -v 1

Sample output:

Health checks:
  [✓] gpg-agent is available
  [✓] ~/.local/share/dotsecenv/vault: format v2 (latest)
  [!] /var/lib/dotsecenv/vault: format v1 (latest: v2)
  [✓] ~/.local/share/dotsecenv/vault: 0.0% fragmentation

Status: warning

Upgrade vault /var/lib/dotsecenv/vault from v1 to v2? [y/N]:

vault upgrade

Upgrade vault file format to the latest version.

dotsecenv vault upgrade [flags]

When behavior.require_explicit_vault_upgrade is set to true in your config, automatic vault upgrades are disabled. Use this command to explicitly upgrade vault formats.

Examples:

# Upgrade vault (prompts if multiple vaults configured)
dotsecenv vault upgrade

# Upgrade specific vault
dotsecenv vault upgrade -v 1

# Upgrade vault at path
dotsecenv vault upgrade -v ./project/vault

vault upgrade

Upgrade vault file format to the latest version.

dotsecenv vault upgrade [flags]

When behavior.require_explicit_vault_upgrade is set to true in your config, automatic vault upgrades are disabled. Use this command to explicitly upgrade vault formats.

Examples:

# Upgrade vault (prompts if multiple vaults configured)
dotsecenv vault upgrade

# Upgrade specific vault
dotsecenv vault upgrade -v 1

# Upgrade vault at path
dotsecenv vault upgrade -v ./project/vault

---

validate

Validate the vault and configuration files.

dotsecenv validate [flags]

Breaking Change in v0.4

v0.4 changed the hash computation format to improve security. Secrets created with v0.3.x will fail validation with “hash mismatch” errors.

To fix existing vaults:

1. Each user must re-sign their own secret values (one user cannot edit another’s values):

   # For each secret you created
   dotsecenv secret get SECRET_KEY | dotsecenv secret store SECRET_KEY

2. After re-signing, edit the vault file manually to remove old values that no longer validate. Look for entries where the hash field fails verification and delete those value blocks.

3. Commit the updated vault file.

This is a one-time migration. New secrets created with v0.4+ will validate correctly.

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.4.6
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	Configuration error
3	Vault error
4	GPG error
5	Authentication error (not logged in)
6	Validation failed
7	Fingerprint required
8	Access denied
9	Algorithm not allowed

---

Configuration File

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

# Approved algorithms (minimum strength)
approved_algorithms:
  - algo: ECC
    curves: [P-384, P-521]
    min_bits: 384
  - algo: EdDSA
    curves: [Ed25519, Ed448]
    min_bits: 255
  - algo: RSA
    min_bits: 2048

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

# Active user fingerprint
fingerprint: E60A1740BAEF49284D22EA7D3C376348F0921C59

# Behavior settings (all default to false)
behavior:
  require_explicit_vault_upgrade: false
  restrict_to_configured_vaults: false

# GPG executable path
gpg:
  program: /usr/bin/gpg

Behavior Settings

Granular settings that control how dotsecenv handles edge cases. See Behavior Settings for full documentation.

Setting	Default	Description
require_explicit_vault_upgrade	false	Prevent automatic vault format upgrades; requires vault upgrade command
restrict_to_configured_vaults	false	Ignore CLI -v flags; only use vaults from config file

GPG Program Configuration

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

Value	Behavior
PATH	Infer GPG location from system PATH
/absolute/path	Use the specified absolute path
Empty/missing	Error: must be explicitly configured

Examples:

# Infer from system PATH (recommended default)
gpg:
  program: PATH

# Explicit absolute path
gpg:
  program: /usr/bin/gpg

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

---

See Also

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