CLI referenceLast updated May 7, 2026

Blueprints CLI command reference

Reference documentation for the Sanity CLI Blueprints command.

The blueprints CLI command enables initializing, managing, and deploying Blueprints and resources like Functions.

Blueprints introduction

Learn what Blueprints are, how they work, and how to get started.

Functions introduction

Learn how to take advantage of Functions in your Sanity projects.

Commands

`add`

USAGE
  $ sanity blueprints add TYPE [--install] [-n <value>] [--example <value>] [--fn-helpers] [--fn-installer <value>] [--fn-type <value>] [--javascript] [--json] [--language <value>]

ARGUMENTS
  TYPE  Type of resource to add (only "function" is supported)

FLAGS
  -i, --install               Shortcut for --fn-installer npm
  -n, --name=<value>          Name of the resource to add
      --example=<value>       Example to use for the function resource. Discover examples at https://www.sanity.io/exchange/type=recipes/by=sanity
      --fn-helpers            Add helpers to the new function
      --fn-installer=<value>  Which package manager to use when installing the @sanity/functions helpers
      --fn-type=<value>       Document change event(s) that should trigger the function; you can specify multiple events by specifying this flag multiple times
      --javascript            Use JavaScript instead of TypeScript
      --json                  Format output as json
      --language=<value>      Language of the new function

DESCRIPTION
  This command is deprecated. Use "functions add" instead.
  
  Equivalent usage:
    $ <%= config.bin %> functions add
    $ <%= config.bin %> functions add --name my-function --type document-create

EXAMPLES
    $ sanity blueprints add function

    $ sanity blueprints add function --helpers

    $ sanity blueprints add function --name my-function

    $ sanity blueprints add function --name my-function --fn-type document-create

    $ sanity blueprints add function --name my-function --fn-type document-create --fn-type document-update --lang js

`config`

USAGE
  $ sanity blueprints config [--edit] [--json] [--organization-id <value>] [--project-id <value>] [--stack <value>]

FLAGS
  -e, --edit                     Modify the configuration interactively, or directly when combined with ID flags.
      --json                     Format output as json
      --organization-id=<value>  Sanity organization ID used to scope Blueprint and Stack
      --project-id=<value>       Sanity project ID used to scope Blueprint and Stack
      --stack=<value>            Stack name or ID to set in the configuration. Requires --edit flag

DESCRIPTION
  Manages the local Blueprint configuration, which links your Blueprint to a Sanity project and Stack.
  
  Without flags, displays the current configuration. Use --edit to interactively modify settings, or combine --edit with ID flags to update values directly (useful for scripting and automation).
  
  If you need to switch your Blueprint to a different Stack, use --edit --stack.

EXAMPLES
    $ sanity blueprints config

    $ sanity blueprints config --edit

    $ sanity blueprints config --edit --project-id <projectId>

    $ sanity blueprints config --edit --project-id <projectId> --stack <name-or-id>

`deploy`

USAGE
  $ sanity blueprints deploy [-m <value>] [--json] [--new-stack-name <value>] [--no-wait] [--organization-id <value>] [--project-id <value>] [--stack <value>]

FLAGS
  -m, --message=<value>          Message describing the deployment (e.g. reason for change)
      --json                     Format output as json
      --new-stack-name=<value>   Set a new name for the Stack
      --no-wait                  Do not wait for Stack deployment to complete
      --organization-id=<value>  Sanity organization ID used to scope Blueprint and Stack
      --project-id=<value>       Sanity project ID used to scope Blueprint and Stack
      --stack=<value>            Stack name or ID to use instead of the locally configured Stack

DESCRIPTION
  Applies your local Blueprint to the remote Stack, creating, updating, or removing resources as needed. This is the primary command for applying infrastructure changes.
  
  Before deploying, run 'blueprints plan' to preview changes. After deployment, use 'blueprints info' to verify Stack status or 'blueprints logs' to monitor activity.
  
  Use --no-wait to queue the deployment and return immediately without waiting for completion.
  
  Use --fn-installer to force which package manager to use when deploying functions.
  
  Set SANITY_ASSET_TIMEOUT (seconds) to override the 60-second timeout for processing resource assets.

EXAMPLES
    $ sanity blueprints deploy

    $ sanity blueprints deploy --message "Enable staging dataset"

    $ sanity blueprints deploy --no-wait

    $ sanity blueprints deploy --fn-installer npm

    $ sanity blueprints deploy --stack <name-or-id>

    $ sanity blueprints deploy --organization-id <orgId> --stack <name-or-id>

    $ sanity blueprints deploy --new-stack-name <new-name>

`destroy`

USAGE
  $ sanity blueprints destroy [--force] [--json] [--no-wait] [--organization-id <value>] [--project-id <value>] [--stack <value>]

