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 list` raises CLIInvalidUsage when given more than one positional argument; it accepts at most one (an optional query string). Note that in this version the backing endpoint is still a TODO — after login the command simply returns 0 — so the usage guard is the only substantive behavior beyond option parsing.

Source

Thrown at plugins/commands/cloud/list.rb:41

            o.on("-j", "--json", "Formats results in JSON") do |j|
              options[:check] = j
            end
            o.on("-l", "--limit", Integer, "Max number of search results (default is 25)") do |l|
              options[:check] = l
            end
            o.on("-p", "--provider", "Comma separated list of providers to filter search. Defaults to all.") do |p|
              options[:check] = p
            end
            o.on("-s", "--sort-by", "Column to sort list (created, downloads, updated)") do |s|
              options[:check] = s
            end
          end

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

          @client = client_login(@env)

          # TODO: This endpoint is not implemented yet

          0
        end
      end
    end
  end
end

View on GitHub (pinned to 35f3160f4a)

Solutions

  1. Pass at most one argument, quoted: `vagrant cloud list "my boxes"`
  2. Use the documented flags (-p, -s) for filtering instead of extra positionals
  3. Use `vagrant cloud search "query"` for working remote queries, since list's endpoint is unimplemented in this version

Example fix

# before
vagrant cloud list ubuntu server
# after
vagrant cloud list "ubuntu server"
Defensive patterns

Strategy: validation

Validate before calling

# bash: at most one positional before invoking
if [ "$#" -gt 1 ]; then
  echo "usage: vagrant cloud list [query]" >&2
  exit 64
fi
exec vagrant cloud list "$@"

Try / catch

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

Prevention

When it happens

Trigger: Running `vagrant cloud list foo bar`; an unquoted multi-word string splitting into two argv entries; forwarding arbitrary user input as multiple arguments from a wrapper.

Common situations: Treating list like search and passing an unquoted query; expecting provider filtering via positional args instead of the -p/--provider and -s/--sort-by flags; scripts passing "$@" where users type multiple words.

Related errors

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