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 cloud version create` requires exactly two positional arguments: the `org/box-name` identifier and the version string. The guard `argv.empty? || argv.length != 2` raises CLIInvalidUsage for zero, one, or three-plus entries; the version description is supplied via -d/--description, never positionally.

Source

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

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

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

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

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

            create_version(org, box_name, version, @client.token, options.slice(:description))
          end

          # Create a new version of the box
          #
          # @param [String] org Organization box is within
          # @param [String] box_name Name of box
          # @param [String] box_version Version of box to create
          # @param [String] access_token User Vagrant Cloud access token
          # @param [Hash] options
          # @option options [String] :description Description of box version

View on GitHub (pinned to 35f3160f4a)

Solutions

Use the exact form: `vagrant cloud version create org/box-name version`
Attach the description as an option: `vagrant cloud version create -d "Initial release" myorg/mybox 1.0.0`
Check `vagrant cloud version create -h`

Example fix

# before
vagrant cloud version create myorg/mybox
# after
vagrant cloud version create myorg/mybox 1.0.0

Defensive patterns

Strategy: validation

Validate before calling

# Ruby: exactly two positionals, identifier slash-separated
pos = args.select { |a| !a.start_with?("-") }
unless pos.size == 2 && pos.first =~ %r{\A[^/\s]+/[^/\s]+\z}
  abort "usage: vagrant cloud version create org/box-name version"
end

Try / catch

begin
  env.cli(%w[cloud version create], org_box, version)
rescue Vagrant::Errors::CLIInvalidUsage => e
  $stderr.puts e.message.lines.first
  exit 64
end

Prevention

Keep version strings (including pre-release labels) as one quoted token
Pass descriptions via -d, never as a trailing positional
Compute the next version in your tooling instead of typing it interactively

When it happens

Trigger: `vagrant cloud version create myorg/mybox` (version missing); three arguments from an unquoted version or box identifier containing a space; passing the description as a third positional.

Common situations: Copying the single-argument style from `vagrant cloud box create`; splitting semantic-version pre-release labels into separate args; scripts forwarding user input unquoted.

Related errors

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