FLAGS
      --force                    Force Stack destruction (skip confirmation)
      --json                     Format output as json
      --no-wait                  Do not wait for Stack destruction to complete
      --organization-id=<value>  Sanity organization ID used to scope Blueprint and Stack
      --project-id=<value>       Sanity project ID used to scope Blueprint and Stack
      --stack=<value>            Stack name or ID to destroy (defaults to the locally configured Stack)

DESCRIPTION
  Permanently removes the remote Stack and all its provisioned resources. Your local Blueprint files remain untouched, allowing you to redeploy later with 'blueprints init' + 'blueprints deploy'.
  
  This is a destructive operation. You will be prompted to confirm unless --force is specified.
  
  Use this to clean up test environments or decommission a Stack you no longer need.

EXAMPLES
    $ sanity blueprints destroy

    $ sanity blueprints destroy --stack <name-or-id> --project-id <projectId> --force --no-wait

`doctor`

USAGE
  $ sanity blueprints doctor [-p <value>] [--fix] [--json] [--verbose]

FLAGS
  -p, --path=<value>  Path to a Blueprint file or directory containing one
      --fix           Interactively fix configuration issues
      --json          Format output as json
      --verbose       Verbose output; defaults to true

DESCRIPTION
  Analyzes your local Blueprint and remote Stack configuration for common issues, such as missing authentication, invalid project references, or misconfigured resources.
  
  Run this command when encountering errors with other Blueprint commands. Use --fix to interactively resolve detected issues.

EXAMPLES
    $ sanity blueprints doctor

    $ sanity blueprints doctor --fix

`info`

USAGE
  $ sanity blueprints info [--json] [--organization-id <value>] [--project-id <value>] [--stack <value>]

FLAGS
      --json                     Format output as json
      --organization-id=<value>  Sanity organization ID used to scope Blueprint and Stack
      --project-id=<value>       Sanity project ID used to scope Blueprint and Stack
      --stack=<value>            Stack name or ID

DESCRIPTION
  Displays the current state and metadata of your remote Stack deployment, including deployed resources, status, and configuration.
  
  Use this command to verify a deployment succeeded, check what resources are live, or confirm which Stack your local Blueprint is connected to.
  
  Run 'blueprints stacks' to see all available Stacks in your project or organization.

EXAMPLES
    $ sanity blueprints info

    $ sanity blueprints info --stack <name-or-id>

    $ sanity blueprints info --project-id <id> --stack <name-or-id>

    $ sanity blueprints info --organization-id <orgId> --stack <name-or-id>

`init`

USAGE
  $ sanity blueprints init [DIR] [--blueprint-type <value>] [--dir <value>] [--example <value>] [--json] [--organization-id <value>] [--project-id <value>] [--stack-id <value>] [--stack-name <value>]

ARGUMENTS
  [DIR]  Directory to create the local Blueprint in

FLAGS
      --blueprint-type=<value>   Blueprint manifest type to use for the local Blueprint
      --dir=<value>              Directory to create the local Blueprint in
      --example=<value>          Example to use for the local Blueprint
      --json                     Format output as json
      --organization-id=<value>  Sanity organization ID used to scope Blueprint and Stack
      --project-id=<value>       Sanity project ID used to scope Blueprint and Stack
      --stack-id=<value>         Existing Stack ID used to scope local Blueprint
      --stack-name=<value>       Name to use for a new Stack provisioned during initialization

DESCRIPTION
  A Blueprint is your local infrastructure-as-code configuration that defines Sanity resources (datasets, functions, etc.). A Stack is the remote deployment target where your Blueprint is applied.
  [NOTE: Currently, accounts are limited to three (3) Stacks per project scope.]
  
  This is typically the first command you run in a new project. It creates a local Blueprint manifest file (sanity.blueprint.ts, .js, or .json) and provisions a new remote Stack.
  Additionally, a Blueprint configuration file is created in .sanity/ containing the scope and Stack IDs. This is .gitignored by default.
  
  After initialization, use 'blueprints plan' to preview changes, then 'blueprints deploy' to apply them.

EXAMPLES
    $ sanity blueprints init

    $ sanity blueprints init [directory]

    $ sanity blueprints init --blueprint-type <json|js|ts>

    $ sanity blueprints init --blueprint-type <json|js|ts> --project-id <projectId> --stack-id <stackId>

    $ sanity blueprints init --blueprint-type <json|js|ts> --stack-name <stackName>

`logs`

USAGE
  $ sanity blueprints logs [-l <value>] [--watch] [--before <value>] [--json] [--organization-id <value>] [--project-id <value>] [--since <value>] [--stack <value>]

FLAGS
  -l, --limit=<value>            Maximum number of log entries to retrieve (1-500)
  -w, --watch                    Watch for new Stack logs
      --before=<value>           Only show logs before this ISO 8601 timestamp
      --json                     Format output as json
      --organization-id=<value>  Sanity organization ID used to scope Blueprint and Stack
      --project-id=<value>       Sanity project ID used to scope Blueprint and Stack
      --since=<value>            Only show logs after this ISO 8601 timestamp
      --stack=<value>            Stack name or ID to use instead of the locally configured Stack

