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 search` requires exactly one positional argument — the search query. Zero args or more than one raises CLIInvalidUsage. Because an unquoted multi-word query arrives as several argv entries, `vagrant cloud search ubuntu server` fails the `argv.length != 1` guard even though the intent was a single query.

Source

Thrown at plugins/commands/cloud/search.rb:57

            o.on("-l", "--limit LIMIT", Integer, "Max number of search results Default: 25") do |l|
              options[:limit] = l
            end
            o.on("-p", "--provider PROVIDER", String, "Filter search results to a single provider. Defaults to all.") do |p|
              options[:provider] = p
            end
            o.on("--sort-by SORT", "Field to sort results on (created, downloads, updated) Default: downloads") do |s|
              options[:sort] = s
            end
            o.on("--[no-]auth", "Authenticate with Vagrant Cloud if required before searching") do |l|
              options[:quiet] = !l
            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, options.slice(:quiet))
          query = argv.first

          options[:limit] = 25 if !(options[:limit].to_i < 1) && !options[:limit]

          search(query, @client&.token, options)
        end

        # Perform requested search and display results to user
        #
        # @param [String] query Search query string
        # @param [Hash] options
        # @option options [String] :provider Filter by provider
        # @option options [String] :sort Field to sort results
        # @option options [Integer] :limit Number of results to display

View on GitHub (pinned to 35f3160f4a)

Solutions

Quote the query: `vagrant cloud search "ubuntu server"`
Guard empty queries in scripts: `[ -n "$QUERY" ] && vagrant cloud search "$QUERY"`
Use options for everything else: --limit, --provider, --sort-by, --[no-]auth

Example fix

# before
vagrant cloud search ubuntu server
# after
vagrant cloud search "ubuntu server"

Defensive patterns

Strategy: validation

Validate before calling

# bash: require exactly one quoted query
if [ "$#" -ne 1 ] || [ -z "$1" ]; then
  echo "usage: vagrant cloud search QUERY" >&2
  exit 64
fi
exec vagrant cloud search "$@"

Try / catch

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

Prevention

Always quote search queries — multi-word input is the top cause of this error
Default an empty query variable to a deliberate value instead of passing nothing
In scripts pass one variable ("$QUERY"), never "$@", to search

When it happens

Trigger: `vagrant cloud search` with no query; an unquoted multi-word query splitting into 2+ argv entries; flags placed after the query without their values being recognized; an empty $QUERY variable collapsing to zero args.

Common situations: Unquoted search strings — the most common cause; scripts passing "$@" instead of one quoted variable; assuming search behaves like `vagrant box search` of older releases.

Related errors

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