dottie (pronounced dotty) makes .env files maintainable at scale.

Most teams start with a small .env, then over time it becomes hard to review, risky to edit, and difficult to keep in sync across environments. Dottie turns .env from a plain text dump into a structured, validated, automatable configuration document.

• Safer changes — validate values before they ship (e.g. URL, number, email, required values).
• Less drift — update local .env files from an upstream template while preserving local values.
• Better readability — keep sections, comments, formatting, and optional/disabled values organized.
• Automation-friendly — query values, print JSON, or render custom docs/templates from the .env model.
• Team-friendly workflows — treat .env as code with predictable formatting and command-driven edits.

• Create and update values with comments, quote styles, ordering, and groups.
• Enable/disable keys without losing the original value.
• Validate values using annotation-based rules.
• Format files for consistent style.
• Print in multiple styles (compact, pretty, export, filtered, with/without disabled keys).
• Read specific values as literal or interpolated output.
• List groups and inspect file structure.
• Export JSON for external tooling.
• Render templates for generated docs or config artifacts.

• Annotations in comments (e.g. @dottie/validate, @dottie/source) attach metadata to keys.
• Groups organize keys into logical sections.
• Interpolation resolves references like ${PORT} when desired.
• Disabled keys are preserved as commented assignments and can be re-enabled later.
• Upstream source templates let you evolve defaults without overwriting local intent.

# Create a new `.env` file
touch .env

# Create a key/value pair
dottie set my_key=value

# Create another key (PORT) with value "3306"
#  * One comment
#  * One validation rule that the value must be a number
#  * "none" quote style from the default "double"
dottie set \
  --comment 'A port for some service' \
  --comment '@dottie/validate number' \
  --quote-style none \
  PORT=3306

# Check validation (success)
dottie validate

# Print the file
dottie print

# Print the file (but pretty)
dottie print --pretty

# Change the "PORT" value to a "test" (a non-number).
# NOTE: the comments are kept in the file, even if they are omitted here
dottie set PORT=test

# Test validation again (it now fails)
dottie validate

# Fix the port value
dottie set PORT=3306

# Create a new key/value pair in a group named "database"
# NOTE: the group will be created on-demand if it does not exist
dottie set \
  --group database \
  --comment 'the hostname to the database' \
  DB_HOST="db"

# Create a "DB_PORT" key pair in the same "database" group as before
# NOTE: this value refers to the 'PORT' key we set above via interpolation
dottie set \
  --group database \
  --comment 'the port for the database' \
  --comment '@dottie/validate number' \
  DB_PORT='${PORT}'

# Print the file again
dottie print --pretty

# Disable the DB_PORT key
dottie disable DB_PORT

# Print the file again
# NOTE: the DB_PORT key/value is now gone
dottie print --pretty

# Print the file again, but include commented disabled keys
# NOTE: the DB_PORT key/value is printed (but still disabled)
dottie print --pretty --with-disabled

# Enable the DB_PORT key again
dottie enable DB_PORT

This flow shows the core Dottie lifecycle:

1. Create and annotate keys (set + comments + validation rules)
2. Validate correctness (validate)
3. Inspect output in different modes (print, value, json)
4. Temporarily toggle behavior (disable / enable)
5. Keep everything readable and consistent over time (fmt, update)

brew install jippi/tap/dottie

echo 'deb [trusted=yes] https://pkg.jippi.dev/apt/ * *' | sudo tee /etc/apt/sources.list.d/dottie.list
sudo apt update
sudo apt install dottie

echo '[dottie]
name=dottie
baseurl=https://pkg.jippi.dev/yum/
enabled=1
gpgcheck=0' | sudo tee /etc/yum.repos.d/dottie.repo
sudo yum install dottie

sudo snap install dottie

scoop bucket add dottie https://github.com/jippi/scoop-bucket.git
scoop install dottie

yay -S dottie-bin

Download the .deb, .rpm or .apk packages from the releases page and install them with the appropriate tools.

go install github.com/jippi/dottie@latest

All artifacts are checksummed, and the checksum file is signed with cosign.

1. Download the files you want, and the checksums.txt, checksum.txt.pem and checksums.txt.sig files from the releases page:

2. Verify the signature:

   cosign verify-blob \
     --certificate-identity 'https://github.com/jippi/dottie/.github/workflows/release.yml@refs/tags/v1.0.0' \
     --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
     --cert 'https://github.com/jippi/dottie/releases/download/v1.0.0/checksums.txt.pem' \
     --signature 'https://github.com/jippi/dottie/releases/download/v1.0.0/checksums.txt.sig' \
     ./checksums.txt

