Repository navigation
Description
Summary
In v3.0.0, unknown flags passed to a command defined in .ahoy.yml are silently discarded before the configured shell command runs — and so is the argument that follows each flag. In v2.5.0 they were forwarded verbatim.
This is not covered by the release notes, which state that "there are no breaking changes to the command syntax or behaviour", so I believe it is unintended rather than a deliberate change.
Reproduction
.ahoy.yml:
ahoyapi: v2
commands:
echoargs:
cmd: echo "$@"
usage: Echo the arguments it receives$ ahoy echoargs AAA --log-junit x.xml --configuration y.dist BBB
AAA BBB # v3.0.0 -- flags and their values gone
AAA --log-junit x.xml --configuration y.dist BBB # v2.5.0Every form is affected, including the = form, so that is not a workaround:
| Input after the command name | v3.0.0 output |
|---|---|
AAA --log-junit x.xml BBB |
AAA BBB |
AAA --log-junit=x.xml BBB |
AAA BBB |
AAA -R -p BBB |
AAA BBB |
START --filter='My Test Name' -R END |
START |
CMD -p /tmp/logs END |
CMD END |
Note the last two: because pflag assumes the token after an unknown flag is its value, a trailing positional argument can be destroyed too.
Inserting -- anywhere before the flags restores the v2 behaviour, which is the only workaround we have found.
Root cause
v2.5.0 — v2/ahoy.go#L248-L253, on urfave/cli v1:
newCmd := cli.Command{
Name: name,
Aliases: cmd.Aliases,
SkipFlagParsing: true,
HideHelp: cmd.Hide,
}v3.0.0 — ahoy.go#L336-L345, on cobra:
newCmd := &cobra.Command{
Use: name,
Aliases: cmd.Aliases,
// Don't use DisableFlagParsing - it prevents persistent flags from being parsed.
// Instead, we use FParseErrWhitelist to allow unknown flags to pass through.
FParseErrWhitelist: cobra.FParseErrWhitelist{
UnknownFlags: true,
},
Hidden: cmd.Hide,
}The premise in that comment does not hold: FParseErrWhitelist.UnknownFlags only suppresses the error, it does not pass the flag through. In pflag@v1.0.10/flag.go#L992-L1011 the unknown-flag branch returns without ever appending the flag token to f.args, and stripUnknownFlagValue additionally drops the following non-dash token as the presumed value.
-- works because it is the only verbatim path, at flag.go#L1145-L1150.
Reproduced against pflag v1.0.10 in isolation, with no ahoy involved:
IN : [AAA --log-junit x.xml --configuration y.dist BBB]
OUT: [AAA BBB]
IN : [AAA --log-junit=x.xml BBB]
OUT: [AAA BBB]
IN : [-- AAA --log-junit x.xml BBB]
OUT: [AAA --log-junit x.xml BBB]
Why this went unnoticed
The BATS suite never asserts an unknown flag surviving without --:
tests/migration-safety.bats#L86-L92"Command arguments are preserved" uses only positional arguments.tests/cli-flag-combinations.bats#L118-L123is the only case with flag-like arguments after a command, and it passes--.
A regression test along the lines of ahoy echoargs AAA --foo bar BBB producing AAA --foo bar BBB would have caught it.
Impact
Ahoy is widely used to wrap other CLIs, so the failure is silent rather than loud: the wrapped tool runs successfully with different semantics. In our toolchain, commands lost their own hard-coded options, with no user input involved:
phpunit --configuration <path> --list-suitesreceived nothing at all and printed its usage screenchown -R www-data:www-data .reached the container aschown .mkdir -p /tmp/logsreached it asmkdirphpcsran with no standard, no file list and no report options
Suggested fix
Restore the v2 contract by using DisableFlagParsing: true on the generated commands, and parse ahoy's own persistent flags before the command name — which the pre-parser in flag.go already does today. That would make the objection recorded in the code comment no longer applicable.
Related: #163 requests separator-free argument appending as an enhancement; this report is narrower, namely that v3.0.0 lost behaviour v2.5.0 had.
Happy to supply the isolated pflag reproduction or test a patch.
Environment
- ahoy v3.0.0 (
ahoy-bin-linux-amd64), Linux x86_64 - Compared against ahoy v2.5.0 on the same host and the same
.ahoy.yml
Activity
ocean commentedon Aug 31, 2026
Thanks for the report @jurgenhaas and sorry about the breakage. I should always have written more tests!
I'll have a look at this today.
Merge pull request ahoy-cli#185 from ocean/fix/issue-182-arg-passthrough
jurgenhaas commentedon Sep 2, 2026
Thank you, @ocean for the real quick turnaround.
fix: only strip a leading '--', not every occurrence (#186)
test: restore the 'help does not run the command' assertion