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 provider create` requires three or four positional arguments: `organization/box-name`, provider name, version, and optionally a URL to the box file. Fewer than three or more than four argv entries raises CLIInvalidUsage with the command help; checksum and architecture settings are options, not positionals.

Source

Thrown at plugins/commands/cloud/provider/create.rb:44

              o.on("-a", "--architecture ARCH", String, "Architecture of guest box (defaults to current host architecture)") do |a|
                options[:architecture] = a
              end
              o.on("-c", "--checksum CHECKSUM_VALUE", String, "Checksum of the box for this provider. --checksum-type option is required.") do |c|
                options[:checksum] = c
              end
              o.on("-C", "--checksum-type TYPE", String, "Type of checksum used (md5, sha1, sha256, sha384, sha512). --checksum option is required.") do |c|
                options[:checksum_type] = c
              end
              o.on("--[no-]default-architecture", "Mark as default architecture for specific provider") do |d|
                options[:default_architecture] = d
              end
            end

            # Parse the options
            argv = parse_options(opts)
            return if !argv
            if argv.count < 3 || argv.count > 4
              raise Vagrant::Errors::CLIInvalidUsage,
                help: opts.help.chomp
            end

            @client = client_login(@env)

            org, box_name = argv.first.split('/', 2)
            provider_name = argv[1]
            version = argv[2]
            url = argv[3]

            create_provider(org, box_name, version, provider_name, url, @client.token, options)
          end

          # Create a provider for the box version
          #
          # @param [String] org Organization name
          # @param [String] box Box name
          # @param [String] version Box version

View on GitHub (pinned to 35f3160f4a)

Solutions

  1. Use the exact form: `vagrant cloud provider create org/box-name provider version [url]`
  2. Pass metadata as options: --checksum, --checksum-type, --[no-]default-architecture
  3. Confirm with `vagrant cloud provider create -h`

Example fix

# before
vagrant cloud provider create myorg/mybox virtualbox
# after
vagrant cloud provider create myorg/mybox virtualbox 1.0.0
Defensive patterns

Strategy: validation

Validate before calling

# Ruby: enforce the 3-or-4 argument contract before invoking
pos = args.select { |a| !a.start_with?("-") }
unless (3..4).cover?(pos.size)
  abort "usage: vagrant cloud provider create org/box-name provider version [url]"
end
exec "vagrant", "cloud", "provider", "create", *args

Try / catch

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

Prevention

When it happens

Trigger: `vagrant cloud provider create myorg/mybox virtualbox` (version missing); a version split into separate tokens; five or more positionals because a URL or checksum was passed as a bare argument.

Common situations: Forgetting the version argument since create feels like it could infer the next version; passing the URL without an option flag; argument-order mistakes between provider and version when porting scripts between Vagrant versions.

Related errors

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