Sanity logosanity.ioAll Systems Operational© Sanity 2026
Change Site Theme
Sanity logo

Documentation

    • Overview
    • Platform introduction
    • Next.js quickstart
    • Nuxt.js quickstart
    • Astro quickstart
    • React Router quickstart
    • Studio quickstart
    • Build with AI
    • Content Lake
    • Functions
    • APIs and SDKs
    • Agent Actions
    • Visual Editing
    • Blueprints
    • Platform management
    • Dashboard
    • Studio
    • Canvas
    • Media Library
    • App SDK
    • Content Agent
    • HTTP API
    • CLI
    • Libraries
    • Specifications
    • Changelog
    • User guides
    • Developer guides
    • Courses and certifications
    • Join the community
    • Templates
Content Lake (Datastore)
Overview

  • Understanding Content Lake

    Technical limits
    API Versioning
    API CDN

  • Datasets and documents

    Datasets
    Documents
    Drafts
    IDs and Paths
    Perspectives
    Attribute limit
    Hot swap
    Cloud clone
    Backups

  • Querying with GROQ

    Introduction
    How queries work
    Custom functions
    Query cheat sheet
    Vision plugin
    Syntax reference
    GROQ @ Sanity Learn

  • Querying with GraphQL

    Introduction
    GROQ and GraphQL

  • Mutations

    Introduction to document mutations
    Mutate documents with actions
    Transactions
    Patches
    Document mutation patterns

  • Assets

    Introduction
    Upload, query, and delete assets
    Metadata
    Transformations
    IIIF

  • Content Operations

    Importing Data
    Restore a deleted dataset from a backup
    Migrating your schema and content
    Content migration cheat sheet
    Schema migration principles
    Schema change course @ Sanity Learn

  • Real-time and dynamic content

    Perspectives for preview and presentation
    Live Content API
    Listening API

  • Webhooks

    Introduction
    Best practices
    HTTP API reference
    Toolkit (JS)

  • Embeddings (Experimental)

    Introduction
    Create and query an embeddings index
    Embeddings Index CLI reference
    HTTP API reference

  • Security

    Access Your Data (CORS)
    Browser security & CORS
    Keeping your data safe
    Activity Feed

  • Reference

    GROQ Specification
    Common Sanity document types
    HTTP API
    Roles and permissions
    URL Format
    Authentication
    Using JSONMatch
    IP addresses used by Sanity

On this page

Next

Store and query structured content

Was this page helpful?

On this page

  • Prerequisites
  • Installing the Embeddings Index CLI
  • Embeddings Index CLI commands
  • Commands
  • Options
  • Further reading
Content Lake (Datastore)Last updated January 9, 2026

Embeddings Index CLI reference

Reference documentation of the Sanity Embeddings Index CLI to create and manage embeddings indexes for your content.

Experimental feature

This article describes an experimental Sanity feature. The APIs described are subject to change and the documentation may not be completely accurate.

Using this feature requires Sanity to send data to OpenAI and Pinecone to store vector interpretations of documents.

Gotcha

Embeddings Index API is currently in beta. Features and behavior may change without notice.

Embeddings Index API is available to users on the Team plan and above.

Embeddings Index API functionality is available through the Embeddings Index CLI, the Embeddings Index UI for Sanity Studio, and the Embeddings Index HTTP API.

The Sanity Embeddings Index CLI offers commands to create, delete, fetch, and query embeddings indexes in a Sanity project.

You can install the Embeddings Index CLI:

  • Globally, to make its commands available in the terminal regardless of the current directory path.
  • Locally, on a per-project basis.

To execute the commands without installing the Embeddings Index CLI, invoke them through the npx package runner.

The Embeddings Index CLI commands work only in the context of a local Sanity project:

# Go to the root directory of a Sanity project
cd path-to/my-sanity-project/root-dir

# Invoke the embeddings-index CLI commands
embeddings-index-cli <command> [<arguments>]

# Alternatively: invoke the commands without installing
npx @sanity/embeddings-index-cli <command> [<arguments>]
# Go to the root directory of a Sanity project
cd path-to/my-sanity-project/root-dir

# Invoke the embeddings-index CLI commands
embeddings-index-cli <command> [<arguments>]

# Alternatively: invoke the commands without installing
pnpm dlx @sanity/embeddings-index-cli <command> [<arguments>]
# Go to the root directory of a Sanity project
cd path-to/my-sanity-project/root-dir

# Invoke the embeddings-index CLI commands
embeddings-index-cli <command> [<arguments>]

# Alternatively: invoke the commands without installing
yarn dlx @sanity/embeddings-index-cli <command> [<arguments>]
# Go to the root directory of a Sanity project
cd path-to/my-sanity-project/root-dir

