Sanity CLI for coding agents

When a coding agent needs to inspect content in a Sanity project, the Sanity Command Line Interface (CLI) lets it run queries and manage documents from a terminal. A Sanity dataset is the collection of content records, such as articles or product pages, that a project stores in Sanity’s hosted content service.

For a read-only task, an agent can query the dataset to find content or check field values. The CLI runs from the project’s shell, while the query reaches Sanity over the network. The examples below follow Sanity’s documentation; they have not been installed or tested for this article.

What the CLI does

Sanity describes its CLI as a set of tools for managing, developing, debugging, and deploying Sanity Studio projects, as well as running scripts that migrate or manipulate data. For content work, sanity documents query can retrieve dataset documents using GROQ, Sanity’s query language.

An agent can use the command to find records before changing code that reads them. For example, an agent working on an article listing could inspect several article records to confirm which fields the dataset contains. The query only reads content; commands that create, edit, or delete documents are separate actions.

Set up the CLI and sign in

Sanity recommends running the CLI through npx sanity@latest, which downloads and runs the current CLI version without requiring a global installation. Run it from the root of a configured Sanity Studio project, where the project configuration identifies the Sanity project and dataset. Sanity also warns that a previous global installation can cause version collisions. See the CLI installation guidance before adding a global install.

For an interactive session, sign in with:

npx sanity@latest login

For an unattended run, such as one started by an agent in a continuous integration (CI) environment, Sanity documents the SANITY_AUTH_TOKEN environment variable. Create a token in the project management dashboard and make it available to the agent’s shell through the environment or a secret manager. Do not put the token in the agent prompt or commit it to the repository. Sanity’s CLI configuration documentation describes both authentication methods.

Query documents without changing them

Replace article below with a document type defined in the project’s schema. The command requests up to five matching documents and returns only their IDs and types:

npx sanity@latest documents query '*[_type == "article"][0...5]{_id, _type}'

The quoted GROQ expression filters records by _type, takes up to five matches, and returns two fields. The query runs against the configured Sanity dataset, so the agent needs network access and credentials that let it read that dataset. It does not write to Sanity.

A coding agent could use this result to identify document IDs for a follow-up task, or to check whether the expected document type exists before editing a site’s query code. A prompt for that read-only task might be:

Use the Sanity CLI from this project’s root to query up to five documents of the article type. Report their IDs and types. Do not create, edit, or delete any Sanity documents.

If the project uses a different document type, the agent should substitute its actual schema type before running the query. The command returns results from the project and dataset configured in the CLI, and only when matching content exists. The output depends on that content.

Keep reads and writes separate

A query helps an agent inspect content, but it does not validate whether an editorial change is correct or whether a later write is safe. Sanity’s documents command reference also explains commands for managing documents. Before you let an agent run one of those commands, choose the records it should change and review the proposed data separately. Do not treat a successful query as approval to write.

The CLI sends commands directly to the Sanity service. Local command execution does not mean the data stays local: a query sends a request to the configured dataset, and a document-management command can change content stored there. For agent use, start with read-only queries and grant the shell only the credentials needed for the task.