A patch release that fixes a v3 regression in tab completion, and makes release downloads verifiable.

If you use a completion script written for Ahoy v2, please upgrade. In v3.0.0 and v3.0.1, pressing Tab after a command name could run that command.

Fixes

Tab completion no longer (accidentally) runs your commands.

#193, reported and fixed by @hanoii in #194.

Completion scripts from the v2 (urfave/cli) era, including the bash script in our own docs, work by adding --generate-bash-completion to the words typed so far:

opts=$( ${COMP_WORDS[@]:0:$COMP_CWORD} --generate-bash-completion )

So ahoy deploy <TAB> runs ahoy deploy --generate-bash-completion. Since v3.0.0, Ahoy's own flags are only recognised before the command name. That meant the flag was passed to deploy as an ordinary argument, and deploy ran.

A --generate-bash-completion that comes last is now treated as a completion request. Ahoy lists the subcommands of the command you typed and runs nothing, as v2 did. Anywhere else in the arguments, it still reaches your command unchanged, so wrapped tools that take a flag of that name still receive it.

Cleaner completion from ahoy completion <shell>

The same PR fixes the completion scripts that ahoy completion bash|zsh|fish|powershell generates, when you complete the first word after ahoy:

• Each command is listed once, instead of twice.
• Hidden commands, such as __complete and anything marked hide: true, are no longer suggested.
• Suggestions now match what you've typed. ahoy f<TAB> gives foo fo instead of the full command list.
• Aliases are still offered alongside command names.

Completion of subcommands and of later arguments is unchanged.

Thanks

• @hanoii (Ariel Barreiro) for reporting #193 with a clear before-and-after table, and for the fix and tests in #194. This is Ariel's second regression fix in two releases.

Full changelog

• #190, #192 Include the raw binaries in the checksums file, and sign it with cosign
• #194 Stop legacy completion from running commands (@hanoii), fixes #193
• Updated the README sponsors section

Full diff: v3.0.1...v3.0.2

A patch release fixing three regressions in v3.0.0, plus one new feature.

If you are on v3.0.0, please upgrade! Two of these bugs changed the arguments your commands received without telling you: the wrapped tool ran, exited 0, and may well have done something other than what you typed. Sorry.

Fixes

Interactive and full-screen commands work again

#180, reported and fixed by @hanoii in #181.

v3.0.0 replaced the process-wide os.Stderr with a pipe (for reason while in the early stages of migrating to Cobra), so every child process inherited a pipe on fd 2 instead of the terminal. Anything that draws a TUI on stderr could no longer ask the terminal how big it was, measured 0x0, and rendered nothing. gum on Bubble Tea v2 crashed outright with makeslice: len out of range.

That covers gum, fzf, glow, progress bars, spinners, and anything else that repaints the terminal (or bits of it) in place.

# v3.0.0
$ ahoy fds
l-wx------ ... /proc/self/fd/2 -> 'pipe:[3079507]'

# v3.0.1
$ ahoy fds
lrwx------ ... /proc/self/fd/2 -> /dev/pts/2

Ahoy no longer displaces anything on stderr. Output is not buffered either, so a long-running command's output appears as it is produced.