# Invoke the embeddings-index CLI commands
embeddings-index-cli <command> [<arguments>]

# Alternatively: invoke the commands without installing
bunx @sanity/embeddings-index-cli <command> [<arguments>]

Prerequisites

  • The Sanity CLI. The CLI ships with the main Sanity package.
    You need it to log in to Sanity, which enables consuming the Embeddings Index CLI.
  • The Embeddings Index CLI.

Installing the Embeddings Index CLI

# Installing the Embeddings Index CLI globally
npm install --save-dev --global @sanity/embeddings-index-cli

# Installing the Embeddings Index CLI for a specific Sanity project
cd path-to/my-sanity-project/root-dir
npm install --save-dev @sanity/embeddings-index-cli

# Running the Embeddings Index CLI commands without installation
npx @sanity/embeddings-index-cli <command> [<arguments>]
# Installing the Embeddings Index CLI globally
pnpm add --save-dev --global @sanity/embeddings-index-cli

# Installing the Embeddings Index CLI for a specific Sanity project
cd path-to/my-sanity-project/root-dir
pnpm add --save-dev @sanity/embeddings-index-cli

# Running the Embeddings Index CLI commands without installation
pnpm dlx @sanity/embeddings-index-cli <command> [<arguments>]
# Installing the Embeddings Index CLI globally
yarn global add --dev @sanity/embeddings-index-cli

# Installing the Embeddings Index CLI for a specific Sanity project
cd path-to/my-sanity-project/root-dir
yarn add --dev @sanity/embeddings-index-cli

# Running the Embeddings Index CLI commands without installation
yarn dlx @sanity/embeddings-index-cli <command> [<arguments>]
# Installing the Embeddings Index CLI globally
bun add --dev -g @sanity/embeddings-index-cli

# Installing the Embeddings Index CLI for a specific Sanity project
cd path-to/my-sanity-project/root-dir
bun add --dev @sanity/embeddings-index-cli

# Running the Embeddings Index CLI commands without installation
bunx @sanity/embeddings-index-cli <command> [<arguments>]

Embeddings Index CLI commands

To view the built-in help, run:

# Prints the help for the available commands and arguments
embeddings-index-cli --help

# Alternatively, without installing the CLI
npx @sanity/embeddings-index-cli --help
# Prints the help for the available commands and arguments
embeddings-index-cli --help

# Alternatively, without installing the CLI
pnpm dlx @sanity/embeddings-index-cli --help
# Prints the help for the available commands and arguments
embeddings-index-cli --help

# Alternatively, without installing the CLI
yarn dlx @sanity/embeddings-index-cli --help
# Prints the help for the available commands and arguments
embeddings-index-cli --help

# Alternatively, without installing the CLI
bunx @sanity/embeddings-index-cli --help

Commands

  • create

    Creates a new embeddings index in the current Sanity project.
    It requires the following arguments:

    • --indexName: assign a descriptive name to the index.
    • --dataset: specify the name of an existing dataset. This is the target dataset to index. Note that the embeddings index API does not support dataset aliases.
    • --filter: specify the filtering criteria to include in the index only the selected subset of documents from the database.
      The filter must be a valid GROQ filter without the square brackets that wrap the value assigned to _type.
      Example: _type=='tutorial'
    • --projection: specify the projection criteria to include in the index only the selected subset of properties from the filtered documents.
      The projection must be a valid GROQ projection, including curly brackets.
      Example: {title, author}

    Alternatively, you can create an embeddings index by passing a JSON manifest file with the --manifest argument:

    • --manifest <manifest-file-name>.json

    For more information on creating a JSON manifest file, see the CLI manifest command in this reference.

  • delete

    Deletes an existing embeddings index in the current Sanity project.
    It requires the following argument:

    • --indexName: the name of the index to delete.

    Alternatively, you can specify an existing JSON manifest file instead of indexName:

    • --manifest <manifest-file-name>.json
  • get

    Retrieves status information about a specific embeddings index in the current Sanity project.
    It requires the following argument:

    • --indexName: the name of the index whose status you want to retrieve.

    Alternatively, you can specify an existing JSON manifest file instead of indexName:

    • --manifest <manifest-file-name>.json
  • list

    Gets the status of all existing embeddings indexes in a Sanity project.

  • manifest

    Creates a JSON manifest file with the configuration of an embeddings index, and saves the file to the specified location.

    It requires the following arguments:

    • --out: specify the name of the JSON manifest file and, if necessary, the path to the directory to save it to.
      If you don't specify a path, the JSON manifest file is saved to the current location in the Sanity project.
      Example: <manifest-file-name>.json
    • --indexName: see the same argument under create.
    • --dataset: see the same argument under create.
    • --filter: see the same argument under create.
    • --projection: see the same argument under create.
  • query

    Queries an embeddings index.
    Returns an array of document IDs with their relevance score, based on the queried input string.

    It requires the following arguments:

    • --indexName: the name of the index you want to query
    • --text: enter the content that you want to retrieve from the database using the embeddings index.
      The content can be a string of text or a valid JSON-formatted document.

    Examples

    Query the embeddings index to retrieve relevant documents whose content matches the following text string:

    "This is a song about vegetables."

    Query the embeddings index to retrieve relevant documents whose content matches the following JSON document:

    '{"_type": "lyrics", "title": "Call Any Vegetable"}'

