Skip to main content
The sanity init command creates a new Sanity Studio project or initializes a project in an existing directory. It scaffolds the project structure, sets up configuration files, and optionally creates a new Sanity project.

​
Basic Usage

sanity init
This starts an interactive wizard that guides you through:
  1. Authentication (if not logged in)
  2. Project selection or creation
  3. Dataset configuration
  4. Template selection
  5. Output path specification
  6. Package manager choice
The recommended way to initialize a new project is using the create command: 
npm create sanity@latest
This provides the latest templates and best practices for new projects.

​
Options

​
Project Configuration

  • --project <projectId>, --project-id <projectId> - Project ID to use for the studio
  • --organization <organizationId> - Organization ID to use for the project
  • --create-project <name> - Create a new project with the given name
  • --project-plan <name> - Select a plan for a new project
  • --coupon <name> - Apply a coupon for a new project (cannot be used with --project-plan)

​
Dataset Configuration

  • --dataset <dataset> - Dataset name for the studio
  • --dataset-default - Set up a project with a public dataset named “production”
  • --visibility <mode> - Visibility mode for dataset (public or private)

​
Template & Output

  • --template <template> - Project template to use (default: “clean”)
  • --output-path <path> - Path to write studio project to
  • --overwrite-files - Overwrite existing files (default: false)

​
Build Configuration

  • --no-typescript - Do not use TypeScript for template files
  • --package-manager <name> - Specify package manager (npm, pnpm, yarn, bun)
  • --auto-updates - Enable/disable auto updates of studio versions (default: true)

​
Authentication & Mode

  • --provider <provider> - Login provider to use
  • -y, --yes - Unattended mode, accepting defaults and using only flags
  • --bare - Skip Studio initialization, only print project ID and dataset name to stdout
  • --env <filename> - Write environment variables to file (default: “.env”)
  • --no-mcp - Skip AI editor integration (MCP) setup

​
Next.js Specific

When initializing in a Next.js project:
  • --nextjs-add-config-files - Add config files to Next.js project (default: true)
  • --nextjs-embed-studio - Embed Studio in Next.js application (default: true)
  • --nextjs-append-env - Append project ID and dataset to .env file (default: true)

​
Examples

sanity init

​
Templates

Sanity provides several starter templates:
  • clean - Minimal clean slate (default)
  • moviedb - Movie database example
  • blog - Blog with posts and authors
  • shopify - E-commerce with Shopify integration
  • podcast - Podcast management
You can also use custom templates from GitHub repositories.

​
What Gets Created

Running sanity init creates: 
project-name/
├── sanity.config.ts       # Studio configuration
├── sanity.cli.ts          # CLI configuration
├── package.json           # Dependencies
├── tsconfig.json          # TypeScript config
├── .env                   # Environment variables
├── schemas/               # Schema definitions
│   └── index.ts
└── public/                # Static assets
    └── favicon.ico

​
Configuration Files

​
sanity.config.ts

Defines your Studio configuration:
sanity.config.ts
import {defineConfig} from 'sanity'
import {structureTool} from 'sanity/structure'
import {visionTool} from '@sanity/vision'
import {schemaTypes} from './schemas'

export default defineConfig({
  name: 'default',
  title: 'My Project',
  projectId: 'abc123',
  dataset: 'production',
  plugins: [structureTool(), visionTool()],
  schema: {
    types: schemaTypes,
  },
})

​
sanity.cli.ts

Defines CLI-specific settings:
sanity.cli.ts
import {defineCliConfig} from 'sanity/cli'

export default defineCliConfig({
  api: {
    projectId: 'abc123',
    dataset: 'production',
  },
})

​
Unattended Mode

For CI/CD pipelines or scripts, use unattended mode: 
sanity init -y \
  --project my-project-id \
  --dataset production \
  --output-path ./studio
Unattended mode (-y or --yes) accepts defaults for all prompts. Ensure you provide all required flags.

​
Framework Detection

The CLI automatically detects frameworks in your directory:
  • Next.js
  • Remix
  • Astro
  • SvelteKit
  • Nuxt
Behavior adapts based on the detected framework.
For Next.js projects, the CLI offers to embed the Studio directly in your application.

​
Troubleshooting

​
Authentication Required

If not logged in, run: 
sanity login

​
Overwriting Existing Files

To overwrite existing files without prompts: 
sanity init --overwrite-files -y

​
Custom Package Manager

Specify your preferred package manager: 
sanity init --package-manager pnpm

​
Next Steps

After initialization:
  1. Navigate to your project directory
  2. Start the development server: sanity dev
  3. Define your schema in schemas/
  4. Customize sanity.config.ts

Development Server

Learn how to run the local development server

Build docs developers (and LLMs) love

Get started for freeTalk to us