Repository navigation
Description
Summary
A missing env: file is skipped in complete silence. The command still runs, with every variable it expected set to empty. Nothing is printed, not even with --verbose, and the exit code is 0.
There is currently no way to say "this env file must exist".
Reproduction
ahoyapi: v2
env:
- .env.global-missing
commands:
deploy:
usage: Deploy somewhere
env:
- .env.cmd-missing
cmd: echo "DEPLOY_HOST=[$DEPLOY_HOST] TOKEN=[$API_TOKEN]"$ ahoy deploy
DEPLOY_HOST=[] TOKEN=[]
$ echo $?
0
$ ahoy -v deploy
[debug] Found .ahoy.yml at /tmp/envtest/.ahoy.yml
===> Ahoy deploy from : [bash -c echo "DEPLOY_HOST=[$DEPLOY_HOST] TOKEN=[$API_TOKEN]" deploy]
DEPLOY_HOST=[] TOKEN=[]Compare a missing imports: file, which fails loudly and names the file:
$ ahoy group
[fatal] Command [group] has 'imports' set, but no commands were found.
Missing import files: missing.ahoy.ymlSo the two "file listed in config but not on disk" cases behave in opposite ways, and the quiet one is the one that carries credentials.
Why this is worth changing
This is not hypothetical. It showed up in a project using Ahoy in the wild, teosibileau/arca, a CLI for issuing invoices against the Argentine tax authority. The author wrote a dedicated check-env command and calls it from the top of every command that needs credentials, and left a comment at the top of the file explaining why:
Los comandos con credenciales cargan .env via la directiva env de ahoy y delegan el chequeo de archivo faltante en check-env, porque ahoy ignora silenciosamente un env file ausente y correría con variables vacías.
("Commands with credentials load .env via ahoy's env directive and delegate the missing-file check to check-env, because ahoy silently ignores an absent env file and would run with empty variables.")
That is a user writing a workaround for this behaviour, in a tool where running with empty credentials means talking to a tax authority's API with no auth. ahoy config validate does report the missing file, but only if you think to run it, and it does not help at the moment the command actually runs.
Current behaviour is deliberate
getEnvironmentVars():
// We allow non-existent "env" files, so skip if file doesn't exist.
if !fileExists(envFile) {
return nil
}And it is documented:
guides/environment.mdx: "Missing files are silently skipped - no error."reference/environment.mdx: "Missing env files are silently skipped - specifying a file that doesn't exist is not an error."
It is also genuinely useful. The documented layering pattern relies on it:
env:
- .env.base
- .env.local # may not exist, and that is fine
- .env.overrideSo the fix is not simply to make it an error. Both cases are legitimate, and right now only one of them is expressible.
Options
1. Warn at run time when a declared env file is missing.
Smallest change, not breaking. Prints to stderr and keeps running. Downside: the .env.local layering pattern above would warn on every run for a file the author deliberately left out, which is noisy enough that people would learn to ignore it.
2. Let an env file be marked optional, and warn only for the rest.
Extends the existing StringArray handling to accept a mapping form alongside the current string and list forms:
env:
- .env # required, warns if absent
- path: .env.local
optional: true # silent if absentBackwards compatible, since every existing config keeps parsing. Uses the same word optional that imports already uses, with the same meaning.
3. As above, then make a missing non-optional env file an error in v4.
Brings env into line with imports: declared means required, absent means say so. Would need the warning shipped first in a v3.x so people have a release to adjust in.
4. Leave the default alone, add opt-in strictness (an env_required: true or similar). Least disruptive, but adds a field that most people who need it will never discover, which is how we got here.
My preference is 2, then 3 at the next major version. That gives the arca author a way to delete their check-env workaround, keeps the layering pattern quiet and explicit, and ends with env and imports behaving consistently.
Notes
- Whatever we pick, the docs statements quoted above need updating, and
ahoy config validateshould agree with the new behaviour. - A malformed line inside an env file already warns at run time, so there is precedent for warning here rather than only at validate time.
Activity
feat: let an env file be marked optional, and report the rest when mi…
test: restore the 'help does not run the command' assertion
Merge pull request #189 from ocean/fix/issue-188-env-optional