Options

  • --debug

    Prints the stack trace. Useful to inspect errors.

  • --help

    Prints the CLI built-in help.

  • --silent

    Doesn't print any information or warning messages.
    Use either --silent or --verbose. Don't specify both options.

  • --verbose

    Logs extensive information and warning messages.
    Use either --silent or --verbose. Don't specify both options.

  • --version

    Prints the version number of the currently installed embeddings index CLI.

Further reading

embeddings-index-cli package on the npm registry

# Go to the root directory of a Sanity project
cd path-to/my-sanity-project/root-dir

# Invoke the embeddings-index CLI commands
embeddings-index-cli <command> [<arguments>]

# Alternatively: invoke the commands without installing
npx @sanity/embeddings-index-cli <command> [<arguments>]
# Go to the root directory of a Sanity project
cd path-to/my-sanity-project/root-dir

# Invoke the embeddings-index CLI commands
embeddings-index-cli <command> [<arguments>]

# Alternatively: invoke the commands without installing
pnpm dlx @sanity/embeddings-index-cli <command> [<arguments>]
# Go to the root directory of a Sanity project
cd path-to/my-sanity-project/root-dir

# Invoke the embeddings-index CLI commands
embeddings-index-cli <command> [<arguments>]

# Alternatively: invoke the commands without installing
yarn dlx @sanity/embeddings-index-cli <command> [<arguments>]
# Go to the root directory of a Sanity project
cd path-to/my-sanity-project/root-dir

# Invoke the embeddings-index CLI commands
embeddings-index-cli <command> [<arguments>]

# Alternatively: invoke the commands without installing
bunx @sanity/embeddings-index-cli <command> [<arguments>]
# Go to the root directory of a Sanity project
cd path-to/my-sanity-project/root-dir

# Invoke the embeddings-index CLI commands
embeddings-index-cli <command> [<arguments>]

# Alternatively: invoke the commands without installing
npx @sanity/embeddings-index-cli <command> [<arguments>]
# Go to the root directory of a Sanity project
cd path-to/my-sanity-project/root-dir

# Invoke the embeddings-index CLI commands
embeddings-index-cli <command> [<arguments>]

# Alternatively: invoke the commands without installing
pnpm dlx @sanity/embeddings-index-cli <command> [<arguments>]
# Go to the root directory of a Sanity project
cd path-to/my-sanity-project/root-dir

# Invoke the embeddings-index CLI commands
embeddings-index-cli <command> [<arguments>]

# Alternatively: invoke the commands without installing
yarn dlx @sanity/embeddings-index-cli <command> [<arguments>]
# Go to the root directory of a Sanity project
cd path-to/my-sanity-project/root-dir

# Invoke the embeddings-index CLI commands
embeddings-index-cli <command> [<arguments>]

# Alternatively: invoke the commands without installing
bunx @sanity/embeddings-index-cli <command> [<arguments>]
# Installing the Embeddings Index CLI globally
npm install --save-dev --global @sanity/embeddings-index-cli

# Installing the Embeddings Index CLI for a specific Sanity project
cd path-to/my-sanity-project/root-dir
npm install --save-dev @sanity/embeddings-index-cli

# Running the Embeddings Index CLI commands without installation
npx @sanity/embeddings-index-cli <command> [<arguments>]
# Installing the Embeddings Index CLI globally
pnpm add --save-dev --global @sanity/embeddings-index-cli

# Installing the Embeddings Index CLI for a specific Sanity project
cd path-to/my-sanity-project/root-dir
pnpm add --save-dev @sanity/embeddings-index-cli

# Running the Embeddings Index CLI commands without installation
pnpm dlx @sanity/embeddings-index-cli <command> [<arguments>]
# Installing the Embeddings Index CLI globally
yarn global add --dev @sanity/embeddings-index-cli