A follow-up (#184) removed the pipe entirely. It turned out to be dead code: it had been added to intercept Cobra's error output during the v3 migration, that job had since moved elsewhere, and what remained copied stderr to stderr, achieving nothing except the loss of the terminal.

Command arguments are passed through verbatim

#182, reported by @jurgenhaas, fixed in #185. Also closes #163, raised by @AlexSkrypnyk.

v3.0.0 let Cobra parse each command's arguments before running it. Any flag it did not recognise was silently dropped, along with the token following it.

$ ahoy echoargs AAA --log-junit x.xml --configuration y.dist BBB
AAA BBB                                            # v3.0.0
AAA --log-junit x.xml --configuration y.dist BBB   # v3.0.1, and v2.5.0

Because Ahoy is often used to wrap other CLIs, this was quiet rather than loud. Reported effects included phpunit --configuration <path> --list-suites receiving nothing at all, chown -R www-data:www-data . arriving as chown ., and mkdir -p /tmp/logs arriving as mkdir.

Ahoy's own flags were being claimed after the command name too, which was the same defect, driven by a CLI change that I decided was actually counterproductive. Something like ahoy phpunit -v turned on Ahoy's verbose mode instead of PHPUnit's.

All text after the command name now reaches your command exactly as typed, in order. Ahoy's own flags are recognised only before the command name.

ahoy --verbose deploy     # --verbose is Ahoy's
ahoy deploy --verbose     # --verbose belongs to the deploy command

Two things to know when upgrading:

• ahoy <command> --help now reaches the wrapped tool, so ahoy drush --help gives you Drush's help. Ahoy's own help for a command is ahoy help <command>. That form was documented but didn't work correctly, and is now a real command.
• -v and --verbose after a command name belong to the command. Put them before the command name for Ahoy's verbose output.

This also resolves #163: appending arguments has never needed --, and now does not lose them either.

A literal -- reaches your command

#186, fixed in #187.

Ahoy removed every -- a user typed, not just a leading one, so a separator meant as data never arrived. Lots of tools need to use those.

That last row is a bit of a nasty one. With a branch and a file sharing a name, asking to discard edits to the file switched branch instead and left the edits in place.

A leading -- is still consumed, so ahoy up -- --build behaves exactly as before. Any later -- is now your command's data. This applied to v2 as well, so it is a fix rather than a regression.

✨ New feature: optional env files

Written up in #188, added in #189.

A missing env: file used to be skipped in complete silence. No output, exit code 0, and every variable the command expected left empty. Nothing was printed even with --verbose, and there was no way to tell Ahoy that a file had to be present.

An env entry is now required by default and reported on stderr when absent. Mark the optional ones like this:

env:
  - .env                  # required, warns if absent
  - path: .env.local
    optional: true        # silent if absent

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

optional has the same meaning here as it already has for the imports section of the config file.

This is not a breaking change. A missing file is still not fatal and the command still runs, so existing configurations behave as they did apart from the new warning. Every existing form still parses: the env: .env shorthand, plain lists, empty lists and nulls.

This allows for two smaller improvements:

• ahoy config validate now reports only the required files that are missing, and shows optional ones as an expected absence rather than a problem.
• An env entry that names no file (env: "", a null list entry, or a mapping with no path) is now a config error naming the offending position, instead of being treated as a file called ''.

The mapping form cannot be read by Ahoy versions before v3.0.1, so ahoy config validate flags it if you are targeting an older release.

Where this came from

A project using Ahoy in the wild, teosibileau/arca, a CLI for issuing invoices against the Argentine tax authority. Its .ahoy.yml carries a hand-written check-env command called from the top of every command that needs credentials, with a comment explaining why:

porque ahoy ignora silenciosamente un env file ausente y correría con variables vacías

("because ahoy silently ignores an absent env file and would run with empty variables")

Sometimes someone writing a workaround is as good as a bug report. @teosibileau hopefully your workaround isn't needed any more now!

Documentation

The docs site has been updated to add more details about these fixes:

• Standard streams: what Ahoy does with stdin, stdout and stderr, which is nothing, and why that matters for full-screen and TUI commands.
• Passing arguments: a table of which tokens are Ahoy's and which are your command's, including the = forms and --.
• Wrapper commands: how a wrapped tool keeps its own flags, and where ahoy help <command> fits.
• Environment files: the required/optional distinction and the mapping form.

Upgrading

No configuration changes are required. Existing .ahoy.yml files work unchanged.

Worth checking after upgrading:

1. Anywhere you rely on Ahoy's -v, --verbose, -f or --file after a command name. Move those ahead of the command name.
2. Any script using ahoy <command> --help to get Ahoy's help. Use ahoy help <command>.
3. Any env: entry for a file that is deliberately absent. Mark it optional: true to silence the new warning.

Run ahoy config validate to have most of this checked for you.

Thanks

• @hanoii for reporting #180 with a precise diagnosis, and for the fix in #181.
• @jurgenhaas for reporting #182, including an isolated pflag reproduction that made the root cause obvious.
• @AlexSkrypnyk for #163, which turned out to be the same underlying problem.
• @teosibileau for using Ahoy, for your sponsorship, and for giving me some ideas!

Two of the three regressions were found and diagnosed by users rather than by our tests. I thought that would be the case when I released v3.0.0 with all the underlying changes, I'm happy it's worked out and sorry for any inconvenience.

Full changelog

• #181 Preserve terminal stderr for subprocesses (@hanoii), fixes #180
• #184 Remove the dead stderr capture pipe
• #185 Restore verbatim argument pass-through, fixes #182, closes #163
• #187 Only strip a leading --, fixes #186
• #189 Optional env files and missing-file reporting, fixes #188

Full diff: v3.0.0...v3.0.1

Ahoy v3 migrates the CLI framework from urfave/cli v1 to spf13/cobra.

Every existing .ahoy.yml file SHOULD continue to work unchanged - at the moment ahoyapi: v2 is still the current config
file format flag, and there are no breaking changes to the command syntax or behaviour. Updates to the configuration file format are likely to happen in the next 6-12 months though, but ahoy release versions will be forwards-compatible.

Upgrading

For most people this is a drop-in replacement. Two things to be aware of:

1. Homebrew

brew install ahoy now installs v3. There is no ahoy@2 formula - a versioned formula was
submitted to homebrew-core and declined as against their policy. If you need to stay on v2, use
the binaries or archives attached to the
v2.5.0 release.

I will continue to monitor the v2 release line code for security issues, dependency upgrades etc, and will release minor version updates as and when required, for at least the next 6 months.

2. 32-bit ARM builds are now split into armv6 and armv7

Previous releases shipped a single ahoy-bin-linux-arm built for ARMv6. v3 builds ARMv6 and ARMv7 separately, so that asset is replaced by two:

If you hand-wrote a download URL ending in -linux-arm, point it at -linux-armv6 (identical to
what you had) or -linux-armv7 (better performance on Raspberry Pi 2 and newer). The install
one-liner in the README selects the right one automatically.

All other asset names are unchanged from v2.5.0. Static Linux builds
(ahoy-bin-linux-amd64-static, ahoy-bin-linux-arm64-static) are new in v3 and useful for minimal containers.

What's new

ahoy config command group

Two new subcommands:

• ahoy config validate: validates .ahoy.yml files, with version mismatch detection and
  field-level checks that catch unsupported features
• ahoy config init: the command that downloads a "starter" .ahoy.yml file, is now reworked to use Go's native HTTP client, dropping external dependencies

New environment variables

• AHOY_CMD: absolute path to the running ahoy binary (via os.Executable()). Nested ahoy
  calls can use $AHOY_CMD to guarantee they invoke the same binary version of ahoy.
• AHOY_COMMAND_NAME: the name of the command being run (e.g. test), so wrapped scripts
  can detect that they were invoked via ahoy, and which command triggered them. Resolves
  #165.

Better help output

Two-tier help with per-command DESCRIPTION sections, as long as you add them to your .ahoy.yml files.

Bug fixes

• Fixed nil-pointer panics in edge-case command execution paths
• Fixed silent error swallowing and incorrect exit codes on invalid flags
• Fixed a stderr-capture deadlock by replacing buffering with a goroutine drain
• Fixed atomic file writes and URL scheme validation in downloadFile
• Fixed AHOY_FILE and AHOY_VERBOSE environment variable wiring

Internal changes

Framework migration

• Replaced urfave/cli with spf13/cobra, a more widely used CLI tool library that has more features we can use
• CLI flags are handled directly via Cobra and spf13/pflag
• Added a custom pre-parser so the small amount of single-dash flags we have (-version, -help) keep on working
• Added expandPath() for unified, consistent file path handling

Project structure

v3 code now lives at the repository root. The v2 code is preserved in the v2/ subdirectory for posterity and continued support.

CI

• Tests run against both the v2 and root (v3) codebases
• Added Homebrew coreutils to the macOS runners so timeout works in the BATS suite

Full changelog: v2.5.0...v3.0.0

New features! ✨ ✨

• Multiple .env files support - You can now specify multiple environment files using array syntax, addressing #136. Files are loaded in order with later files overriding earlier ones. Thanks to @jackwrfuller for the initial implementation that was incorporated into this feature!

# Single env file (backwards compatible)
env: .env

# Multiple env files (new array syntax)
env:
  - .env.base
  - .env.local
  - .env.override

# Command-level multiple env files
commands:
  deploy:
    env:
      - .env.deploy
      - .env.secrets

Bug fixes 🐛 👏

• Windows compatibility improvements - A big welcome back to original maintainer @frankcarey who fixed path handling and binary execution issues on Windows platforms. Thanks to Frank for identifying and helping resolve these Windows issues! 🙌

What's Changed

• Add comprehensive test coverage for multiple env files feature with 25+ unit and integration tests
• Implement StringArray type for flexible YAML parsing of both single strings and arrays
• Maintain full backwards compatibility with existing .ahoy.yml files
• Add graceful handling of non-existent env files (they are silently skipped)
• Support for comments and empty lines in env files
• Proper environment variable precedence: command-level overrides global, later files override earlier ones

Technical Details

The multiple env files feature uses a new StringArray type that handles both the old single string format and the new array format in YAML. This ensures 100% backwards compatibility - existing .ahoy.yml files will continue to work without any changes.

Full Changelog: v2.4.0...v2.5.0

Bug fix 🐛 👏

• Use Environ() instead of Env by @jnsalsa in #140 - this prevents existing environment variables from all being cleared out when using then env option in your command file.

What's Changed

• chore: Update Dependabot config for v2 by @ocean in #134
• Linting and config updates by @ocean in #141

New Contributors

• @jnsalsa made their first contribution in #140

Full Changelog: v2.3.0...v2.4.0

New features! ✨ ✨

• Add support for .env files in commands by @jackwrfuller in #126
• Add Oh-My-Zsh plugin by @jackwrfuller in #128

What's Changed

• chore: Remove outdated docs build tools by @ocean in #123
• Create FUNDING.yml by @ocean in #124
• Update Zsh completions and add Oh-My-Zsh plugin by @jackwrfuller in #128
• Fix broken installation command by @jackwrfuller in #127
• Linting corrections by @ocean in #131
• Move code to v2 directory as this is correct for v2 of a Go project by @ocean in #132
• Update README to add info about .env file support by @ocean in #133

New Contributors

• @jackwrfuller made their first contribution in #128

Full Changelog: v2.2.0...v2.3.0

✨ What's new ✨

• Optional imports by @hanoii in #119
• Add command aliases as requested in #110 by @ocean in #122

New Contributors 🎉

• @dependabot made their first contribution in #116
• @hanoii made their first contribution in #119

Full Changelog: v2.1.1...v2.2.0

A quick rebuild with the latest Go, version 1.20.

What's Changed

• Create code of conduct by @ocean in #102
• Update issue templates by @ocean in #103

Full Changelog: 2.0.2...v2.1.1

What's fixed 🥳

• Fix for #4 : Show overwrite warning for ahoy init by @ocean in #97
• Fix for #100 : Stop -- parameter being passed literally to command by @ocean in #101

What's changed 🛠️

• docs: Update README by @ocean in #98
• chore: Realign binary naming & ldflags by @ocean in #99

Full Changelog: 2.0.1...2.0.2

Alpha release

This is an alpha release for testing if the problem in #100 has been fixed.

What's Changed

• docs: Update README by @ocean in #98
• fix!: [#4] Show overwrite warning for ahoy init by @ocean in #97
• chore: Realign binary naming & ldflags by @ocean in #99
• fix: Prevent -- from being passed as argument to command (fix for #100) by @ocean in a562009

Full Changelog: 2.0.1...2.0.2-alpha