dotfill 1.3.0

Local-only helper to populate and maintain a personal .env file with API tokens and identity variables

dotfill

dotfill is a local-only helper for maintaining token and identity variables in a personal .env file. It runs a Python CLI plus a localhost web UI, reads TOML configuration, and writes only after explicit user action.

Generic dotfill ships with no services, identities, domains, token names, or import aliases. A user config or a wrapper package supplies those definitions.

Installation

For CLI use, install dotfill as an isolated tool:

uv tool install dotfill

or:

pipx install dotfill

For use as a library or project dependency:

uv add dotfill

or:

pip install dotfill

dotfill requires Python 3.14 or newer.

Quick Start

dotfill status
dotfill
dotfill config path
dotfill config open

Useful options:

dotfill --config-root C:\tmp\dotfill-config --profile demo status
dotfill --env-path C:\work\project\.env

First Config From An Existing .env

For individual use, install dotfill directly and create your own config.toml. If you already have a .env, a practical first setup path is to make a copy, remove the secret values, then ask an AI coding agent to draft config.toml from the sanitized variable names using dotfill's public docs.

Do not give API tokens or other secrets to the agent. Keep only variable names and non-secret comments, for example GITHUB_TOKEN= or GITHUB_TOKEN=<redacted>. Review the generated service URLs, test URLs, auth mode, identities, and derived variables before using the config against your real .env.

See Getting started for a suggested prompt and review checklist.

Documentation

• Getting started walks through the first config and dashboard run.
• TOML config schema is the full user-facing config reference.
• Troubleshooting covers common setup, config, import, and service-test issues.

Maintainer requirements, design notes, and implementation tracking live under dev/docs/.

Configuration

dotfill loads two optional TOML files from the resolved config directory:

config_common.toml
config.toml

config_common.toml is intended for managed baseline configuration. config.toml is intended for user-owned overrides. Both files must include version = 1 when present.

See docs/config-schema.md for the complete schema.

Default config root:

platformdirs.user_config_dir("dotfill", appauthor=False, roaming=True)

Profiles live under profiles/<name> inside the config root.

Example:

version = 1
name = "Example profile"

[target]
default_env_path = "~/.env"

[identities.WORK_EMAIL]
source = "literal"
value = "[e-mail]"

[identities.WORK_USER]
source = "local_part"
from = "WORK_EMAIL"

[derived.WORK_USERNAME]
from_identity = "WORK_EMAIL"

[services.EXAMPLE]
display_name = "Example"
token_var = "EXAMPLE_TOKEN"
token_url = "https://service.example.com/users/{WORK_USER}/tokens"
test_url = "https://service.example.com/me"
tls_verify = true
icon = "key"

[services.EXAMPLE.auth]
kind = "bearer"

[import_aliases.OLD_EXAMPLE_TOKEN]
target = "EXAMPLE_TOKEN"

Set enabled = false in config.toml to disable an inherited service, identity, derived variable, or import alias.

.env Behavior

The target .env contains ordinary environment values only. dotfill no longer reads legacy service or derived-variable meta-configuration from .env; those assignments are unrelated content unless their exact names are explicitly configured as managed variables in TOML.

The parser/writer preserves comments, blank lines, unrelated variables, unrelated duplicates, and line endings. Duplicate managed variables are rejected before writes.

Local UI

dotfill starts a server bound to 127.0.0.1, opens the dashboard, and serves static assets from the installed package. The dashboard can:

• show configured identities, derived variables, services, config directory, and target .env;
• save service tokens;
• fill missing enabled derived variables during token saves and import commits;
• fill or reset individual derived variables to their computed defaults;
• import token/derived values from another .env-like file;
• test configured service tokens on explicit user action.

When no services are configured, the dashboard shows an empty generic state.

Privacy

• No cloud backend, accounts, telemetry, or remote sync.
• Raw token values are not returned by state/import APIs.
• Dropped import values are kept only in backend session memory as secret values.
• The browser keeps session and token input in memory only; no browser storage is used.
• Service tests support configured bearer, header API-key, and basic auth requests only to configured test URLs.
• Service tests verify TLS by default. Use tls_verify = false only when a configured service explicitly requires it.

Wrapper Packages

Wrapper packages are for sharing baked-in dotfill defaults with other people. For example, a team wrapper can provide managed config_common.toml content so teammates get the same services, token variable names, identity rules, import aliases, and profile policy without each person hand-writing the same TOML.

If you are using dotfill only for yourself, you usually do not need a wrapper. Install dotfill directly and create your own config.toml, profiles, services, identities, and aliases.

Wrappers launch dotfill through:

from dotfill.entrypoints import run_dotfill

raise SystemExit(
    run_dotfill(
        locked_profile="team",
        before_config_load=sync_managed_config,
    )
)

Use locked_profile when the wrapper command should always mean one profile. Use default_profile only when CLI --profile or DOTFILL_PROFILE should be allowed to select another profile. Wrappers should not import the Typer app directly. User overrides remain in config.toml.

For a complete sample wrapper repo, see dotfill-wrapper-example.

Development

From a source checkout:

uv sync
uv run pytest
uv run dotfill status
uv build

If the virtual environment is activated, dotfill --help works directly. Without activation, use uv run dotfill ... or .\.venv\Scripts\dotfill.exe ....