CLI Reference
Complete reference for all dotsecenv commands. Use dotsecenv --help or dotsecenv <command> --help for inline help.
Global Options
Section titled “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) |
--no-pinentry |
Disable GPG pinentry prompts; fail if user interaction is required |
-h, --help |
Show help for command |
Calls to dotsecenv use your GPG pinentry configuration. The Claude Code and
Codex skills add --no-pinentry to their calls. See
GPG Agent: agent calls for the flag’s behavior
and recovery guidance.
dotsecenv
Section titled “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
Section titled “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 |
Initialize configuration or vault files.
init config
Section titled “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: ECC P-384+, EdDSA Ed25519/Ed448. RSA is not included; see RSA keys are legacy. New keys from identity create default to P-384, which NIST approves for both signing and encryption.
Options:
| Flag | Description |
|---|---|
--gpg-program PATH |
Set gpg.program to this absolute path (without validation). Defaults to PATH, which resolves the gpg binary from the system PATH at runtime. |
--login FINGERPRINT |
Initialize config with specified fingerprint |
Examples:
# Create default config (FIPS-compliant by default).# gpg.program is set to "PATH" (resolved from system PATH at runtime).dotsecenv init config
# Create config at custom locationdotsecenv init config -c ~/my-project/dotsecenv.yaml
# Pin GPG to an absolute path (skips runtime PATH lookup)dotsecenv init config --gpg-program /usr/local/bin/gpg
# Initialize with login fingerprintdotsecenv init config --login E60A1740BAEF49284D22EA7D3C376348F0921C59init vault
Section titled “init vault”Initialize vault file(s).
dotsecenv init vault [flags]Two modes of operation:
- With
-v PATH: Initialize a specific vault file at the given path - 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 configdotsecenv init vault
# Initialize specific vaultdotsecenv init vault -v ~/project/secrets/vaultinit secenv
Section titled “init secenv”Add references for your vault secrets to the .secenv file in the current directory. In a terminal this opens an interactive picker, one tab per vault. Without a terminal, or with --all or --silent, it adds every reference that is not already present.
dotsecenv init secenv [flags]It writes references (KEY={dotsecenv/...}), never plaintext values, and never overwrites a key already in .secenv. A key that is already present is skipped with a warning that --silent mutes.
Picker keys:
| Key | Action |
|---|---|
← / → |
Switch vault tabs (the last tab is Apply) |
↑ / ↓ |
Move within a tab |
space |
Toggle the key under the cursor |
ctrl+a / ctrl+n / ctrl+r |
Select all / none / reverse, current tab only |
enter |
Advance to Apply, then confirm and write |
esc / ctrl+c |
Cancel |
Options:
| Flag | Description |
|---|---|
--all |
Add every not-present reference without prompting (warnings still shown) |
-v PATH or -v INDEX |
Restrict to specific vaults; works in both modes |
Reference derivation:
| Vault key | .secenv line |
|---|---|
DATABASE_PASSWORD |
DATABASE_PASSWORD={dotsecenv/} |
prod::DB_PASSWORD |
PROD_DB_PASSWORD={dotsecenv/prod::DB_PASSWORD} |
Namespaced keys are prefixed, with :: becoming _, so two namespaces that share a key name do not collide.
Examples:
# Pick interactively (in a terminal)dotsecenv init secenv
# Add every reference not already presentdotsecenv init secenv --all
# Restrict to one vaultdotsecenv init secenv -v 2 --all
# No terminal: adds everything automaticallyecho | dotsecenv init secenvInitialize 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:
- Validates the GPG key exists and you have the secret key
- Creates a signed login proof (timestamp + fingerprint + signature)
- 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 directlydotsecenv login E60A1740BAEF49284D22EA7D3C376348F0921C59identity
Section titled “identity”Manage GPG identities.
dotsecenv identity [command]identity create
Section titled “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: P384 (default), P521, ED25519, RSA4096 (legacy) |
--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 signing, ECDH encryption |
P521 |
NIST P-521: ECDSA signing, ECDH encryption |
ED25519 |
EdDSA signing, X25519 encryption. X25519 is not NIST-approved |
RSA4096 (legacy) |
RSA 4096-bit key. Not in the default approved_algorithms |
P384 is the default because NIST approves both of its algorithms: ECDSA for signatures (FIPS 186-5) and ECDH for encryption. ED25519 signatures are FIPS 186-5 approved too, but FIPS 140-3 does not approve its X25519 encryption subkey for key agreement.
RSA is legacy. OpenPGP encrypts to RSA keys with PKCS #1 v1.5 padding, which Go deprecated in 1.26, so the default config rejects --algo RSA4096 and the error explains how to opt in. With RSA allowed, identity create still prints a warning before generating the key. See RSA keys are legacy.
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)
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 flagsdotsecenv identity create --name "John Doe" --email "john@example.com"
# Use a P-521 keydotsecenv identity create --algo P521
# Output template for manual generationdotsecenv 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-passphraseidentity add
Section titled “identity add”Add an existing GPG identity to one or more vaults by fingerprint.
dotsecenv identity add FINGERPRINT [flags]This is useful for onboarding new team members or pre-authorizing keys before sharing secrets. If the identity already exists in a vault it is skipped.
Arguments:
FINGERPRINT: GPG key fingerprint of the identity to add
Options:
| Flag | Description |
|---|---|
--all |
Add identity to all configured vaults |
-v |
Target vault (path or 1-based index) |
When neither --all nor -v is specified, the vault is auto-selected if only
one is configured, or you are prompted to choose interactively.
The identity’s public key is fetched from GPG, validated against the
configured approved_algorithms, and appended to the vault. The entry is
signed by the current user’s key (the person running the command), so you
do not need the target’s private key. Their public key in your GPG keyring is
enough.
Examples:
# Add an identity to the only configured vaultdotsecenv identity add E60A1740BAEF49284D22EA7D3C376348F0921C59
# Add to all configured vaultsdotsecenv identity add E60A1740BAEF49284D22EA7D3C376348F0921C59 --all
# Add to a specific vault by indexdotsecenv identity add E60A1740BAEF49284D22EA7D3C376348F0921C59 -v 2
# Add to a specific vault by pathdotsecenv identity add E60A1740BAEF49284D22EA7D3C376348F0921C59 -v ~/.config/dotsecenv/vault.jsonlsecret
Section titled “secret”Manage secrets in the vault.
secret get
Section titled “secret get”Retrieve a secret value from the vault, or list all secret keys.
dotsecenv secret get [SECRET] [flags]Two modes of operation:
- List mode (no arguments): Lists all secret keys from configured vaults
- Get mode (with SECRET argument): Retrieves the secret value
Get mode returns the value from the first configured vault that holds the secret, skipping any vault where it was forgotten.
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, newest first, including values that secret forget deleted (requires SECRET) |
--last |
Retrieve the most recent value across all vaults (requires SECRET) |
--json |
Output as JSON |
Examples:
# List all secrets from all vaultsdotsecenv secret get
# List secrets from a specific vaultdotsecenv secret get -v 2
# List secrets as JSONdotsecenv secret get --json
# Get a secret valuedotsecenv secret get DATABASE_PASSWORD
# Get namespaced secretdotsecenv secret get prod::API_KEY
# Get all versionsdotsecenv secret get DATABASE_PASSWORD --all
# Get as JSONdotsecenv secret get DATABASE_PASSWORD --json
# Get from specific vaultdotsecenv secret get -v 2 DATABASE_PASSWORDList mode output:
DATABASE_PASSWORDprod::API_KEYOLD_SECRET (deleted)A key shows as deleted only when every vault holding it has deleted it.
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 }]Get mode JSON output (SECRET --json):
{ "added_at": "2026-04-12T10:22:01Z", "value": "my-secret-value", "vault": "~/.local/share/dotsecenv/vault"}Get-all mode JSON output (SECRET --all --json):
Returns an array, newest-first, with available_to and signed_by per version for auditing access control across history. A value that a later secret forget in the same vault deleted carries "deleted": true; the text output marks it [deleted]. See Audit Trail for usage patterns.
[ { "added_at": "2026-04-12T10:22:01Z", "value": "my-secret-value", "vault": "~/.local/share/dotsecenv/vault", "available_to": ["ALICE_FP", "BOB_FP"], "signed_by": "ALICE_FP" }, { "added_at": "2026-02-03T14:08:55Z", "value": "previous-value", "vault": "~/.local/share/dotsecenv/vault", "available_to": ["ALICE_FP"], "signed_by": "ALICE_FP" }, { "added_at": "2025-11-20T09:15:40Z", "value": "forgotten-value", "vault": "~/.local/share/dotsecenv/vault", "available_to": ["ALICE_FP", "BOB_FP"], "signed_by": "BOB_FP", "deleted": true }]secret store
Section titled “secret store”Store an encrypted secret value.
dotsecenv secret store SECRET [flags]Storing over an existing secret keeps its current recipient set: the new value is encrypted to every fingerprint on the latest entry’s available_to, not just yours. Rotating a shared secret therefore never removes anyone’s access. To narrow access, use secret revoke (before or after storing).
When the kept recipient set includes identities other than yours, secret store warns and lists them. With a terminal attached it then asks for confirmation; declining cancels the store without writing anything. Without a terminal (piped input, CI) it proceeds after the warning. The --share and --no-share flags skip both the warning and the confirmation.
After secret forget, any identity in the vault can store the secret again. The new value is encrypted only to yours, and secret get never returns values from before the deletion.
Options:
| Flag | Description |
|---|---|
--share |
Keep the existing recipient set without warning or confirmation |
--no-share |
Encrypt the new value only to your identity |
--json |
Validate that stdin is valid JSON before storing |
--share and --no-share are mutually exclusive. Note that --no-share does not revoke anything by itself: prior entries stay readable to their recipients, and reads by those identities fall back to the newest entry they can decrypt.
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 secretecho "prod-password" | dotsecenv secret store prod::DATABASE_PASSWORD
# Store interactively (type value, then Ctrl+D)dotsecenv secret store API_KEY
# Store from filecat ~/.ssh/private_key | dotsecenv secret store SSH_PRIVATE_KEY
# Store in specific vaultecho "value" | dotsecenv secret store -v ./vault SECRET_NAME
# Rotate a shared secret, keeping the recipient set, without promptingecho "new-value" | dotsecenv secret store --share DATABASE_PASSWORD
# Rotate a shared secret for yourself onlyecho "new-value" | dotsecenv secret store --no-share DATABASE_PASSWORDsecret share
Section titled “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 secretdotsecenv secret share DATABASE_PASSWORD E60A1740BAEF49284D22EA7D3C376348F0921C59
# Share in all vaultsdotsecenv secret share DATABASE_PASSWORD E60A1740... --all
# Share namespaced secretdotsecenv secret share prod::API_KEY FINGERPRINTsecret revoke
Section titled “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.
Options:
| Flag | Description |
|---|---|
--all |
Revoke access from all vaults where the secret is shared |
Examples:
# Revoke access to a secretdotsecenv secret revoke DATABASE_PASSWORD FINGERPRINT
# Revoke from all vaultsdotsecenv secret revoke DATABASE_PASSWORD FINGERPRINT --all
# Then rotate the secretecho "new-value" | dotsecenv secret store DATABASE_PASSWORDsecret forget
Section titled “secret forget”Mark a secret as deleted in the vault.
dotsecenv secret forget SECRET [flags]This adds a deletion marker to the secret in one vault. secret get skips that vault and returns the secret from the next vault that holds it, if any, and vault describe shows it as deleted. Any identity can then store the secret again with secret store.
Options:
| Flag | Description |
|---|---|
--ignore-not-found |
Exit successfully if the secret is not found or already deleted (handy for idempotent scripts and CI) |
Examples:
# Mark a secret as deleteddotsecenv secret forget DATABASE_PASSWORD
# Delete from specific vaultdotsecenv secret forget -v 2 prod::API_KEY
# Delete using vault pathdotsecenv secret forget -v ./project/vault SECRET_NAME
# Idempotent delete: succeed even if the secret is absent or already deleteddotsecenv secret forget --ignore-not-found DATABASE_PASSWORDBehavior after deletion:
secret get SECRETskips the vault; when no other vault holds the secret, it returns the error “secret has been deleted”secret get --alllists the deleted values, marked[deleted](or"deleted": truewith--json)secret get --lastdoes not consider deleted valuessecret store SECRETworks for any identity and encrypts the new value only to the storervault describeshows(deleted)next to the secret name
Manage vaults.
vault describe
Section titled “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 vaultsdotsecenv vault describe
# Output as JSONdotsecenv vault describe --json
# Describe specific vaultdotsecenv vault describe -v 1Sample 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_KEYJSON output (--json):
available_to reflects the current authorization snapshot (the most-recent value’s recipients). It is omitted for deleted secrets and secrets with no values. See Audit Trail for query patterns.
[ { "position": 1, "vault": "~/.local/share/dotsecenv/vault", "identities": [ { "uid": "Alice <alice@example.com>", "fingerprint": "ABC123...", "algorithm": "RSA", "algorithm_bits": 4096, "created_at": "2026-01-04T08:14:32Z" } ], "secrets": [ { "key": "DATABASE_PASSWORD", "available_to": ["ABC123...", "DEF456..."] }, { "key": "OLD_SECRET", "deleted": true } ] }]vault doctor
Section titled “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
- Crypto module - reports the
GOFIPS140build setting, the FIPS 140-3 module version, and whether FIPS mode is disabled, enabled, or enforced (GODEBUG=fips140=only). This check is informational and never changes the overall status - Vault format version - checks if vaults need upgrading to the latest format
- Legacy RSA identities - warns when a vault holds RSA identities and lists them by UID and fingerprint.
--fixcan’t fix this: each owner creates a P-384 identity (theidentity createdefault) and the secrets are shared with it - 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). Use --fix to auto-fix without prompting. With behavior.require_explicit_vault_upgrade set, run it to upgrade outdated vaults.
Options:
| Flag | Description |
|---|---|
--fix |
Auto-fix issues without prompting |
--json |
Output as JSON |
Examples:
# Run health checksdotsecenv vault doctor
# Auto-fix issues (upgrade vaults, defragment) without promptingdotsecenv vault doctor --fix
# Output as JSON (useful for CI)dotsecenv vault doctor --json
# Check specific vaultdotsecenv vault doctor -v 1Sample output:
Health checks: [✓] gpg-agent is available [✓] crypto: GOFIPS140=v1.26.0 (module v1.26.0, FIPS 140-3 mode enabled) [✓] ~/.local/share/dotsecenv/vault: format v2 (latest) [!] .dotsecenv/vault: format v1 (latest: v2) [✓] ~/.local/share/dotsecenv/vault: 0.0% fragmentation
Status: warning
Upgrade vault .dotsecenv/vault from v1 to v2? [y/N]:vault compact
Section titled “vault compact”Drop superseded secret values to shrink a vault.
The runnable vault compaction example demonstrates a dry run, compaction, and validation in an isolated vault.
dotsecenv vault compact [flags]For each secret, compaction keeps the newest value every current identity can decrypt (exactly what secret get returns for that identity) and drops the rest. Deleted secrets are removed entirely. For a secret stored again after a deletion, compaction also drops every value up to and including the deletion. Values readable only by revoked fingerprints are dropped, since no current identity can read them.
Compaction never decrypts. It reads only access lists (available_to fingerprints) and value order, then rewrites the file preserving every kept value verbatim, so signatures stay valid. Identities are never touched.
Without --yes, the command prints the plan and asks for confirmation before writing. Confirmation is skipped automatically in CI.
Compaction records the running dotsecenv release in the vault header as dotsecenv_version. If a newer release created the vault or last rewrote it, the command warns you to upgrade dotsecenv, then continues.
Options:
| Flag | Description |
|---|---|
--yes |
Skip the confirmation prompt |
--json |
Output as JSON (writes only when combined with --yes) |
Examples:
# Show the plan, then confirm before writingdotsecenv vault compact
# Compact without prompting (also auto-skips the prompt in CI)dotsecenv vault compact --yes
# Preview the plan as JSON without writingdotsecenv vault compact --json
# Compact a specific vaultdotsecenv vault compact -v 1Sample output:
Vault: ~/.local/share/dotsecenv/vaultCompaction plan (metadata only, no decryption): AWS_KEY: 5 -> 1 value(s) DB_PASSWORD: 4 -> 1 value(s) TEMP_TOKEN: 2 value(s) -> removed (deleted)Total: 11 -> 2 value(s); 1 deleted secret(s) removeddoctor
Section titled “doctor”Run health checks on vaults and the GPG environment. This is a top-level alias for vault doctor, following the brew doctor / flutter doctor convention.
dotsecenv doctor [flags]Options:
| Flag | Description |
|---|---|
--fix |
Auto-fix issues without prompting |
--json |
Output as JSON |
Examples:
# Run health checksdotsecenv doctor
# Auto-fix issues without promptingdotsecenv doctor --fixSee vault doctor for the full list of checks and sample output.
validate
Section titled “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 vaultdotsecenv validate
# Validate and fix issuesdotsecenv validate --fix
# Validate specific vaultdotsecenv validate -v ./project/vaultSample output:
✓ Config file: valid✓ Vault header: valid✓ Identity entries: 2 valid✓ Secret entries: 5 valid✓ All signatures verifiedpolicy
Section titled “policy”Inspect and validate the system-wide policy directory at /etc/dotsecenv/policy.d/. See Security Policies for the full design.
Both subcommands are standalone. They don’t load the user config or open vaults, so they keep working when the policy itself is broken, which is when you most need to inspect it.
dotsecenv policy <subcommand> [flags]policy list
Section titled “policy list”Print the effective merged policy with per-field origin attribution.
dotsecenv policy list [--json]Options:
| Flag | Description |
|---|---|
--json |
Emit a structured JSON object instead of human-readable text |
Text output:
$ dotsecenv policy listPolicy directory: /etc/dotsecenv/policy.d (2 fragment(s)) approved_algorithms: - algo: ECC, curves: [P-384, P-521], min_bits: 384 [50-org-baseline.yaml] approved_vault_paths: - /srv/secrets/*/vault [50-org-baseline.yaml] behavior: restrict_to_configured_vaults: true [50-org-baseline.yaml] gpg.program: /usr/bin/gpg [99-overrides.yaml]When no policy is configured (/etc/dotsecenv/policy.d/ doesn’t exist):
$ dotsecenv policy listno policy in effect (/etc/dotsecenv/policy.d does not exist)JSON output:
dotsecenv policy list --json{ "dir": "/etc/dotsecenv/policy.d", "fragments": ["50-org-baseline.yaml", "99-overrides.yaml"], "approved_algorithms": [ { "entry": { "algo": "ECC", "curves": ["P-384", "P-521"], "min_bits": 384 }, "origins": ["50-org-baseline.yaml"] } ], "approved_vault_paths": [ { "pattern": "/srv/secrets/*/vault", "origins": ["50-org-baseline.yaml"] } ], "behavior": [ { "field": "restrict_to_configured_vaults", "value": true, "origin": "50-org-baseline.yaml" } ], "gpg": { "program": "/usr/bin/gpg", "origin": "99-overrides.yaml" }}policy validate
Section titled “policy validate”Parse all fragments and report structural errors. Designed for CI on the ops repo that ships your policy.
dotsecenv policy validate [--json]Options:
| Flag | Description |
|---|---|
--json |
Emit a structured JSON object on stdout (errors still affect exit code) |
Text output:
$ dotsecenv policy validate✓ policy valid (2 fragment(s) in /etc/dotsecenv/policy.d)JSON output (success):
{ "dir": "/etc/dotsecenv/policy.d", "valid": true, "fragment_count": 2}JSON output (failure):
{ "dir": "/etc/dotsecenv/policy.d", "valid": false, "fragment_count": 0, "error": { "exit_code": 8, "message": "policy fragment /etc/dotsecenv/policy.d/50-org.yaml has insecure permissions: mode 0666" }}Exit codes:
| Code | Condition |
|---|---|
0 |
Policy valid (or no policy in effect) |
1 |
Empty allow-list (e.g., approved_algorithms: []) |
2 |
Forbidden key (login, vault) or malformed YAML |
8 |
Insecure permissions or unreadable fragment |
completion
Section titled “completion”Generate shell completion scripts for dotsecenv.
dotsecenv completion [bash|zsh|fish]# Load for current sessionsource <(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# Enable shell completion if not already enabledecho "autoload -U compinit; compinit" >> ~/.zshrc
# Install completionsdotsecenv completion zsh > "${fpath[1]}/_dotsecenv"
# Restart shell# Load for current sessiondotsecenv completion fish | source
# Install permanentlydotsecenv completion fish > ~/.config/fish/completions/dotsecenv.fishversion
Section titled “version”Show version information.
dotsecenv version [flags]Options:
| Flag | Description |
|---|---|
--json |
Output as JSON |
Example output:
version: v0.2.1commit: abc1234build at: 2025-01-15T10:30:00Zgo version: go1.24.0crypto: GOFIPS140=v1.26.0 (module v1.26.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.26.0", "fips140ModuleVersion": "v1.26.0", "fips140Enabled": true, "fips140Enforced": false }}Environment Variables
Section titled “Environment Variables”| Variable | Description |
|---|---|
DOTSECENV_CONFIG |
Override config file path |
GNUPGHOME |
Override GPG home directory |
Exit Codes
Section titled “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
Section titled “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 # RSA is legacy and not in the defaults. To accept RSA keys anyway: # - algo: RSA # min_bits: 3072
# Vault file path(s)vault: - ~/.config/dotsecenv/vault
# Active user identity (signed login block, populated by `dotsecenv login <FP>`)login: fingerprint: E60A1740BAEF49284D22EA7D3C376348F0921C59 added_at: "2026-04-25T12:00:00Z" hash: "<sha-256 of 'login:<added_at>:<fingerprint>'>" signature: "<hex-encoded detached GPG signature of hash>"
# Behavior settings (all default to false)behavior: require_explicit_vault_upgrade: false restrict_to_configured_vaults: false
# GPG executable pathgpg: program: /usr/bin/gpgBehavior Settings
Section titled “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; upgrade with vault doctor |
restrict_to_configured_vaults |
false |
Ignore CLI -v flags; only use vaults from config file |
GPG Program Configuration
Section titled “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 pathgpg: program: /usr/bin/gpgSee Also
Section titled “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
- Security Policies: admin-pinned organization-wide rules
- How-To Guides: common tasks