3. If the signature is valid, you can then verify the SHA256 sums match with the downloaded binary:

   sha256sum --ignore-missing -c checksums.txt

Our Docker images are signed with cosign.

Verify the signatures:

cosign verify \
  --certificate-identity 'https://github.com/jippi/dottie/.github/workflows/release.yml@refs/tags/v1.0.0' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  jippi/dottie

Quick navigation:

• Annotation Reference
• Global Flags
• Manipulation Commands
  • dottie set
  • dottie update
  • dottie fmt
  • dottie disable
  • dottie enable
  • dottie exec
  • dottie shell
• Output Commands
  • dottie print
  • dottie validate
  • dottie value
  • dottie groups
  • dottie json
  • dottie template
• Additional Commands
  • dottie completion

All commands support the following global flags:

↑ Back to Commands

Set/update one or multiple key=value pairs.

Related: Annotation Reference

dottie set KEY=VALUE [KEY=VALUE ...] [flags]

$ dottie set \
    --comment 'The port for the web server' \
    --comment '@dottie/validate number' \
    --quote-style none \
    PORT=8080
Key [ PORT ] was successfully upserted
File was successfully saved

# The port for the web server
# @dottie/validate number
PORT=8080

$ dottie set --group database --comment 'Database hostname' DB_HOST=localhost
Key [ DB_HOST ] was successfully upserted
File was successfully saved

################################################################################
# database
################################################################################

# Database hostname
DB_HOST="localhost"

$ dottie set PORT=hello
  PORT ( .env:5 )
    * (number) The value [hello] is not a valid number.

Error: Key: 'PORT' Error:Field validation for 'PORT' failed on the 'number' tag

↑ Back to Commands

Update the .env file from a source.

Related: Annotation Reference

dottie update [flags]

# @dottie/source https://example.com/template.env

APP_NAME="my-app"
DB_HOST="localhost"

dottie update --source https://example.com/template.env

↑ Back to Commands

Format a .env file. Ensures consistent spacing by adding blank lines between key/value groups, especially before comment blocks.

dottie fmt [flags]

KEY1=hello
# Comment for KEY2
KEY2=world
# Comment for KEY3
KEY3=test

$ dottie fmt
File was successfully formatted

KEY1=hello

# Comment for KEY2
KEY2=world

# Comment for KEY3
KEY3=test

↑ Back to Commands

Disable (comment out) a KEY if it exists. The key is prefixed with # to comment it out, making it invisible to normal print output while preserving the value for later re-enabling.

dottie disable KEY [flags]

APP_NAME="dottie"

# Database port
DB_PORT="3306"

$ dottie disable DB_PORT
Key [ DB_PORT ] was successfully disabled

APP_NAME="dottie"

# Database port
#DB_PORT="3306"

↑ Back to Commands

Enable (uncomment) a KEY if it exists. Removes the leading # from a previously disabled key, making it active again.

dottie enable KEY [flags]

# Database port
#DB_PORT="3306"

$ dottie enable DB_PORT
Key [ DB_PORT ] was successfully enabled

# Database port
DB_PORT="3306"

↑ Back to Commands

Run update logic against a source without forcing a file write. This is useful for checks, previews, CI validation, and troubleshooting update behavior before persisting changes.

dottie exec [flags]

dottie exec --source https://example.com/.env.template --no-save

↑ Back to Commands

Start an interactive dottie shell for exploring and working with your .env file in a REPL-style workflow.

dottie shell [flags]

Use this when you prefer an interactive session over one-off commands, especially while iterating on config changes.

↑ Back to Commands

Print environment variables.

dottie print [flags]

APP_NAME="dottie"

# The port for the web server
# @dottie/validate number
PORT=8080

################################################################################
# database
################################################################################

# Database hostname
DB_HOST="localhost"

# Database port
# @dottie/validate number
DB_PORT="${PORT}"

$ dottie print
APP_NAME="dottie"
PORT=8080
DB_HOST="localhost"
DB_PORT="8080"

$ dottie print --pretty
APP_NAME="dottie"

# The port for the web server
# @dottie/validate number
PORT=8080

################################################################################
# database
################################################################################

# Database hostname
DB_HOST="localhost"

# Database port
# @dottie/validate number
DB_PORT="8080"

$ dottie print --export
export APP_NAME="dottie"
export PORT=8080
export DB_HOST="localhost"
export DB_PORT="8080"

