envops

A single-file CLI to inspect and manipulate .env files, designed to be safe by default: values that look like secrets are masked in all output unless you explicitly ask otherwise.

Built with Python stdlib only — a plain python3 (≥3.10) runs it.

Though it works as a regular CLI, envops is first and foremost a skill for AI agents: the bundled skill (skills/envops/SKILL.md) makes the agent route every .env operation through envops — never cat or read env files directly, prefer masked output, treat --unsafe as a last resort — so credentials never leak into the conversation, logs, or context.

Install

Install the skill into your agent (Claude Code, etc.) with skills:

npx skills add reorx/envops

Or with skm:

skm install https://github.com/reorx/envops

That’s all — the skill carries the CLI’s own install steps, so the agent sets up the envops command by itself the first time it needs it.

Usage

show — print key-value pairs (secrets masked)

envops show ./test.env

FOO=hello
API_SECRET=sk******ij
DATABASE_URL=po******pp
DEBUG=true

Show only certain keys; add --unsafe to expose masked values — use with caution and compromise in mind:

envops show ./test.env -k FOO BAR
envops show ./test.env -k API_SECRET --unsafe

list-keys — list keys only

envops list-keys ./test.env

copy — copy pairs from source to dest

Specify keys with -k, or --full to copy every pair. Changes made to the dest file are printed (masked):

envops copy ./test.env /path/to/dest.env -k FOO BAR
envops copy ./test.env /path/to/dest.env --full

+ BAR="quoted value"
~ FOO=hello (was old_foo)
updated /path/to/dest.env: 2 change(s)

+ means the key was added, ~ means its value was updated. Keys already equal in dest are left untouched. Unrelated lines, comments, and formatting in dest are preserved; the dest file is created if it doesn’t exist.

set — set a key’s value from stdin

echo value | envops set ./test.env -k FOO
pbpaste | envops set ./test.env -k API_SECRET

One trailing newline is stripped from stdin. Existing keys are updated in place; new keys are appended.

delete — remove key(s) from an env file

envops delete ./test.env -k FOO
envops delete ./test.env -k FOO BAR

- FOO=hello
deleted 1 key(s) from ./test.env

Deleted pairs are reported in the copy diff style with values masked, so you can confirm what went without exposing it. If any key is missing the command fails and the file is left completely untouched — no half-applied deletion. All occurrences of a duplicate key are removed, so an earlier value can’t come back to life.

read-value — print a key’s raw value

Only use this when the other commands cannot solve the problem, as it exposes the value. --unsafe is required; without it the command fails:

envops read-value ./test.env -K FOO --unsafe

Remote files over SSH

Any file argument may be an scp-style remote path ([user@]host:/path, a colon before the first slash marks it remote). Hosts, keys, and options come from your regular ssh config:

envops show foo@bar:/app/.env
envops copy /tmp/test.env foo@bar:/app/.env --full
envops copy foo@bar:/app/.env ./local.env -k DATABASE_URL

Remote handling keeps the tool’s safety guarantees:

• remote content is only ever held in memory — no plaintext temp file lands on the local disk
• writes are atomic: content goes to a mktemp file next to the target, then mv replaces it, so a dropped connection can’t leave a half-written .env
• the target’s permissions are preserved (stat -c on Linux, stat -f on macOS/BSD remotes; 600 for newly created files)
• output masking works exactly as for local files

Secret detection

A value is masked when any of these match — except pure-numeric values (timeouts, sizes, retry counts like AUTH_TOKEN_EXPIRE=604800), which are never treated as secrets:

• Key name contains SECRET, TOKEN, PASSWORD, API_KEY, ACCESS_KEY, PRIVATE, CREDENTIAL, AUTH, SALT, SIGNING, DSN, … (case-insensitive) — unless the key’s last word marks plain config (URL, URI, ENDPOINT, HOST, PORT, DOMAIN, PATH, NAME, TELEMETRY, …), so BETTER_AUTH_URL is not treated as a secret by its name alone
• Value prefix matches known credential formats: sk-, ghp_, glpat-, xoxb-, AKIA..., JWT (eyJ...), etc.
• Random-looking token run: the value contains an unbroken alphanumeric run of ≥20 chars that mixes letters and digits with Shannon entropy ≥3.5

The entropy check works on alphanumeric runs, so structured values — hostnames (oss-cn-beijing.aliyuncs.com), bucket names (myapp-demo-snapshot), db names — are cut into short segments by - . _ / and pass in the clear.

URL-shaped values (://..., any scheme word) are masked per segment instead of as a whole, so the recognizable parts stay readable:

• the userinfo password is always masked — weak passwords are still passwords
• random-looking runs in the path/query are masked (webhook tokens, etc.)
• scheme, username, host, and port stay in the clear

NEO4J_URL=neo4j://neo4j:12******[email protected]:7687
SLACK_WEBHOOK=https://hooks.slack.com/services/T01ABCDEFGH/B02JKLMNOPQ/x9******ty

Masked form keeps the first and last 2 characters (sk******ij) so you can tell credentials apart without leaking them.

Env file handling

• Supports export KEY=value, single/double quotes, inline # comments on unquoted values
• Duplicate keys: last occurrence wins (dotenv semantics)
• On write, values containing spaces or special characters are double-quoted with escaping
• Writes preserve comments, blank lines, and unrelated lines byte-for-byte

Development

uv run pytest

Tests invoke the CLI as a subprocess and assert on real command behavior.