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 box create` requires exactly one positional argument: the box identifier in `org/box-name` form. Vagrant raises CLIInvalidUsage when argv is empty (no box given) or contains more than one entry; the embedded help text shows the expected form along with the -d/--description, -s/--short-description and -p/--private options.

Source

Thrown at plugins/commands/cloud/box/create.rb:39

              o.separator "Options:"
              o.separator ""

              o.on("-d", "--description DESCRIPTION", String, "Full description of the box") do |d|
                options[:description] = d
              end
              o.on("-s", "--short-description DESCRIPTION", String, "Short description of the box") do |s|
                options[:short] = s
              end
              o.on("-p", "--[no-]private", "Makes box private") do |p|
                options[:private] = p
              end
            end

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

            @client = client_login(@env)

            org, box_name = argv.first.split('/', 2)
            create_box(org, box_name, @client.token, options.slice(:description, :short, :private))
          end

          # Create a new box
          #
          # @param [String] org Organization name of box
          # @param [String] box_name Name of box
          # @param [String] access_token User access token
          # @param [Hash] options Options for box filtering
          # @option options [String] :short Short description of box
          # @option options [String] :description Full description of box
          # @option options [Boolean] :private Set box visibility as private

View on GitHub (pinned to 35f3160f4a)

Solutions

  1. Pass one slash-separated identifier: `vagrant cloud box create myorg/mybox`
  2. Attach metadata as options, not extra positionals: `vagrant cloud box create -s "My box" myorg/mybox`
  3. Check `vagrant cloud box create -h` for the exact banner

Example fix

# before
vagrant cloud box create myorg mybox
# after
vagrant cloud box create myorg/mybox
Defensive patterns

Strategy: validation

Validate before calling

# Ruby wrapper: validate the org/box identifier before shelling out
arg = ARGV[0]
if ARGV.length != 1 || arg.to_s !~ %r{\A[^/\s]+/[^/\s]+\z}
  abort "usage: vagrant cloud box create org/box-name"
end
exec "vagrant", "cloud", "box", "create", *ARGV

Try / catch

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

Prevention

When it happens

Trigger: Running `vagrant cloud box create` with no argument; passing two or more positionals such as `vagrant cloud box create myorg mybox` instead of the slash-separated form; an unquoted identifier containing spaces.

Common situations: Assuming organization and box name are separate arguments (as some CLIs accept); forgetting the organization prefix entirely; scripts that conditionally append an argument and end up passing zero or two.

Related errors

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