$ dottie print --group database
DB_HOST="localhost"
DB_PORT="8080"

$ dottie print --key-prefix DB_
DB_HOST="localhost"
DB_PORT="8080"

↑ Back to Commands

Validate a .env file.

Validation rules come from @dottie/validate annotations. See @dottie/validate Reference.

dottie validate [flags]

# @dottie/validate number
PORT=hello

# @dottie/validate email
ADMIN_EMAIL=not-an-email

# @dottie/validate required
API_KEY=

$ dottie validate --no-fix
┌──────────────────────────────────────────────────────────────────────────────┐
│                          3 validation errors found                           │
└──────────────────────────────────────────────────────────────────────────────┘

PORT (.env:2)
    * (number) The value [hello] is not a valid number.

ADMIN_EMAIL (.env:5)
  * (email) The value [not-an-email] is not a valid e-mail address.

API_KEY (.env:8)
  * (required) This value is required and cannot be empty.

$ dottie validate
┌──────────────────────────────────────────────────────────────────────────────┐
│                          No validation errors found                          │
└──────────────────────────────────────────────────────────────────────────────┘

↑ Back to Commands

Print the value of a .env key if it exists.

dottie value KEY [flags]

# Interpolated value (default) - resolves variable references
$ dottie value DB_PORT
8080

# Literal value - shows the raw value as written in the file
$ dottie value DB_PORT --literal
${PORT}

$ dottie value DB_PORT
Error: key [ DB_PORT ] exists, but is commented out - use [--with-disabled] to include it

$ dottie value DB_PORT --with-disabled
8080

↑ Back to Commands

Print groups found in the .env file. Groups are defined by section headers using the banner format.

dottie groups [flags]

APP_NAME="dottie"

################################################################################
# database
################################################################################

DB_HOST="localhost"

$ dottie groups
┌──────────────────────────────────────────────────────────────────────────────┐
│                              Groups in .env                                  │
└──────────────────────────────────────────────────────────────────────────────┘
database   (.env:4)

↑ Back to Commands

Print the .env file as JSON. Outputs a structured JSON representation including keys, values, comments, annotations, groups, variable dependencies, and position information.

dottie json [flags]

# @dottie/validate number
PORT=8080

DB_PORT="${PORT}"

dottie json

{
  "statements": [
    {
      "key": "PORT",
      "literal": "8080",
      "enabled": true,
      "quote": null,
      "comments": [
        {
          "value": "# @dottie/validate number",
          "annotation": { "Key": "dottie/validate", "Value": "number" }
        }
      ],
      "dependents": {
        "DB_PORT": { "key": "DB_PORT", "literal": "${PORT}" }
      }
    },
    {
      "key": "DB_PORT",
      "literal": "${PORT}",
      "enabled": true,
      "quote": "double",
      "dependencies": {
        "PORT": { "Name": "PORT" }
      }
    }
  ]
}

↑ Back to Commands

Render a template from a .env file model.

dottie template [flags] TEMPLATE_FILE

{{ range .Groups }}
## {{ .String | title }}
{{ range .Assignments }}
### {{ .Name | title }} { data-toc-label="{{ .Name }}" }
{{ if .Annotation "dottie/validate" | first | default "" | contains "required" }}
<!-- md:flag required -->
{{ end }}
{{ if eq .Literal "" }}
<!-- md:default none -->
{{ else if eq .Literal .Interpolated }}
<!-- md:default `{{ .Interpolated | trim }}` -->
{{ else }}
<!-- md:default computed:`{{ .Literal | trim }}` -->
{{ end }}
{{ with .Documentation true }}{{ . | trim }}{{ end }}
{{ with .Annotation "dottie/validate" }}
**Validation rules:** `{{ . | first | trim }}`
{{ end }}
{{ end }}
{{ end }}

dottie template --file .env.docker docs-customization/template/dot-env.template.tmpl > docs/generated/env-settings.md

## App

### App Name { data-toc-label="APP_NAME" }
<!-- md:flag required -->
<!-- md:default none -->
The name/title for your site
Validation rules: `required,ne=My Pixelfed Site`

### App Url { data-toc-label="APP_URL" }
<!-- md:default computed:`https://${APP_DOMAIN}` -->
This URL is used by the console to properly generate URLs.
Validation rules: `required,http_url`

↑ Back to Commands

Generate shell completion scripts so dottie subcommands and flags can be tab-completed in your terminal.

dottie completion [bash|zsh|fish|powershell]

# bash
source <(dottie completion bash)

# zsh
source <(dottie completion zsh)

