Blueprints CLI command reference

npx sanity blueprints --help

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

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>

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 180-second timeout for processing resource assets.
  
  Set SANITY_ASSET_CONCURRENCY to override how many resource assets are processed at once (default 4).
  
  Exit codes: 0 deployed, 2 deployment failed, 75 deployment accepted but completion could not be confirmed (rerun 'blueprints info' to check).

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>

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

FLAGS
  -f, --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 Blueprint manifest and resource files remain intact; "stackId" is unset in your local config.
  
  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.
  
  Exit codes: 0 destroyed, 2 destruction failed, 75 destruction accepted but completion could not be confirmed (rerun 'blueprints info' to check).

EXAMPLES
    $ sanity blueprints destroy

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

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

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

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.
  
  Supports --json for programmatic consumption of diagnostic results.

EXAMPLES
    $ sanity blueprints doctor

    $ sanity blueprints doctor --fix

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

FLAGS
  -v, --verbose                  Show resource and external IDs
      --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>

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 (defaults to the current directory)

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.
  
  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. A .gitignore covering node_modules, .env, and Function build output is created or updated; the .sanity/ config itself is not ignored.
  
  After initialization, use 'blueprints plan' to preview changes, then 'blueprints deploy' to apply them.
  
  Running without a directory prompts to confirm the current directory. Run 'blueprints init .' to initialize in the current directory without a prompt.

EXAMPLES
    $ sanity blueprints init

    $ sanity blueprints init .

    $ sanity blueprints init [directory]

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

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

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

    $ sanity blueprints init --stack-name <newStackName>

    $ sanity blueprints init --stack-id <existingStackId>

    $ sanity blueprints init new-stack --type <json|js|ts> --org <organizationId> --name <newStackName>

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

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

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>

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>

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>

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

FLAGS
      --all                      List Stacks from every organization and project you have access to
      --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.
  
  Without a scope, prompts for an organization or project. Use --all to list Stacks across every organization and project you can access, or --include-projects with --organization-id for one organization and its projects.

EXAMPLES
    $ sanity blueprints stacks

    $ sanity blueprints stacks --all

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

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

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