CLI Configuration

Wrangle datasets and webhooks, initialise plugin boilerplate code, build and deploy—all from the command line

The sanity Command Line Interface (CLI) is a handy tool for managing your Sanity projects in your terminal. Note that there are some commands that can only be run in a project folder and global ones.

Sanity CLI can read configuration from a sanity.cli.js (.ts) file in the same folder that the command is run in. It will fall back on the configuration in the sanity.config.ts file.

• apiCliApiConfig

  Defines the projectId, dataset that the CLI should connect and run its commands on

• server{ hostname?: string, port?: number }

  Defines the hostname and port that the development server should run on. hostname defaults to localhost, and port to 3333.

• graphqlGraphQLAPIConfig[]

  Defines the GraphQL APIs that the CLI can deploy and interact with.

• reactStrictModeboolean

  Wraps the Studio in <React.StrictMode> root to aid in flagging potential problems related to concurrent features (startTransition, useTransition, useDeferredValue, Suspense). Can also be enabled by setting SANITY_STUDIO_REACT_STRICT_MODE="true"|"false". It only applies to sanity dev in development mode and is ignored in sanity build and in production. Defaults to false.

• viteany

  Exposes the default Vite configuration for the Studio so it can be changed and extended.

• project{ basePath?: string }

  Contains the property basePath which lets you change the top-level slug for the Studio. You typically need to set this if you embed the Studio in another application where it is one of many routes. Defaults to an empty string.

• idstring

  ID of GraphQL API. Only (currently) required when using the --api flag for sanity graphql deploy, in order to only deploy a specific API.

• workspacestring

  Name of workspace containing the schema to deploy

  Optional, defaults to default (eg the one used if no name is defined)

• sourcestring

  Name of source containing the schema to deploy, within the configured workspace

  Optional, defaults to default (eg the one used if no name is defined)

• tagstring

  API tag for this API - allows deploying multiple different APIs to a single dataset

  Optional, defaults to default

• playgroundboolean

  Whether or not to deploy a "GraphQL Playground" to the API url - an HTML interface that allows running queries and introspecting the schema from the browser. Note that this interface is notsecured in any way, but as the schema definition and API route is generally open, this does notexpose any more information than is otherwise available - it only makes it more discoverable.
  Optional, defaults to true

• generation'gen3' | 'gen2' | 'gen1'

  Generation of API to auto-generate from schema. New APIs should use the latest (gen3).

  Optional, defaults to gen3

• nonNullDocumentFieldsboolean

  Define document interface fields (_id, _type etc) as non-nullable. If you never use a document type as an object (within other documents) in your schemas, you can (and probably should) set this to true. Because a document type could be used inside other documents, it is by default set to false, as in these cases these fields can be null.

  Optional, defaults to false

• filterSuffixstring

  Suffix to use for generated filter types.

  Optional, Defaults to Filter.

usage: sanity [--default] [-v|--version] [-d|--debug] [-h|--help] <command> [<args>]

Commands:
   build      Builds the Sanity Studio configuration into a static bundle
   codemod    Runs a code modification script
   cors       Configures CORS settings for Sanity projects
   dataset    Manages datasets, like create or delete, within projects
   debug      Gathers information on Sanity environment
   deploy     Builds and deploys Sanity Studio to Sanity hosting
   dev        Starts a local dev server for Sanity Studio with live reloading
   docs       Opens the Sanity documentation
   documents  Manages documents in your Sanity Content Lake datasets
   exec       Executes a script within the Sanity Studio context
   graphql    Deploys changes to your project's GraphQL API(s)
   help       Displays help information about Sanity
   hook       Sets up and manages webhooks within your Sanity project
   init       Initialize a new Sanity Studio project
   install    Installs dependencies of the current project
   login      Authenticates against the Sanity.io API
   logout     Logs out of the Sanity.io session
   manage     Opens the Sanity project management UI
   migration  Manages content migrations for Content Lake datasets
   preview    Starts a server to preview a production build of Sanity Studio
   projects   Interact with projects connected to your logged in user
   schema     Interacts with Sanity Studio schema configurations
   start      Alias for `sanity preview`
   telemetry  Interact with telemetry settings for your logged in user
   undeploy   Removes the deployed Sanity Studio from Sanity hosting
   users      Manages users of your Sanity project
   versions   Shows the installed versions of Sanity CLI and core components

See 'sanity help <command>' for specific information on a subcommand.

To change the host name of your Sanity-hosted Studio (e.g., https://<1oldHostName>.sanity.studio to https://<2newHostName>.sanity.studio), please see Undeploying the Studio.

Not to be confused with sanity debug, which returns information about your Sanity environment, you can use the DEBUG environment variable with your sanity commands to get more verbose results and troubleshoot potential issues.

For full debugger results, use a wildcard on its own (DEBUG=* sanity <command>). For more targeted results, you can specify a namespace followed by a wildcard (DEBUG=sanity* sanity <command> or DEBUG=sanity:cli* sanity <command>).

Results can also be excluded by using a - prefix. DEBUG=sanity*,-sanity:export* sanity dataset export production production.tar.gz would return all debuggers in the sanity namespace except for sanity:export debuggers (e.g., sanity:cli and sanity:client) during export of the production dataset.

In most cases, you'll use sanity login to authenticate with the Sanity API. When you need to run the CLI unattended, like in a CI/CD environment, set the SANITY_AUTH_TOKEN environment variable to a token. You can generate tokens in the project management dashboard.