dotgoblin 0.2.0

CLI tool for managing environment variable hoards bound to named profiles or working directories.

dotgoblin

CLI tool for managing environment variable hoards bound to named profiles or working directories. Secrets stay off disk via shell interpolation at runtime.

Installation

With uv (recommended)

# Run directly without installing
uvx dotgoblin --help

# Install globally
uv tool install dotgoblin

# Install from source
uv tool install .

# Or add to a project
uv add dotgoblin

With pip

pip install dotgoblin

From source

git clone https://github.com/frizzy/dotgoblin.git
cd dotgoblin
uv sync

Quick start

# Create a hoard
dotgoblin hoard create myapp

# Add variables
dotgoblin var set myapp DATABASE_URL "postgres://localhost:5432/app"
dotgoblin var set myapp API_KEY '$(pass show myapp/api-key)'

# Bind your project directory to the hoard
cd ~/Code/myapp
dotgoblin bind myapp

# Run a command with the injected env
dotgoblin -- flask run

# Or reference a hoard explicitly
dotgoblin myapp -- flask run

# Preview what would be injected
dotgoblin --dry-run -- flask run

Concepts

• Hoard — a named collection of environment variables stored as TOML
• Binding — maps a working directory to a hoard, so dotgoblin -- <cmd> auto-selects it
• Section — hoards can have named sections (e.g. local, prod) that override base variables
• Secret interpolation — values like $(pass show key) are evaluated at runtime, keeping secrets off disk

Storage

All config lives in ~/.config/dotgoblin/ (override with DOTGOBLIN_DIR):

~/.config/dotgoblin/
├── hoards/
│   ├── myapp.toml
│   └── ...
└── bindings.toml

Hoard file format

# Top-level variables apply to all sections
APP_NAME = "myapp"

[_meta]
default = "local"

[local]
DATABASE_URL = "postgres://localhost:5432/app"
API_KEY = "$(pass show local/api-key)"

[prod]
DATABASE_URL = "postgres://prod.db:5432/app"
API_KEY = "$(pass show prod/api-key)"

Commands

Run a command

dotgoblin -- <command...>                      # use bound hoard
dotgoblin <name> -- <command...>               # use named hoard
dotgoblin <name>:<section> -- <command...>     # named hoard, specific section
dotgoblin :<section> -- <command...>           # bound hoard, specific section
dotgoblin --dry-run -- <command...>            # preview without running

The hoard reference is the single token before --. Variables are merged on top of your current shell environment.

Manage hoards

dotgoblin hoard create <name>    # create a new empty hoard
dotgoblin hoard list             # list all hoards (alias: ls)
dotgoblin hoard show <name>      # show variables (secrets shown as raw expressions)
dotgoblin hoard cat <name>       # print resolved env in envfile format (--export for `export …`)
dotgoblin hoard edit <name>      # open in $EDITOR
dotgoblin hoard rm <name>        # delete (fails if bound)

Manage variables

dotgoblin var set <hoard> <KEY> <value>    # set a variable
dotgoblin var rm <hoard> <KEY>             # remove a variable

Bindings

Multiple directories can be bound to the same hoard.

dotgoblin bind [<hoard-name>]            # bind current directory to a hoard
dotgoblin bind add <hoard-name> <dir>    # bind an arbitrary directory
dotgoblin bind list [<hoard-name>]       # list all bindings (or filter by hoard) (alias: ls)
dotgoblin bind rm [<directory>]          # remove a binding (default: cwd)
dotgoblin unbind                         # shortcut for bind rm
dotgoblin status                         # show active hoard and variables

If bind is called without a hoard name, an anonymous hoard is created automatically.

Secret interpolation

Any value containing $(...) is treated as a shell expression and evaluated at runtime. This keeps secrets out of the store files.

API_KEY = "$(pass show myapp/api-key)"
TOKEN = "Bearer $(cat ~/.tokens/myapp)"
DB_PASS = "$(op read 'op://Vault/DB/password')"

Interpolation only happens during dotgoblin -- <cmd> and --dry-run. All other commands display the raw expression. If a command fails, dotgoblin aborts with the failing key and stderr.

Resolution order

1. Hoard reference before -- (explicit, highest priority)
2. Directory binding (from bindings.toml)
3. Error: no hoard found

Environment

Variable	Description
DOTGOBLIN_DIR	Override config directory (default: ~/.config/dotgoblin/)
EDITOR	Editor used by dotgoblin hoard edit (default: vi)

License

MIT