dtx

dtx is a small CLI for managing encrypted .env-style environments on your local machine.

It is built on top of the dotenvx CLI and gives you a narrow workflow:

• keep env files encrypted at rest
• select the env you want to use
• run commands through an explicit execution gate

The goal is not to replace your shell environment management. The goal is to make secret-backed command execution more deliberate and easier to reason about.

Why dtx

With dtx, you can:

• keep multiple local environments such as dev, staging, and prod
• avoid leaving plaintext env files around by default
• avoid accidentally running commands with the wrong secrets loaded
• keep the "current env" as lightweight state without storing secrets in it

The intended flow looks like this:

dtx edit dev
dtx use dev
dtx run -- npm start

Requirements

dtx depends on the dotenvx CLI for encryption, decryption, and runtime env injection.

Install dotenvx first:

npm install -g @dotenvx/dotenvx

Then install dtx:

go install github.com/yokawasa/dtx/cmd/dtx@latest

Or download a prebuilt binary from GitHub Releases:

• dtx_linux_amd64.tar.gz for Linux on x86_64
• dtx_linux_arm64.tar.gz for Linux on ARM64
• dtx_darwin_amd64.tar.gz for macOS on Intel
• dtx_darwin_arm64.tar.gz for macOS on Apple Silicon
• dtx_windows_amd64.zip for Windows on x86_64

For example, on macOS with Apple Silicon:

curl -fLo dtx_darwin_arm64.tar.gz https://github.com/yokawasa/dtx/releases/latest/download/dtx_darwin_arm64.tar.gz
tar -xzf dtx_darwin_arm64.tar.gz
install dtx /usr/local/bin/dtx

You can also verify the downloaded archive with checksums.txt from the same release.

Requirements:

• Go 1.21 or later to install from source with go install
• dotenvx available on PATH

Quick Start

Create or edit an env named dev:

dtx edit dev

dtx edit uses $VISUAL first, then $EDITOR. If neither is set, it returns an error.

Select the current env:

dtx use dev

Check the current env:

dtx current

Run a command with the selected env:

dtx run -- npm start

Run a command with an explicit env instead of current:

dtx run prod -- npm start

List available envs:

dtx ls

Command Summary

dtx use <env>                           Set the current env
dtx current                             Print the current env
dtx ls                                  List available envs
dtx run [env] [--verbose] -- <command>  Run a command with an env
dtx edit <env> [--verbose]              Create or edit an encrypted env
dtx completion <bash|zsh|fish>          Generate shell completion

Notes:

• dtx run only interprets dtx options before --.
• Everything after -- is passed to the target command unchanged.
• If no env is passed to dtx run, dtx uses the current env.

Shell Completion

Generate completion for bash, zsh, or fish:

dtx completion bash
dtx completion zsh
dtx completion fish

The generated scripts complete:

• subcommands
• env names from ~/.dtx/envs/
• dtx run options such as --verbose

Examples for shell setup:

# bash
echo 'source <(dtx completion bash)' >> ~/.bashrc

# zsh
echo 'source <(dtx completion zsh)' >> ~/.zshrc

# fish
dtx completion fish > ~/.config/fish/completions/dtx.fish

Storage Layout

By default, dtx stores its state under ~/.dtx.

~/.dtx/
  envs/
    dev.enc
    staging.enc
    prod.enc
  keys/
    dev
    staging
    prod
  current

current stores only the selected env name. It does not store secret values.

For isolated testing or automation, you can override the home directory with DTX_HOME:

DTX_HOME=/tmp/dtx-test dtx ls

Security Model

dtx is designed to reduce mistakes and limit plaintext exposure, not to provide perfect isolation from the same local user.

In practice, that means:

• env files are stored encrypted
• plaintext is exposed only during editing or command execution
• dtx run is the explicit path for secret-backed execution
• the selected env state is stored separately from the secret data

Design and Development Docs

If you want the implementation details or design rationale:

• Design Document
• Implementation Notes
• Developer Manual
• ADR 0001: Go and dotenvx CLI adapter