Skip to content

v3.0.0 regression: unknown flags and their values are stripped from .ahoy.yml commands #182

Closed

Description

@jurgenhaas

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

Every 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 --:

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-suites received nothing at all and printed its usage screen
  • chown -R www-data:www-data . reached the container as chown .
  • mkdir -p /tmp/logs reached it as mkdir
  • phpcs ran 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

  1. ocean commented on Aug 31, 2026

    @ocean
    Member

    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.

  2. added a commit that references this issue on Sep 2, 2026
    968aefa
  3. jurgenhaas commented on Sep 2, 2026

    @jurgenhaas
    Author

    Thank you, @ocean for the real quick turnaround.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions

      ⌂ 换网址