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 publish` validates its argument vector combinatorially: it needs 3 or 4 positional arguments (`org/box-name version provider [box-file]`); the 3-argument form requires --url to be set (the box file is hosted remotely), and the 4-argument form forbids --url (you cannot supply both a URL and a local file). Violating any branch raises CLIInvalidUsage.

Source

Thrown at plugins/commands/cloud/publish.rb:73

              options[:checksum_type] = c
            end
            o.on("--[no-]direct-upload", "Upload asset directly to backend storage") do |d|
              options[:direct_upload] = d
            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.length < 3 || # missing required arguments
              argv.length > 4 || # too many arguments
              (argv.length < 4 && !options.key?(:url)) || # file argument required if url is not provided
              (argv.length > 3 && options.key?(:url)) # cannot provide url and file argument
            raise Vagrant::Errors::CLIInvalidUsage,
              help: opts.help.chomp
          end

          org, box_name = argv.first.split('/', 2)
          _, version, provider_name, box_file = argv

          if box_file && !File.file?(box_file)
            raise Vagrant::Errors::BoxFileNotExist,
              file: box_file
          end

          @client = client_login(@env)
          params = options.slice(:private, :release, :url, :short_description,
            :description, :version_description, :checksum, :checksum_type,
            :architecture, :default_architecture)

          # Display output to user describing action to be taken
          display_preamble(org, box_name, version, provider_name, params)

View on GitHub (pinned to 35f3160f4a)

Solutions

  1. Remote form (3 args + URL): `vagrant cloud publish org/box 1.0.0 virtualbox --url https://example.com/box.box`
  2. Local form (4 args, no URL): `vagrant cloud publish org/box 1.0.0 virtualbox ./box.box`
  3. Check `vagrant cloud publish -h` — the banner shows both accepted forms

Example fix

# before (both a file and --url given)
vagrant cloud publish myorg/mybox 1.0.0 virtualbox ./box.box --url https://example.com/box.box
# after
vagrant cloud publish myorg/mybox 1.0.0 virtualbox ./box.box
Defensive patterns

Strategy: validation

Validate before calling

# Mirror publish's exclusive-or rule before invoking
n = positional_args_count   # args after flag extraction
has_url = !options[:url].nil?
valid = (n == 3 && has_url) || (n == 4 && !has_url)
abort "usage: vagrant cloud publish org/box version provider [file | --url URL]" unless valid

Try / catch

begin
  argv = %w[cloud publish] + (url ? ["--url", url] : []) + [org_box, version, provider, *file]
  env.cli(*argv)
rescue Vagrant::Errors::CLIInvalidUsage => e
  $stderr.puts e.message.lines.first
  exit 64
end

Prevention

When it happens

Trigger: `vagrant cloud publish org/box 1.0.0 virtualbox` with no --url (3 args, missing remote location); `vagrant cloud publish org/box 1.0.0 virtualbox ./box.box --url https://...` (4 args plus --url, both sources given); five or more positionals.

Common situations: Migrating from the older five-argument publish syntax (org box version provider file as separate positionals); assuming --url is additive; forgetting --url in direct-URL workflows or forgetting to drop it when switching to local files.

Related errors

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