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
  • Automate deployment operations with vespa auth api-key

Install Vespa CLI:

To learn the basics on how to use Vespa CLI, see the quick start guide or the cheat sheet below.

See the reference documentation for documentation of individual Vespa CLI commands and their options. This documentation is also bundled with CLI and accessible through vespa help <command> 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

# export a token value for dataplane access
$ export VESPA_CLI_DATA_PLANE_TOKEN='value-of-token'

# Get help
$ vespa document put --help

Login and init

# Use endpoints on localhost
$ vespa config set target local

# Use Vespa Cloud
$ vespa config set target cloud

# 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
 
# Get the deployed application package as a .zip-file
$ vespa fetch

# Deploy an application package from cwd to a prod zone with CD pipeline in Vespa Cloud using deployment.xml
$ vespa prod deploy

# Track deployment to Vespa Cloud status
$ vespa status

# Validate endpoint status, get endpoint only
$ vespa status --format=plain

# Remove a deployment from Vespa Cloud
$ vespa destroy -a vespa-team.vespacloud-docsearch.other

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 --data '
{
    "fields": {
        "album": "A Head Full of Dreams",
        "artist": "Coldplay"
    }
}'


# Put a document, ID in JSON
$ vespa document put --data '
{
    "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 --data '
{
    "fields": {
        "album": {
            "assign": "A Head Full of Thoughts"
        }
    }
}'

# Get one or more documents
$ vespa document get id:mynamespace:music::a-head-full-of-dreams
$ vespa document get id:mynamespace:music::a-head-full-of-dreams id:mynamespace:music::when-we-all-fall-asleep-where-do-we-go

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

# Feed multiple documents or feed from stdin
$ vespa feed *.jsonl
$ cat docs.json | vespa feed -

# Feed to Vespa Cloud
$ vespa feed --application mytenant.myapp -target https://b123e1db.b68a1234.z.vespa-app.cloud feedfile.json

# Print successful and failed operations:
$ vespa feed --verbose docs.json

# Display a periodic summary every 3 seconds while feeding:
$ vespa feed --progress=3 docs.json

# 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 - great for counting total number of documents
$ 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"'

# Export a specific document, including synthetic (generated) fields
$ vespa visit --selection 'id == "id:en:doc::doc-en-7764"' --field-set '[all]'

# Copy documents from one cluster to another:
$ vespa visit --target http://localhost:8080 | vespa feed --target http://localhost:9090 -

Notes:

  • The input files for vespa feed contains either a JSON array of feed operations, or one JSON operation per line (JSONL).
  • The <document-api> must be enabled in the container before documents can be fed or accessed - see example.
  • For automation, see example usage in a GitHub Action. This action uses security credentials in VESPA_CLI_DATA_PLANE_CERT and VESPA_CLI_DATA_PLANE_KEY for easy security management in GitHub.

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

# Query a different port (after modifying http server port)
$ vespa query 'select * from sources * where true' -t 'http://127.0.0.1:9080'

# Use a query file - useful for large queries, e.g., when using query vectors
$ vespa query --file queries-vector.json

Example query file:

{
    "yql": "select product_id, title from products where {targetHits: 200}nearestNeighbor(dense_embedding, q_vector)",
    "input.query(q_vector)": [-0.050548091530799866, ... ,0.028366032987833023],
    "ranking": "vector_distance"
}