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 upload` requires exactly five positional arguments: `organization/box-name`, provider name, version, architecture, and the path to the file to upload. Any other count raises CLIInvalidUsage; the -D/--direct option toggles direct-to-backend storage and is never positional.

Source

Thrown at plugins/commands/cloud/provider/upload.rb:33

            options = {direct: true}

            opts = OptionParser.new do |o|
              o.banner = "Usage: vagrant cloud provider upload [options] organization/box-name provider-name version architecture box-file"
              o.separator ""
              o.separator "Uploads a box file to Vagrant Cloud for a specific provider"
              o.separator ""
              o.separator "Options:"
              o.separator ""
              o.on("-D", "--[no-]direct", "Upload asset directly to backend storage") do |d|
                options[:direct] = d
              end
            end

            # Parse the options
            argv = parse_options(opts)
            return if !argv
            if argv.count != 5
              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]
            architecture = argv[3]
            file = File.expand_path(argv[4])

            upload_provider(org, box_name, version, provider_name, architecture, file, @client.token, options)
          end

          # Upload an asset for a box version provider
          #
          # @param [String] org Organization name
          # @param [String] box Box name

View on GitHub (pinned to 35f3160f4a)

Solutions

Use the exact five-argument form: `vagrant cloud provider upload org/box-name provider version architecture file`
Quote the file path: `vagrant cloud provider upload myorg/mybox virtualbox 1.0.0 amd64 "./my box.pkg"`
Add -D only as an option for direct uploads to backend storage

Example fix

# before
vagrant cloud provider upload myorg/mybox virtualbox 1.0.0
# after
vagrant cloud provider upload myorg/mybox virtualbox 1.0.0 amd64 ./box.pkg

Defensive patterns

Strategy: validation

Validate before calling

# bash: exactly five arguments and the file must exist before uploading
if [ "$#" -ne 5 ] || ! [[ -f "$5" ]]; then
  echo "usage: vagrant cloud provider upload org/box-name provider version architecture file" >&2
  exit 64
fi
exec vagrant cloud provider upload "$@"

Try / catch

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

Prevention

Quote upload paths — package filenames often contain spaces or versions
Validate count and file existence together in wrappers; both fail late and waste a login
Use -D as an option only; never try to pass the file via a flag

When it happens

Trigger: Four arguments because the file path was forgotten; six or more from an unquoted path containing spaces; the file passed via a flag instead of as the fifth positional.

Common situations: Long upload commands where the trailing file path is dropped by a script; paths with spaces splitting into multiple argv entries; mixing up the argument order (file before architecture).

Related errors

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