vespa-cli.html

---
# Copyright Vespa.ai. All rights reserved.
title: "Vespa CLI"
redirect_from:
- /en/vespa-cli-feed.html
- /en/vespa-cli.html
---

<p>
  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:
</p>
<ul>
  <li>Clone the <a href="https://github.com/vespa-engine/sample-apps/">sample applications</a> repository</li>
  <li>Deploy your application to a Vespa installation running locally or remote</li>
  <li>Deploy your application on <a href="https://cloud.vespa.ai/">Vespa Cloud</a>
  <li>Feed and <a href="../querying/query-language.html#query-examples">query</a> documents</li>
  <li>Send custom requests with automatic authentication</li>
  <li>Automate deployment operations with <a href="../reference/clients/vespa-cli/vespa_auth_api-key">vespa auth api-key</a></li>
</ul>
<p>Install Vespa CLI:</p>
<ul>
  <li>Homebrew: <code>brew install vespa-cli</code></li>
  <li>Mise: <code>mise use vespa-cli</code></li>
  <li><a href="https://github.com/vespa-engine/vespa/releases">Download from GitHub</a></li>
</ul>
<p>
  To learn the basics on how to use Vespa CLI, see
  the <a href="../basics/deploy-an-application-local.html">quick start guide</a> or the <a href="#cheat-sheet">cheat sheet
  below</a>.
</p>
<p>
  See the <a href="../reference/clients/vespa-cli/vespa">reference documentation</a>
  for documentation of individual Vespa CLI commands and their options. This
  documentation is also bundled with CLI and accessible through <code>vespa help
  &lt;command&gt;</code> or <code>man vespa-&lt;command&gt;</code>.
</p>
<p>MTLS keypair location:</p>
<pre>
$ ls -l .vespa/mytenant.myapp.default/
total 16
-rw-r--r--  1 name  staff  3273 Nov  7 08:02 data-plane-private-key.pem
-rw-r--r--  1 name  staff  1697 Nov  7 08:02 data-plane-public-cert.pem
</pre>
<p>
  The <code>.vespa</code> directory should be in the home directory or cwd.
  Remember to run <code>vespa config set target cloud</code> for Vespa Cloud endpoints.
</p>


<h2 id="cheat-sheet">Cheat sheet</h2>


<h3 id="install-configure-and-run">Install, configure and run</h3>
<pre>{% highlight shell %}
# 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
{% endhighlight %}</pre>


<h3 id="login-and-init">Login and init</h3>
<pre>{% highlight shell %}
# 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
{% endhighlight %}</pre>


<h3 id="deployment">Deployment</h3>
<pre>{% highlight shell %}
# Deploy an application package from cwd
$ vespa deploy

# Deploy to a specific zone
$ vespa deploy -z dev.aws-us-east-1c

# 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
{% endhighlight %}</pre>


<h3 id="documents">Documents</h3>
<pre>{% highlight shell %}
# 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 -
{% endhighlight %}</pre>
<p>Notes:</p>
<ul>
  <li>The input files for <code>vespa feed</code> contains either a JSON array of feed operations,
    or one JSON operation per line (<a href="https://jsonlines.org/">JSONL</a>).</li>
  <li>The <a href="../reference/applications/services/container.html#document-api">&lt;document-api&gt;</a>
    must be enabled in the container before documents can be fed or accessed -
    see <a href="https://github.com/vespa-engine/sample-apps/blob/master/album-recommendation/app/services.xml">
      example</a>.</li>
  <li>
    For automation, see example usage in a
    <a href="https://github.com/vespa-engine/documentation/blob/master/.github/workflows/feed.yml">GitHub Action</a>.
    This action uses security credentials in <code>VESPA_CLI_DATA_PLANE_CERT</code> and <code>VESPA_CLI_DATA_PLANE_KEY</code>
    for easy security management in GitHub.
  </li>
</ul>


<h3 id="queries">Queries</h3>
<pre>{% highlight shell %}
# 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
{% endhighlight %}</pre>
<p>Example query file:</p>
<pre>{% highlight json %}
{
    "yql": "select product_id, title from products where {totalTargetHits: 200}nearestNeighbor(dense_embedding, q_vector)",
    "input.query(q_vector)": [-0.050548091530799866, ... ,0.028366032987833023],
    "ranking": "vector_distance"
}
{% endhighlight %}</pre>