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
    • 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
Libraries
Overview
  • Library reference documentation

  • Official clients

    JavaScript Client
    PHP

  • Community clients

    Rust
    LINQ (C#)
    Flutter

  • Frontend tooling

    Next.js toolkit
    Nuxt module
    Astro integration
    @sanity/react-loader
    @sanity/svelte-loader

  • App SDK

    App SDK Explorer
    App SDK Reference

  • Portable Text

    Editor playground
    Standalone Portable Text Editor
    React serializer
    React Native serializer
    React PDF serializer
    Vue serializer
    Svelte serializer
    HTML serializer

  • Utilities

    React RX
    Studio themer
    Embeddings Index CLI reference
    Preview URL Secret

  • Tools

    Vision on demand
    GROQ Playground
    Official vscode / cursor extension

On this page

Previous

Libraries and tooling

Was this page helpful?

On this page

  • Prerequisites
  • Installing the Embeddings Index CLI
  • Embeddings Index CLI commands
  • Commands
  • Options
  • Further reading
LibrariesLast 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>]