Environment Variables

Ahoy can load environment variables from files before running your commands, keeping configuration and secrets out of your YAML.

A simple example v2.3.0+

Create a .env file alongside your .ahoy.yml:

DB_USER=root
DB_PASS=secret
DB_NAME=myapp

Reference it in your config:

ahoyapi: v2

env: .env

commands:
  db:
    usage: Connect to the database
    cmd: mysql -u$DB_USER -p$DB_PASS $DB_NAME

The path is relative to the .ahoy.yml file, not your working directory.

Global and per-command files

The top-level env applies to every command. Individual commands can also specify their own env, which layers on top:

ahoyapi: v2

env: .env # Loaded for every command

commands:
  deploy:
    usage: Deploy the application
    env: .env.deploy # Also loaded for this command only
    cmd: ./deploy.sh

Multiple files v2.5.0+

Both global and per-command env fields accept an array. Files are loaded in order - later files override earlier ones:

ahoyapi: v2

env:
  - .env.base
  - .env.local # Overrides .env.base

commands:
  deploy:
    env:
      - .env.deploy
      - .env.staging
    cmd: ./deploy.sh staging

A file like .env.local is often absent, for example when you start a project from a checked-out repo with an .ahoy.yml file in it. From v3.0.1 Ahoy reports this, rather than passing over it in silence, so please start marking such entries as optional - see below.

Files that may be absent v3.0.1+

A missing env file never stops a command - it is skipped, the variables it would have set stay empty, and the command runs. What changed in v3.0.1 is that Ahoy now shows a warning:

[warn] environment file '.env.local' not found, continuing without it. Add 'optional: true' to that entry if it is meant to be absent.

Every entry is required by default, so a typo in a filename surfaces instead of leaving you to work out why a variable is empty. For the files that are meant to be missing - a personal .env.local that only some developers have - write the entry as a mapping and mark it optional: true:

env:
  - .env.base # Required: warns when absent
  - path: .env.local
    optional: true # Silent when absent

This is the same optional you may already use on imports: simply meaning that the file is not expected to always present.

The warning goes to stderr, so it never contaminates a command’s stdout when you pipe it. ahoy config validate distinguishes the two as well, listing a missing required file with ❌ and a missing optional one with ➖ ... - missing, marked optional.

Requires v3.0.1

The mapping form is not understood by earlier versions - Ahoy v2.5.0 fails to parse it with cannot unmarshal !!seq into string. Keep the plain string form if your .ahoy.yml is shared with anyone still on v2 or v3.0.0.

Precedence

From lowest to highest:

1. Your shell’s existing environment
2. Global env files (in order)
3. Command-specific env files (in order)

Runtime variables v3

Ahoy automatically injects two variables into every command:

Variable	Value
AHOY_COMMAND_NAME	The name of the command being run
AHOY_CMD	Path to the ahoy binary

These are useful for scripts that call other ahoy commands, or need to know their own name.

Keep secrets out of version control

Add your real .env files to .gitignore and commit a .env.example with placeholder values:

.gitignore

.env
.env.local
.env.secrets

# .env.example - safe to commit
DB_USER=your_username
DB_PASS=your_password
DB_NAME=your_database

For the complete format specification and precedence details, see the Environment Reference.