dottie completion zsh > ~/.zsh/completions/_dottie

Annotations are comment lines with this format:

# @<annotation-key> <annotation-value>

In Dottie, annotations are parsed from comments and attached to the following assignment (or treated as document-level config where relevant).

Declares the default source file/URL used by dottie update and dottie exec when --source is not provided.

Syntax:

# @dottie/source <url-or-file-path>

Example:

# @dottie/source https://example.com/.env.template
APP_NAME="my-app"

Explainer:

• Use this when your project has a canonical upstream template.
• --source always overrides the annotation for that command run.

Defines the command used by dottie exec to compute/update the value for the annotated key.

Syntax:

# @dottie/exec <command>
KEY=""

Example:

# @dottie/exec ./scripts/git-sha.sh
APP_VERSION=""

Explainer:

• Command output is used as the assignment value.
• Keep one @dottie/exec annotation per assignment.

Marks an assignment as hidden from shell completion suggestions.

Syntax:

# @dottie/hidden
KEY="value"

Example:

# @dottie/hidden
INTERNAL_DEBUG_TOKEN="secret"

Explainer:

• Helps reduce noise for internal-only keys.
• The key still exists and behaves normally in file parsing/commands.

@dottie/validate attaches validation rules to the next assignment.

Syntax:

# @dottie/validate <rule>[,<rule>...]
KEY=value

Rules are evaluated by go-playground/validator/v10 via Dottie (validator.ValidateMap), so the annotation value is passed through as validator tags.

Tag syntax (from validator/v10):

• AND: separate rules with commas: required,email
• OR: separate alternatives with pipe: rgb|rgba
• Rule parameter: use =: min=3, oneof=dev staging prod
• Escaping separators in parameters:
  • Use 0x2C for literal comma in a parameter value
  • Use 0x7C for literal pipe in a parameter value

Validator tags Dottie can use well (for scalar .env values):

Examples:

# @dottie/validate required,oneof=dev staging production
APP_ENV=dev

# @dottie/validate required_if=QUEUE_DRIVER sqs
SQS_QUEUE=

# @dottie/validate required,dir
STORAGE_PATH=/var/lib/myapp

# @dottie/validate omitempty,oneof=debug info warn error
LOG_LEVEL=info

# @dottie/validate required,email|fqdn
CONTACT=ops@example.com

Notes:

• Multiple rules are comma-separated.
• Alternative rules can be expressed with | (OR logic).
• dottie validate --ignore-rule <tag> can suppress a specific failing tag (for example dir).
• Invalid rule names (for example invalid-rule) are treated as validation configuration errors.
• Dottie delegates rule behavior to validator/v10; exact availability follows the validator version in Dottie.
• port is currently not safe for .env string values with upstream validator/v10 in Dottie (it triggers a validation configuration error).
• Validator reference: https://pkg.go.dev/github.com/go-playground/validator/v10

• Use required_if for value-based conditions
  • Example: required_if=QUEUE_DRIVER sqs means “required only when QUEUE_DRIVER is exactly sqs”.
• Use required_with for presence-based conditions
  • Example: required_with=MAIL_DRIVER means “required when MAIL_DRIVER is set to any non-empty value”.
• Cross-field rules depend on key names
  • Tags like required_if and required_with reference other assignment keys by name; typos in key names make rules behave unexpectedly.
• omitempty short-circuits the rest of the tag chain
  • omitempty,email passes on empty values, but validates as email when a value is provided.
• OR (|) only applies inside the same tag expression
  • email|fqdn means either format is accepted; combine with commas for additional required checks (e.g. required,email|fqdn).

Decision table:

# @dottie/source https://example.com/.env.template

# @dottie/validate required,number
PORT=3306

# @dottie/exec ./scripts/resolve-version.sh
APP_VERSION=""

# @dottie/hidden
INTERNAL_DEBUG_TOKEN="secret"

• @dottie/validate supports validator tags (for example: required, number, email, boolean, oneof, dir, file, fqdn, hostname, http_url, ne, and more).
• @dottie/exec expects exactly one exec annotation per assignment.
• Any non-dottie/* annotation is still parsed and preserved, but has no built-in command behavior unless consumed by your own tooling/templates.

To compile the module yourself, you can set up this repository for development.

You will need:

• Git
• Go

1. Clone the repository:

git clone https://github.com/jippi/dottie.git
cd dottie

1. Build the module:

go build

1. Build the docker container:

docker build --file Dockerfile.release --tag ghcr.io/jippi/dottie:v0.15.1 .