DESCRIPTION
  Retrieves Stack deployment logs, useful for debugging and monitoring deployment activity.
  
  Use --watch (-w) to tail logs in real-time.
  
  Use --limit, --since, or --before to narrow the result set when not watching.
  
  If you're not seeing expected logs, verify your Stack is deployed with 'blueprints info'.

EXAMPLES
    $ sanity blueprints logs

    $ sanity blueprints logs --watch

    $ sanity blueprints logs --stack <name-or-id>

    $ sanity blueprints logs --limit 500

    $ sanity blueprints logs --since 2026-05-01T00:00:00Z

    $ sanity blueprints logs --before 2026-05-01T00:00:00Z

`mint-deploy-token`

USAGE
  $ sanity blueprints mint-deploy-token [--print] [--json] [--label <value>] [--organization-id <value>] [--project-id <value>]

FLAGS
  -P, --print                    Print only the raw token to stdout (suitable for shell substitution)
      --json                     Format output as json
      --label=<value>            Human-readable label for the robot. Defaults to a generated value.
      --organization-id=<value>  Sanity organization ID used to scope Blueprint and Stack
      --project-id=<value>       Sanity project ID used to scope Blueprint and Stack

DESCRIPTION
  Mints a long-lived robot token with the role required to plan, deploy, and destroy Blueprints in this project or organization.
  
  By default the command runs interactively and asks how you want to receive the token (clipboard, print, or exit). Use --print to emit only the raw token for shell pipelines, or --json for full API output.
  
  The minted token is also visible in your Sanity Manage UI under Robots, where it can be revoked.

EXAMPLES
    $ sanity blueprints mint-deploy-token

    $ sanity blueprints mint-deploy-token --label "ci-deploy"

    $ sanity blueprints mint-deploy-token --print

    $ export SANITY_AUTH_TOKEN=$(sanity blueprints mint-deploy-token --print)

    $ sanity blueprints mint-deploy-token --json

    $ sanity blueprints mint-deploy-token --project-id <projectId>

    $ sanity blueprints mint-deploy-token --organization-id <orgId>

`plan`

USAGE
  $ sanity blueprints plan [--json] [--organization-id <value>] [--project-id <value>] [--stack <value>]

FLAGS
      --json                     Format output as json
      --organization-id=<value>  Sanity organization ID used to scope Blueprint and Stack
      --project-id=<value>       Sanity project ID used to scope Blueprint and Stack
      --stack=<value>            Stack name or ID to use instead of the locally configured Stack

DESCRIPTION
  Use this command to preview what changes will be applied to your remote Stack before deploying. This is a safe, read-only operation—no resources are created, modified, or deleted.
  
  Run 'blueprints plan' after making local changes to your Blueprint manifest to verify the expected diff. When ready, run 'blueprints deploy' to apply changes.

EXAMPLES
    $ sanity blueprints plan

    $ sanity blueprints plan --stack <name-or-id>

    $ sanity blueprints plan --organization-id <orgId> --stack <name-or-id>

`promote`

USAGE
  $ sanity blueprints promote [--force] [--json] [--new-stack-name <value>] [--project-id <value>] [--stack <value>]

FLAGS
      --force                   Skip confirmation prompt
      --json                    Format output as json
      --new-stack-name=<value>  Set a new name for the Stack while promoting
      --project-id=<value>      Sanity project ID used to scope Blueprint and Stack
      --stack=<value>           Stack name or ID to promote

DESCRIPTION
  Promotes a deployed Stack to organization scope, enabling management of org-level resources. Promotion cannot be reversed.
  
  Your local Blueprint configuration will be updated to reflect the new scope.

EXAMPLES
    $ sanity blueprints promote

    $ sanity blueprints promote --stack <name-or-id>

    $ sanity blueprints promote --project-id <projectId> --stack <name-or-id>

    $ sanity blueprints promote --new-stack-name <new-name>

`stacks`

USAGE
  $ sanity blueprints stacks [--include-projects] [--json] [--organization-id <value>] [--project-id <value>]

FLAGS
      --include-projects         Include Stacks from all projects within the organization. Requires --organization-id.
      --json                     Format output as json
      --organization-id=<value>  Sanity organization ID used to scope Blueprint and Stack
      --project-id=<value>       Sanity project ID used to scope Blueprint and Stack

DESCRIPTION
  Shows all Stacks associated with a project or organization. By default, lists Stacks scoped to the local Blueprint.
  
  Use this to discover existing Stacks you can scope a local Blueprint to (using 'blueprints config --edit'), or to audit what's deployed across your project.
  
  Use --include-projects with --organization-id to also list Stacks from all projects within the organization.

EXAMPLES
    $ sanity blueprints stacks

    $ sanity blueprints stacks --project-id <projectId>

    $ sanity blueprints stacks --organization-id <organizationId>

    $ sanity blueprints stacks --organization-id <organizationId> --include-projects