• [+] expand all

Vespa CLI

Vespa CLI is the command-line client for Vespa. It is a single binary without any runtime dependencies and is available for Linux, macOS and Windows. With Vespa CLI you can:

  • Clone the sample applications repository
  • Deploy your application to a Vespa installation running locally or remote
  • Deploy your application in Vespa Cloud
  • Feed and query documents
  • Send custom requests with automatic authentication

Install Vespa CLI:

To learn the basics on how to use Vespa CLI, see the quick start guide, or the cheat sheet below. For documentation on individual Vespa CLI commands and their options, see the bundled man pages, e.g. man vespa or man vespa-<command>.

Cheat sheet

Install, configure and run

# Install - make sure to upgrade frequently for new features
$ brew install vespa-cli
$ brew upgrade vespa-cli

# Set home dir to a writeable directory - useful in some container contexts
$ export VESPA_CLI_HOME=/tmp

# Get help
$ vespa document put --help

Login and init

# Use a browser to log into Vespa Cloud
$ vespa auth login

# Configure application instance
$ vespa config set application vespa-team.vespacloud-docsearch.default

# Configure application instance, override global configuration (write to local .vespa)
$ vespa config set --local application vespa-team.vespacloud-docsearch.other

Deployment

# Deploy an application package from cwd
$ vespa deploy

# Track deployment to Vespa Cloud status
$ vespa status

Documents

# Put a document from file
$ vespa document put file-with-one-doc.json

# Put a document
$ vespa document put id:mynamespace:music::a-head-full-of-dreams <(echo '
{
    "fields": {
        "album": "A Head Full of Dreams",
        "artist": "Coldplay"
    }
}
')

# Put a document, ID in JSON
$ vespa document put <(echo '
{
    "put": "id:mynamespace:music::a-head-full-of-dreams",
    "fields": {
        "album": "A Head Full of Dreams",
        "artist": "Coldplay"
    }
}
')

# Update a document
$ vespa document update id:mynamespace:music::a-head-full-of-dreams <(echo '
{
    "fields": {
        "album": {
            "assign": "A Head Full of Thoughts"
        }
    }
}
')

# Get a document
$ vespa document get id:mynamespace:music::a-head-full-of-dreams

# Delete a document
$ vespa document remove id:mynamespace:music::a-head-full-of-dreams

# Feed multiple documents
$ vespa feed *.jsonl

# Export all documents in "doc" schema, using "default" container cluster
$ vespa visit --zone prod.aws-us-east-1c --cluster default --selection doc

# Export slice 0 of 10 - approximately 10% of the documents
$ vespa visit --slices 10 --slice-id 0

# List IDs
$ vespa visit --field-set "[id]"

# Export fields "title" and "term_count" from "doc" schema
$ vespa visit --field-set "doc:title,term_count"

# Export documents using a selection string
$ vespa visit --selection 'doc.last_updated > now() - 86400'

# Export all documents in "doc" schema, in "open" namespace
$ vespa visit --selection 'doc AND id.namespace == "open"'

Queries

# Query for all documents in all schemas / sources
$ vespa query 'yql=select * from sources * where true'

# YQL parameter is assumed if missing - this is equivalent to the above
$ vespa query 'select * from sources * where true'

# Query with an extra query API parameter
$ vespa query 'select * from music where album contains "head"' \
  hits=5

# Use verbose to print a curl equivalent, too
$ vespa query -v 'select * from music where album contains "head"' hits=5