Sanity CLI

@sanity/cli is the official command-line tool for the Sanity structured-content platform, covering the full project lifecycle from scaffolding a new Sanity Studio through dataset management, GraphQL/schema deployment, content migrations, and production hosting.

Built on the oclif CLI framework, it exposes dozens of subcommands organized by domain (datasets, documents, GraphQL, migrations, hooks, tokens, users, organizations, backups, CORS, workflows, blueprints) and ships as the sanity binary installed alongside Sanity Studio projects, with built-in telemetry, framework auto-detection for sanity init, and TypeScript type generation via sanity typegen.

What You Get

• Project scaffolding via sanity init, with framework auto-detection
• Dataset operations: create, list, copy, alias, import, export, backup
• Schema and GraphQL deployment/validation commands
• A content migration framework (sanity migrations create/list/run)
• TypeScript type generation from GROQ queries and schemas
• Studio dev server, static build, deploy, and preview commands
• Token, user, and organization management for project access control
• Webhook (sanity hooks) and CORS origin management

Common Use Cases

• Bootstrapping a new Sanity Studio, optionally paired with a frontend framework
• Exporting and importing datasets between environments (prod/staging)
• Automating schema and GraphQL API deployment in CI/CD pipelines
• Running structured content migrations across a dataset
• Generating TypeScript types from GROQ queries as part of the build

Under The Hood

Architecture The CLI is structured as an oclif application: src/commands/ defines the thin command surface (argument/flag parsing, one file per command or per resource sub-namespace like datasets/, migrations/, organizations/), which delegates to a much larger src/actions/ layer holding the actual business logic per domain (init, dataset, deploy, graphql, migration, schema, telemetry, tokens, typegen, users). Cross-cutting concerns live in src/services/ (auth/session), src/hooks/ (oclif lifecycle hooks for init, prerun, and unknown-command handling), and src/config/ (project-level createCliConfig/defineCliConfig for consumer sanity.cli.ts files). Shared primitives (error types, exit codes, UX helpers) are pulled from an internal @sanity/cli-core package rather than duplicated, and telemetry instrumentation wraps most actions via a shared trace helper, so changing the oclif command-registration boundary or the action-layer contract would ripple through every command in the tree.

Tech Stack Written entirely in TypeScript on Node.js, the CLI is built with the oclif framework for command parsing and help generation, compiled with SWC and a dedicated package-utils tool for type declarations, and orchestrated inside a pnpm and Turborepo monorepo alongside sibling packages such as the shared cli-core, cli-build, and workbench-cli packages. It shells out to subprocesses for package-manager and git operations, detects the host frontend framework during sanity init, and integrates with Sanity’s own client, telemetry package, and GROQ/schema tooling for type generation. Testing runs on Vitest with coverage instrumentation, HTTP interactions are mocked in tests, and releases are versioned and published via an automated changeset workflow.

Code Quality The package colocates an extensive set of test files in __tests__ directories next to the modules they exercise, covering commands, actions, prompts, and utilities. The whole codebase is TypeScript with strict type-checking run in CI, linted via a custom shared ESLint config, auto-formatted by a dedicated formatter, and enforced pre-commit via git hooks and lint-staged; a dependency-usage checker runs in CI to catch unused dependencies and exports. Errors are modeled as typed exceptions carrying explicit exit codes rather than bare throws, and the monorepo runs a wide bank of CI workflows (build, lint, unit/e2e/integration tests, dependency checks, PR title validation) on every change.

API Design The CLI presents one consistent command tree (sanity <resource> <verb>) across a large and still-growing surface — datasets, documents, schemas, GraphQL, migrations, tokens, users, organizations, hooks, CORS, backups, media, workflows, and newer “blueprints” and AI-oriented context/learn/docs commands — all self-documented via generated help and an auto-updated README command reference. sanity init goes further than scaffolding, auto-detecting the host framework to wire environment variables and config files, and MCP/skills setup commands extend the CLI into AI-assisted editor tooling — a broader scope than a typical single-purpose CLI, though it’s built on a standard command-framework pattern rather than a novel parsing approach.