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

Raised by `vagrant cap` when fewer than two positional arguments remain after option parsing. The command shifts and to_sym's the first two argv entries into type and capability name, so both are mandatory: `vagrant cap <type> <capability-name>` plus optional flags like --check or --target-guest.

Source

Thrown at plugins/commands/cap/command.rb:44

          o.separator ""
          o.separator "Options:"
          o.separator ""

          o.on("--check", "Only checks for a capability, does not execute") do |f|
            options[:check] = f
          end

          # TODO: Rename this back to `target` to maintain api
          o.on("-t", "--target-guest=TARGET", "Target guest to run against (if applicable)") do |t|
            options[:target] = t
          end
        end

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

        type = argv.shift.to_sym
        name = argv.shift.to_sym

        # Get the proper capability host to check
        cap_host = nil
        if type == :host
          cap_host = @env.host
        else
          with_target_vms(options[:target] || []) do |vm|
            cap_host = case type
                       when :provider
                         vm.provider
                       when :guest
                         vm.guest
                       else

View on GitHub (pinned to 35f3160f4a)

Solutions

Provide both arguments: `vagrant cap guest read_ip --target-guest default`
Run `vagrant cap --help` to see the expected form and flags
Remember valid types are host, provider, guest

Example fix

# before
vagrant cap guest

# after
vagrant cap guest read_ip --target-guest default

Defensive patterns

Strategy: validation

Validate before calling

# bash: cap needs <type> <name> at minimum
[ $# -ge 2 ] || { vagrant cap --help; exit 1; }
vagrant cap "$@"

Prevention

Remember the positional order: type first (host|provider|guest), then capability name
Use --check first to probe capability support before running it
Consult `vagrant cap --help` when scripting capability checks

When it happens

Trigger: `vagrant cap` alone, or `vagrant cap guest` with no capability name - argv.length < 2 after parse_options.

Common situations: Exploring the cap command via trial and error; forgetting that the type comes before the capability name.

Related errors

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