chocolatey/choco · error · ApplicationException

A single pin command must be listed. Please see the help men

Error message

A single pin command must be listed. Please see the help menu for those commands

What it means

Thrown by ChocolateyPinCommand.ParseAdditionalArguments when more than one unparsed positional argument is passed to the 'choco pin' command. The pin command accepts exactly one subcommand verb (list, add, remove); passing two or more positional tokens is ambiguous and rejected before any parsing of the subcommand type.

Source

Thrown at src/chocolatey/infrastructure.app/commands/ChocolateyPinCommand.cs:68

        public virtual void ConfigureArgumentParser(OptionSet optionSet, ChocolateyConfiguration configuration)
        {
            optionSet
                .Add("n=|name=",
                     "Name - the name of the package. Required with some actions. Defaults to empty.",
                     option => configuration.PinCommand.Name = option.UnquoteSafe())
                .Add("version=",
                     "Version - Used when multiple versions of a package are installed.  Defaults to empty.",
                     option => configuration.Version = option.UnquoteSafe())
                ;
        }

        public virtual void ParseAdditionalArguments(IList<string> unparsedArguments, ChocolateyConfiguration configuration)
        {
            // don't set configuration.Input or it will be passed to list

            if (unparsedArguments.Count > 1)
            {
                throw new ApplicationException("A single pin command must be listed. Please see the help menu for those commands");
            }

            var command = PinCommandType.Unknown;
            var unparsedCommand = unparsedArguments.DefaultIfEmpty(string.Empty).FirstOrDefault();
            Enum.TryParse(unparsedCommand, true, out command);

            if (command == PinCommandType.Unknown)
            {
                if (!string.IsNullOrWhiteSpace(unparsedCommand))
                {
                    this.Log().Warn("Unknown command {0}. Setting to list.".FormatWith(unparsedCommand));
                }

                command = PinCommandType.List;
            }

            configuration.PinCommand.Command = command;
            configuration.Sources = ApplicationParameters.PackagesLocation;

View on GitHub (pinned to 0d5abdd10c)

Solutions

Pass only a single pin subcommand per invocation: 'choco pin list', 'choco pin add --name=pkg', or 'choco pin remove --name=pkg'.
If scripting multiple pin operations, issue separate 'choco pin' calls for each.
Run 'choco pin --help' to review the accepted subcommands.

Example fix

// before
choco pin add remove --name=mypkg
// after
choco pin add --name=mypkg
choco pin remove --name=mypkg

Defensive patterns

Strategy: validation

Validate before calling

// Ensure only one positional subcommand is passed
if (positionalArgs.Count(arg => !arg.StartsWith("-")) > 1)
{
    Console.Error.WriteLine("Pass a single pin subcommand (list, add, or remove).");
}

Prevention

Issue each pin operation as a separate 'choco pin <subcommand>' call.
Validate argument count before invoking the CLI.

When it happens

Trigger: Running 'choco pin add remove' or 'choco pin list add' — i.e. supplying two or more subcommand verbs in a single invocation. Any call where unparsedArguments.Count exceeds 1.

Common situations: User misunderstands the CLI syntax and chains multiple pin operations in one command instead of running them separately. Or a script erroneously concatenates multiple operations.

Related errors

AI-assisted analysis of chocolatey/choco@0d5abdd10c (2026-08-13). Data as JSON: /api/errors/5f3b6a5378c6f135. Report an issue: GitHub.