# Installing the Embeddings Index CLI for a specific Sanity project
cd path-to/my-sanity-project/root-dir
yarn add --dev @sanity/embeddings-index-cli

# Running the Embeddings Index CLI commands without installation
yarn dlx @sanity/embeddings-index-cli <command> [<arguments>]
# Installing the Embeddings Index CLI globally
bun add --dev -g @sanity/embeddings-index-cli

# Installing the Embeddings Index CLI for a specific Sanity project
cd path-to/my-sanity-project/root-dir
bun add --dev @sanity/embeddings-index-cli

# Running the Embeddings Index CLI commands without installation
bunx @sanity/embeddings-index-cli <command> [<arguments>]
# Installing the Embeddings Index CLI globally
npm install --save-dev --global @sanity/embeddings-index-cli

# Installing the Embeddings Index CLI for a specific Sanity project
cd path-to/my-sanity-project/root-dir
npm install --save-dev @sanity/embeddings-index-cli

# Running the Embeddings Index CLI commands without installation
npx @sanity/embeddings-index-cli <command> [<arguments>]
# Installing the Embeddings Index CLI globally
pnpm add --save-dev --global @sanity/embeddings-index-cli

# Installing the Embeddings Index CLI for a specific Sanity project
cd path-to/my-sanity-project/root-dir
pnpm add --save-dev @sanity/embeddings-index-cli

# Running the Embeddings Index CLI commands without installation
pnpm dlx @sanity/embeddings-index-cli <command> [<arguments>]
# Installing the Embeddings Index CLI globally
yarn global add --dev @sanity/embeddings-index-cli

# Installing the Embeddings Index CLI for a specific Sanity project
cd path-to/my-sanity-project/root-dir
yarn add --dev @sanity/embeddings-index-cli

# Running the Embeddings Index CLI commands without installation
yarn dlx @sanity/embeddings-index-cli <command> [<arguments>]
# Installing the Embeddings Index CLI globally
bun add --dev -g @sanity/embeddings-index-cli

# Installing the Embeddings Index CLI for a specific Sanity project
cd path-to/my-sanity-project/root-dir
bun add --dev @sanity/embeddings-index-cli

# Running the Embeddings Index CLI commands without installation
bunx @sanity/embeddings-index-cli <command> [<arguments>]
# Prints the help for the available commands and arguments
embeddings-index-cli --help

# Alternatively, without installing the CLI
npx @sanity/embeddings-index-cli --help
# Prints the help for the available commands and arguments
embeddings-index-cli --help

# Alternatively, without installing the CLI
pnpm dlx @sanity/embeddings-index-cli --help
# Prints the help for the available commands and arguments
embeddings-index-cli --help

# Alternatively, without installing the CLI
yarn dlx @sanity/embeddings-index-cli --help
# Prints the help for the available commands and arguments
embeddings-index-cli --help

# Alternatively, without installing the CLI
bunx @sanity/embeddings-index-cli --help
# Prints the help for the available commands and arguments
embeddings-index-cli --help

# Alternatively, without installing the CLI
npx @sanity/embeddings-index-cli --help
# Prints the help for the available commands and arguments
embeddings-index-cli --help

# Alternatively, without installing the CLI
pnpm dlx @sanity/embeddings-index-cli --help
# Prints the help for the available commands and arguments
embeddings-index-cli --help

# Alternatively, without installing the CLI
yarn dlx @sanity/embeddings-index-cli --help
# Prints the help for the available commands and arguments
embeddings-index-cli --help

# Alternatively, without installing the CLI
bunx @sanity/embeddings-index-cli --help
# Go to the root directory of a Sanity project
cd path-to/my-sanity-project/root-dir

# Invoke the embeddings-index CLI commands
embeddings-index-cli <command> [<arguments>]

# Alternatively: invoke the commands without installing
yarn dlx @sanity/embeddings-index-cli <command> [<arguments>]
# Installing the Embeddings Index CLI globally
yarn global add --dev @sanity/embeddings-index-cli

# Installing the Embeddings Index CLI for a specific Sanity project
cd path-to/my-sanity-project/root-dir
yarn add --dev @sanity/embeddings-index-cli

# Running the Embeddings Index CLI commands without installation
yarn dlx @sanity/embeddings-index-cli <command> [<arguments>]
# Installing the Embeddings Index CLI globally
bun add --dev -g @sanity/embeddings-index-cli

# Installing the Embeddings Index CLI for a specific Sanity project
cd path-to/my-sanity-project/root-dir
bun add --dev @sanity/embeddings-index-cli

# Running the Embeddings Index CLI commands without installation
bunx @sanity/embeddings-index-cli <command> [<arguments>]