Looks like this comes from docker_pkg/cli.py line 76, which is the last line here:

    parser.add_argument('-c', '--configfile', default="config.yaml")
# ...
    actions = parser.add_subparsers(help='Action to perform: {}'.format(','.join(ACTIONS)), dest="mode")
# ...
    update = actions.add_parser('update', help="Helper for preparing an update of an image tree")
    update.add_argument('select', help="Names of the base image being updated", metavar='NAME')
    update.add_argument('--reason', help="Reason for the update.", default='Security update')
    update.add_argument('--version', '-v', help="Specify a version for the image to upgrade", default=None)
    # The directory argument always goes last
    parser.add_argument('directory', metavar="DIRECTORY", help='The directory to scan for images')

The positional arg is handled by the main parser, but it's after the section of argv handed to the subparser, so I'm pleasantly surprised that this works at all. In the error case, my guess is the main parser is still consuming '* Version bump.' for the directory arg, then passing ['golang', '--version', '1.15-1', '--reason'] to the subparser, so that's why the error complains about --reason not getting a value.

Given the order those two parsers act in, I don't think there's an elegant way to fix this -- one of the inelegant options is to remove directory from the main parser and add it to each of the subparsers instead, so that the user-facing API doesn't change, but the argv string is all main-parser stuff and then all subparser stuff, which is the more usual order.

@Joe What do you think?

I agree @rzl, your proposal is probably the most user-friendly solution. Rationale here was I felt I had no need to replicate in every subparser the same last argument, but ofc this results in a horrible UX.