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 cloud version update` when the positional argument count is not exactly 2 after option parsing. Expected: `vagrant cloud version update <org/box-name> <version>` with optional flags such as -d/--description; argv.size != 2 raises Vagrant::Errors::CLIInvalidUsage with the OptionParser help in %{help}.

Source

Thrown at plugins/commands/cloud/version/update.rb:33

            opts = OptionParser.new do |o|
              o.banner = "Usage: vagrant cloud version update [options] organization/box-name version"
              o.separator ""
              o.separator "Updates a version entry on Vagrant Cloud"
              o.separator ""
              o.separator "Options:"
              o.separator ""

              o.on("-d", "--description DESCRIPTION", "A description for this version") do |d|
                options[:description] = d
              end
            end

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

            @client = client_login(@env)
            org, box_name = argv.first.split('/', 2)
            version = argv[1]

            update_version(org, box_name, version, @client.token, options)
          end

          # Update the version of the box
          # @param [String] org Organization name
          # @param [String] box_name Box name
          # @param [String] version Version of the box
          # @param [String] access_token User Vagrant Cloud access token
          # @param [Hash] options
          # @options options [String] :description Description of box version
          # @return [Integer]

View on GitHub (pinned to 35f3160f4a)

Solutions

Re-run with exactly two positional arguments: `vagrant cloud version update <org>/<box-name> <version>`.
Pass the description as a flag: `vagrant cloud version update org/box 1.0.0 -d "new description"`.
Run `vagrant cloud version update -h` to verify the usage line.

Example fix

# before
vagrant cloud version update hashicorp/bionic64 1.0.0 updated description
# after
vagrant cloud version update hashicorp/bionic64 1.0.0 -d "updated description"

Defensive patterns

Strategy: validation

Validate before calling

abort 'usage: vagrant cloud version update <org/box> <version> [-d DESC]' unless ARGV.length == 2 && ARGV.first.include?('/')
system('vagrant', 'cloud', 'version', 'update', *ARGV)

Try / catch

begin
  Vagrant::Environment.new.cli(['cloud', 'version', 'update', 'org/box', '1.0.0'])
rescue Vagrant::Errors::CLIInvalidUsage => e
  warn e.message
  exit 1
end

Prevention

Pass descriptions via -d, never as a third positional word.
Assert both argv tokens are non-empty before shelling out.
Pin the usage line in scripts with a comment so future edits keep the arg count.

When it happens

Trigger: `vagrant cloud version update` with 0, 1, or 3+ positional args, e.g. `vagrant cloud version update hashicorp/bionic64` (version missing), or supplying the description as a third positional word instead of via `-d "text"`.

Common situations: Trying to set the version description by appending text after the version; empty version variables in automation; mixing up argument order (version first, box second).

Related errors

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