CLI reference

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.

Learn more about the Sanity CLI

Learn how to set up and configure the Sanity CLI

Configuration file

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.

Use defineCliConfig from sanity/cli to configure the CLI with TypeScript type-checking:

See the properties table below for all available options.

  • apiCliApiConfig

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

  • deployment{ appId?: string, autoUpdates?: boolean}

    appId: The ID of your studio or app. Generated when deploying your studio or app for the first time.

    autoUpdates: Enable auto-updates for studios.

  • graphqlGraphQLAPIConfig[]

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

  • mediaLibrary{aspectsPath: string}

    aspectsPath: The path to the Media Library aspects directory. When using the CLI to manage aspects, this is the directory they will be read from and written to.

  • 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.

  • reactCompilerReactCompilerConfig
  • 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.

  • 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.

  • viteany

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

  • typegenTypeGenConfig

    Configures automatic TypeScript type generation during sanity dev and sanity build. Properties include enabled, path, generates, and overloadClientMethods. See Sanity TypeGen for details.

  • schemaExtractionObject

    Configures automatic schema extraction during sanity dev and sanity build. Properties: enabled, path, enforceRequiredFields, watchPatterns, workspace.

  • appAppConfig

    Configuration for App SDK applications. Properties: organizationId (required), entry (default: './src/App').

Gotcha

If you run sanity --help outside a folder with a project configuration file and without a specified projectId flag, you will only see the subset of commands that's non project specific.

GraphQLAPIConfig

  • 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.

Commands

USAGE
  $ npx sanity [COMMAND]

TOPICS
  backups     Manage dataset backups
  blueprints  Local Blueprint and remote Stack management commands
  cors        Manage CORS origins for your project
  datasets    Manage datasets in your project
  docs        Browse and search Sanity documentation
  documents   Manage documents in a dataset
  functions   Sanity Function development and management commands
  graphql     Manage GraphQL APIs for your project
  hooks       Manage webhooks for your project
  manifest    Extract studio configuration as JSON manifests
  mcp         Configure Sanity MCP server for AI editors
  media       Manage media assets and aspect definitions
  migrations  Create a new migration within your project
  openapi     Manage OpenAPI specifications
  projects    Manage Sanity projects
  schemas     Manage and validate schemas
  telemetry   Manage telemetry consent
  tokens      Manage API tokens for your project
  typegen     Generate TypeScript types for schema and GROQ
  users       Manage project users and invitations

COMMANDS
  build     Build Sanity Studio into a static bundle
  codemod   Updates Sanity Studio codebase with a code modification script
  debug     Print diagnostic info for troubleshooting
  deploy    Builds and deploys Sanity Studio or application to Sanity hosting
  dev       Start a local development server with live reloading
  doctor    Run diagnostics on your Sanity project
  exec      Executes a script within the Sanity Studio context
  help      Display help for sanity.
  init      Initialize a new Sanity Studio, project and/or app
  install   Install dependencies for the Sanity Studio project
  learn     Open Sanity Learn in your browser
  login     Log in to your Sanity account
  logout    Log out of the current session
  manage    Open project settings in your browser
  preview   Start a local server to preview a production build
  undeploy  Removes the deployed Sanity Studio/App from Sanity hosting
  versions  Show installed package versions

CLI option flag order

For commands with option flags, add the option flag to the end after any arguments. When adding option flags to both commands and subcommands, make sure the command flags are before the subcommand. For example:

sanity COMMAND [args] [--command-flags] SUBCOMMAND [args] --[subcommand-flags]

You can always run sanity COMMAND --help for usage tips and examples.

Changing <hostname>.sanity.studio

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.

Debugging sanity commands

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>).

Example

Least verbose
sanity dataset import production.tar.gz dev

More verbose, returning all debuggers in the sanity namespace
DEBUG=sanity* sanity dataset import production.tar.gz dev

Most verbose, returning all debuggers
DEBUG=* sanity dataset import production.tar.gz dev

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.

Authorizing the CLI

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.

Previous

Sanity CLI

Next

Backups

Was this page helpful?

HTTPS · www.sanity.io
← Home