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

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

Q: What causes "This command was not invoked properly. The help for this command is available below. %{help}" in hashicorp/vagrant?

Pass a plugin name: `vagrant plugin install vagrant-disksize`.

Error message

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

What it means

`vagrant plugin install` requires at least one positional plugin name unless the env-local flag is given (options[:env_local], exposed as --local on current Vagrant, --env-local on some builds). When argv.length < 1 and that flag is absent, Vagrant::Errors::CLIInvalidUsage is raised with the help text. With the flag and no names, the command instead installs every plugin declared in the current Vagrantfile.

Source

Thrown at plugins/commands/plugin/command/install.rb:39

            o.banner = "Usage: vagrant plugin install <name>... [-h]"
            o.separator ""
            build_install_opts(o, options)

            o.on("--local", "Install plugin for local project only") do |l|
              options[:env_local] = l
            end

            o.on("--verbose", "Enable verbose output for plugin installation") do |v|
              options[:verbose] = v
            end
          end

          # Parse the options
          argv = parse_options(opts)
          return if !argv

          if argv.length < 1
            raise Vagrant::Errors::CLIInvalidUsage, help: opts.help.chomp if !options[:env_local]

            errors = @env.vagrantfile.config.vagrant.validate(nil)
            if !errors["vagrant"].empty?
              raise Errors::ConfigInvalid,
                errors: Util::TemplateRenderer.render(
                "config/validation_failed",
                errors: errors)
            end

            local_plugins = @env.vagrantfile.config.vagrant.plugins
            plugin_list = local_plugins.map do |name, info|
              "#{name} (#{info.fetch(:version, "> 0")})"
            end.join("\n")


            @env.ui.info(I18n.t("vagrant.plugins.local.install_all",
              plugins: plugin_list) + "\n")

View on GitHub (pinned to 35f3160f4a)

Solutions

Pass a plugin name: `vagrant plugin install vagrant-disksize`.
To install everything declared in the Vagrantfile: `vagrant plugin install --local`.
Run `vagrant plugin install -h` to see flags (--entry-point, --plugin-source, --verbose) and the usage line.

Example fix

# before
vagrant plugin install
# after
vagrant plugin install vagrant-disksize
# or install all Vagrantfile-declared plugins:
vagrant plugin install --local

Defensive patterns

Strategy: validation

Validate before calling

names = ARGV.reject { |a| a.start_with?('-') }
if names.empty?
  system('vagrant', 'plugin', 'install', '--local') # install Vagrantfile-declared set
else
  system('vagrant', 'plugin', 'install', *names)
end

Try / catch

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

Prevention

Guard scripts: if the plugin list is empty, either abort or explicitly use --local.
Keep Vagrantfile-declared plugins as the single source of truth for CI.
Never let an interpolated variable silently vanish from the command line.

When it happens

Trigger: Bare `vagrant plugin install`; flags-only invocation such as `vagrant plugin install --verbose`; intending to sync Vagrantfile-declared plugins but forgetting the local flag.

Common situations: CI bootstrap scripts calling plugin install before writing the Vagrantfile; users switching a project to Vagrantfile-managed plugins for the first time; a plugin name variable that expanded to empty.

Related errors

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