Skip to content

A missing env: file is skipped silently, so commands run with empty credentials #188

Closed

Description

@ocean

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.yml

So 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.override

So 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 absent

Backwards 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 validate should 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.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions

      ⌂ 换网址