expand all
collapse 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:

Homebrew: brew install vespa-cli
Download from GitHub

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

# Get help
$ vespa document put --help

# 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 <(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 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