Structured Content 101: Find out how to make your content work harder (without your team working harder) →

Setting up with Sanity CLI

How to get started with Sanity.io using the command line interface.

In this guide, you will learn how to get started with a project on Sanity.io from the command line interface (CLI). We will walk you through installing the necessary tooling, initiating a project, and starting the local development server for Sanity Studio. You will also learn how to deploy to *.sanity.studio and how to invite collaborators to the project.

Install CLI tooling

Don't have Node and npm installed? No problem, we have instructions.

npm install -g @sanity/cli

The command line tool is used to set up new projects, manage datasets, import data, and much more. We'll be using it to get your project up and running.

Getting help

The command line tool offers an overview of the available commands using the sanity help command. You can add options to drill down and get additional details. For example:

  • sanity help - an overview of the top-level commands you have available. You will get this same output by running the sanity command with no options.
  • sanity help projects - an overview of the commands available when you run sanity projects.
  • sanity help projects list - an overview of the options available and examples of using sanity projects list.

Gotcha

You will have many more CLI options available when you run sanity or sanity help inside a studio folder (25 at the time of this writing compared to 12 when not in a studio folder). If you're not seeing options like build, cors, dataset, deploy, and exec, then you are likely not in a studio folder or your project is not yet initialized.

Bootstrap a project

Sanity Studio has most of its logic and code contained in NPM packages. This makes it really easy to upgrade to new versions (sanity upgrade) and to install and ship plugins as self-contained packages.

To get started with a new project, run this command after you have installed the CLI tool:

sanity init

This will log you into Sanity, create a project, set up a dataset, and generate the files needed to run the development server locally. There are a number of options available, which you can see here or by running sanity help init.

If you are not logged in, there will be a prompt to do so. If you are, the sanity init command will prompt you for the following:

  1. Select an existing project or create a new project. (If you're in an existing project, you'll first be asked if you want to reconfigure it. When reconfiguring a studio, the prompts will be slightly different from the following but should give you clear feedback about what's happening.) Your existing projects will be listed from oldest to newest (but you can press Up to get to the bottom of the list quickly).
  2. Enter a project name. This will be the name used for the project at sanity.io/manage. If you selected an existing project in step 1, you will not see this option (but you can rename a project from the Settings tab of Manage).
  3. If you're using @sanity/cli@2.29.3 or later, you can select an organization to which you want to assign the project (the organization must already exist and the user must have sufficient permissions to assign a project), or select None to add the project to your personal projects. An organization gives you a way to group projects and is required to add billing details or upgrade a project. You can always transfer a project to or between organizations later.
  4. Select whether to use the default dataset configuration (a public dataset named production). If you select no, you will be prompted to enter a dataset name and visibility.
  5. Enter an output path. If the path in parentheses looks good, you can press Enter. You can also type a folder name (e.g., studio), which will exist as a subfolder in the directory where you ran sanity init.
  6. Select a project template. Depending on your selection, your studio may be pre-configured with sample data and/or a sample schema from which you can model your content. If you want to work from an empty schema and dataset, select Clean project with no predefined schemas. Note that if you select a template, you can always add a new empty dataset later.

If you get a Success! message, your studio is configured and you're ready to go. Proceed with the options listed in the terminal or continue reading this guide.

Protip

You can use the sanity init command to reinitialize an existing project, which lets you change the project ID, change the dataset, or set up a new dataset. You might want to do this if you have existing studio code but want to connect it to a new or different project. Running sanity init in an existing project will change the details in sanity.json but will not delete or overwrite any of your existing files.

Run the studio

To start the development server for Sanity Studio, run this command within the studio folder:

sanity start

This builds the initial JavaScript code required to run the studio and starts a local web server. As you modify and save the code, the server will automatically rebuild the studio and refresh the browser.

The studio is just an HTML file and some JavaScript bundles that run in your browser. It talks to the Sanity API which stores your data and lets you query it from whatever platform or front-end you want.

You can end your development server by pressing Ctrl-C in the terminal where the server is running.

Gotcha

You will need to kill and restart the server to see the effect of certain changes. These include changes to sanity.json, addition or removal of plugins, and anything that involves .env files.

Edit the schema

Open the studio folder in your code editor, and locate the schema.js file in the schemas folder. The schema defines your content model. We recommend that you start by modelling your content logically, without thinking too much about how it's going to be presented. We've written about why this often makes a lot of sense.

Schemas are a pretty big topic. For now, you can just take a quick look at how the schema is defined, and move on to the next step.

Deploy the studio

You can host the studio wherever you like, but we've made it easy for you to get started by deploying it to our cloud platform. Running the following command will build your studio to a static bundle and deploy it to a <your-project>.sanity.studio URL with a name of your choosing (must be unique amongst all Sanity-deployed studios):

sanity deploy

When you change something in the Studio locally, you can rerun this command to deploy the latest changes. Currently, each project can only be deployed to one sanity.studio URL at a time.

Protip

We recommend checking the studio files into git (GitHub, GitLab, Bitbucket, or a self-hosted git repository are four possible setups). While it's technically possible to derive your schemas back from your compiled studio, it's not a simple process, requires your studio be deployed, and will only be as current as your latest deployment. It also will not include your custom components and code.

You'll save yourself potential time and headaches by having your studio in git and pushed to a remote repository. This is also the ideal way to share the studio with other developers.

Our API requires that you define which origins should be permitted to query the API. It's taken care of when you deploy to our servers, but if you host the project yourself you'll need to set up your CORS origins to allow in the Sanity project dashboard. You'll also need to configure your CORS origins when sourcing your data, such as from your front end.

Protip

Do you need to change the subdomain for <yourName>.sanity.studio? Run sanity undeploy to remove the studio from its current domain. When you run sanity deploy again, you will be prompted to set a new subdomain.

Invite collaborators

Once your studio is deployed, you can invite collaborators to your project.

sanity users invite your-friend@a-domain.com

You can invite other users to your project with the sanity users invite command. Use the --role option to specify a role, or omit the flag and you will be prompted to select from all available options. An invitation will be sent with a link that lets the person log in using a Google or GitHub account, or they can create a Sanity account and log in with email and password.

Protip

You can also invite collaborators from the Members tab of your project at sanity.io/manage.

What's next?

To continue learning more about Sanity and the Studio, a good next step is to familiarize yourself with datasets and content modelling.

Was this article helpful?