hashicorp/vagrant · error · Vagrant::Errors::CLIInvalidUsage

This command was not invoked properly. The help for this com

Error message

This command was not invoked properly. The help for this command is available below. %{help}

What it means

`vagrant plugin expunge` accepts only flags (--force, --reinstall, --global-only) and no positional arguments. After parse_options, any leftover argv (argv.length > 0) raises Vagrant::Errors::CLIInvalidUsage with the help text. Expunge removes plugins, so Vagrant deliberately rejects accidental operands.

Source

Thrown at plugins/commands/plugin/command/expunge.rb:42

            end

            o.on("--local-only", "Only expunge local project plugins") do |l|
              options[:env_local_only] = l
            end

            o.on("--global-only", "Only expunge global plugins") do |l|
              options[:global_only] = l
            end

            o.on("--reinstall", "Reinstall current plugins after expunge") do |reinstall|
              options[:reinstall] = reinstall
            end
          end

          # Parse the options
          argv = parse_options(opts)
          return if !argv
          raise Vagrant::Errors::CLIInvalidUsage, help: opts.help.chomp if argv.length > 0

          plugins = Vagrant::Plugin::Manager.instance.installed_plugins

          if !options[:reinstall] && !options[:force] && !plugins.empty?
            result = nil
            attempts = 0
            while attempts < 5 && result.nil?
              attempts += 1
              result = @env.ui.ask(
                I18n.t("vagrant.commands.plugin.expunge_request_reinstall") +
                  " [N]: "
              )
              result = result.to_s.downcase.strip
              result = "n" if result.empty?
              if !["y", "yes", "n", "no"].include?(result)
                result = nil
                @env.ui.error("Please answer Y or N")
              else

View on GitHub (pinned to 35f3160f4a)

Solutions

  1. Run it bare: `vagrant plugin expunge` (add --force or --reinstall as flags).
  2. To remove a single plugin, use `vagrant plugin uninstall <name>` instead.
  3. Check `vagrant plugin expunge -h` for the supported flag set.

Example fix

# before
vagrant plugin expunge my-plugin
# after
vagrant plugin uninstall my-plugin    # expunge wipes ALL plugins, no operands allowed
Defensive patterns

Strategy: validation

Validate before calling

pos = ARGV.reject { |a| a.start_with?('-') }
abort 'vagrant plugin expunge takes no positional arguments' unless pos.empty?
system('vagrant', 'plugin', 'expunge', '--force')

Try / catch

begin
  Vagrant::Environment.new.cli(['plugin', 'expunge'])
rescue Vagrant::Errors::CLIInvalidUsage => e
  warn e.message
  exit 1
end

Prevention

When it happens

Trigger: Any positional token after the subcommand: `vagrant plugin expunge my-plugin`, `vagrant plugin expunge all`, or a stray word where a flag was intended (e.g. `force` instead of `--force`).

Common situations: Users assume expunge can target one plugin (it wipes all); muscle memory from `apt remove pkg`-style commands; scripts interpolating a variable that expands to a bare word.

Related errors

AI-assisted analysis of hashicorp/vagrant@35f3160f4a (2026-08-21). Data as JSON: /api/errors/525178cc7d394c89. Report an issue: GitHub.