@sanity/runtime-cli

Sanity's Runtime CLI for Blueprints and Functions

• Usage
• Commands

Usage

$ npm install -g @sanity/runtime-cli
$ sanity-run COMMAND
running command...
$ sanity-run (--version)
@sanity/runtime-cli/13.0.3 linux-x64 node-v24.12.0
$ sanity-run --help [COMMAND]
USAGE
  $ sanity-run COMMAND
...

Commands

• sanity-run blueprints add TYPE
• sanity-run blueprints config
• sanity-run blueprints deploy
• sanity-run blueprints destroy
• sanity-run blueprints doctor
• sanity-run blueprints info
• sanity-run blueprints init [DIR]
• sanity-run blueprints logs
• sanity-run blueprints plan
• sanity-run blueprints stacks
• sanity-run functions add
• sanity-run functions dev
• sanity-run functions env add NAME KEY VALUE
• sanity-run functions env list NAME
• sanity-run functions env remove NAME KEY
• sanity-run functions logs [NAME]
• sanity-run functions test [NAME]
• sanity-run help [COMMAND]

sanity-run blueprints add TYPE

Add a function resource to a Blueprint

USAGE
  $ sanity-run blueprints add TYPE [--example <value> | -n <value> | --fn-type
    document-create|document-delete|document-update|document-publish|media-library-asset-create|media-library-asset-upda
    te|media-library-asset-delete... | --language ts|js | --javascript | --fn-helpers | --fn-installer
    skip|npm|pnpm|yarn] [-i | ]

ARGUMENTS
  TYPE  (function) 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
      --[no-]fn-helpers        Add helpers to the new function
      --fn-installer=<option>  Which package manager to use when installing the @sanity/functions helpers
                               <options: skip|npm|pnpm|yarn>
      --fn-type=<option>...    Document change event(s) that should trigger the function; you can specify multiple
                               events by specifying this flag multiple times
                               <options: document-create|document-delete|document-update|document-publish|media-library-
                               asset-create|media-library-asset-update|media-library-asset-delete>
      --javascript             Use JavaScript instead of TypeScript
      --language=<option>      [default: ts] Language of the new function
                               <options: ts|js>

DESCRIPTION
  Add a function resource to a Blueprint

  Scaffolds a new Sanity Function in your Blueprint. Functions are serverless handlers triggered by document events
  (create, update, delete, publish) or media library events.

  After adding a function, use 'functions dev' to test locally, then 'blueprints deploy' to publish it.

EXAMPLES
  $ sanity-run blueprints add function

  $ sanity-run blueprints add function --helpers

  $ sanity-run blueprints add function --name my-function

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

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

See code: src/commands/blueprints/add.ts

sanity-run blueprints config

View or edit the local Blueprint configuration

USAGE
  $ sanity-run blueprints config [--project-id <value> -e] [--stack-id <value> ]

FLAGS
  -e, --edit                Modify the configuration interactively, or directly when combined with ID flags.
      --project-id=<value>  Directly set the project ID in the configuration. Requires --edit flag
      --stack-id=<value>    Directly set the Stack ID in the configuration. Requires --edit flag

DESCRIPTION
  View or edit the local Blueprint configuration

  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-id.

EXAMPLES
  $ sanity-run blueprints config

  $ sanity-run blueprints config --edit

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

  $ sanity-run blueprints config --edit --project-id <projectId> --stack-id <stackId>

See code: src/commands/blueprints/config.ts

sanity-run blueprints deploy

Deploy the local Blueprint to the remote Stack

USAGE
  $ sanity-run blueprints deploy [--no-wait]

FLAGS
  --no-wait  Do not wait for Stack deployment to complete

DESCRIPTION
  Deploy the local Blueprint to the remote Stack

  Pushes your local Blueprint configuration to the remote Stack; provisioning, updating, or destroying 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.

EXAMPLES
  $ sanity-run blueprints deploy

  $ sanity-run blueprints deploy --no-wait

See code: src/commands/blueprints/deploy.ts

sanity-run blueprints destroy

Destroy the remote Stack deployment and its resources (will not delete local files)

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

FLAGS
  --force               Force Stack destruction (skip confirmation)
  --no-wait             Do not wait for Stack destruction to complete
  --project-id=<value>  Project associated with the Stack
  --stack-id=<value>    Stack ID to destroy (defaults to current Stack)

DESCRIPTION
  Destroy the remote Stack deployment and its resources (will not delete local files)

  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-run blueprints destroy

  $ sanity-run blueprints destroy --stack-id <stackId> --project-id <projectId> --force --no-wait

See code: src/commands/blueprints/destroy.ts

sanity-run blueprints doctor

Diagnose potential issues with local Blueprint and remote Stack configuration

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

FLAGS
  --fix           Interactively fix configuration issues
  --json          Format output as json.
  --path=<value>  Path to the directory containing the Blueprint
  --verbose       Verbose output

DESCRIPTION
  Diagnose potential issues with local Blueprint and remote Stack configuration

  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.

See code: src/commands/blueprints/doctor.ts

sanity-run blueprints info

Show information about the local Blueprint's remote Stack deployment

USAGE
  $ sanity-run blueprints info [--id <value>]

FLAGS
  --id=<value>  Stack ID to show info for (defaults to the current Stack)

DESCRIPTION
  Show information about the local Blueprint's remote Stack deployment

  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-run blueprints info

  $ sanity-run blueprints info --id <stackId>

See code: src/commands/blueprints/info.ts

sanity-run blueprints init [DIR]

Initialize a local Blueprint and optionally provision a remote Stack deployment

USAGE
  $ sanity-run blueprints init [DIR] [--verbose] [--dir <value>] [--example <value> | --blueprint-type json|js|ts |
    --stack-id <value> | --stack-name <value>] [--project-id <value>]

ARGUMENTS
  [DIR]  Directory to create the local Blueprint in

FLAGS
  --blueprint-type=<option>  Blueprint manifest type to use for the local Blueprint
                             <options: json|js|ts>
  --dir=<value>              Directory to create the local Blueprint in
  --example=<value>          Example to use for the local Blueprint
  --project-id=<value>       Sanity project ID used to scope local Blueprint and remote 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
  --verbose                  Verbose output

DESCRIPTION
  Initialize a local Blueprint and optionally provision a remote Stack deployment

  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-run blueprints init

  $ sanity-run blueprints init [directory]

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

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

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

See code: src/commands/blueprints/init.ts

sanity-run blueprints logs

Display logs for the current Blueprint's Stack deployment

USAGE
  $ sanity-run blueprints logs [-w]

FLAGS
  -w, --watch  Watch for new Stack logs (streaming mode)

DESCRIPTION
  Display logs for the current Blueprint's Stack deployment

  Retrieves Stack deployment logs, useful for debugging and monitoring deployment activity.

  Use --watch (-w) to stream logs in real-time.

  If you're not seeing expected logs, verify your Stack is deployed with 'blueprints info'.

EXAMPLES
  $ sanity-run blueprints logs

  $ sanity-run blueprints logs --watch

See code: src/commands/blueprints/logs.ts

sanity-run blueprints plan

Enumerate resources to be deployed to the remote Stack - will not modify any resources

USAGE
  $ sanity-run blueprints plan

DESCRIPTION
  Enumerate resources to be deployed to the remote Stack - will not modify any resources

  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-run blueprints plan

See code: src/commands/blueprints/plan.ts

sanity-run blueprints stacks

List all remote Stack deployments (defaults to the current Blueprint's project scope)

USAGE
  $ sanity-run blueprints stacks [--project-id <value> | ]

FLAGS
  --project-id=<value>  Project ID to show Stack deployments for

DESCRIPTION
  List all remote Stack deployments (defaults to the current Blueprint's project scope)

  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.

EXAMPLES
  $ sanity-run blueprints stacks

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

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

See code: src/commands/blueprints/stacks.ts

sanity-run functions add

Add a Function to your Blueprint

USAGE
  $ sanity-run functions add [--example <value> | -n <value> |  | --language ts|js | --javascript |  | ] [--type
    document-create|document-delete|document-update|document-publish|media-library-asset-create|media-library-asset-upda
    te|media-library-asset-delete... ] [--helpers] [--installer skip|npm|pnpm|yarn] [-i | ]

FLAGS
  -i, --install             Shortcut for --fn-installer npm
  -n, --name=<value>        Name of the Function to add
      --example=<value>     Example to use for the Function
      --[no-]helpers        Add helpers to the new Function
      --installer=<option>  How to install the @sanity/functions helpers
                            <options: skip|npm|pnpm|yarn>
      --javascript          Use JavaScript instead of TypeScript
      --language=<option>   [default: ts] Language of the new Function
                            <options: ts|js>
      --type=<option>...    Document change event(s) that should trigger the function; you can specify multiple events
                            by specifying this flag multiple times
                            <options: document-create|document-delete|document-update|document-publish|media-library-ass
                            et-create|media-library-asset-update|media-library-asset-delete>

DESCRIPTION
  Add a Function to your Blueprint

  Scaffolds a new Function in the functions/ folder and templates a resource for your Blueprint manifest.

  Functions are serverless handlers triggered by document events (create, update, delete, publish) or media library
  events.

  After adding, use 'functions dev' to test locally, then 'blueprints deploy' to publish.

EXAMPLES
  $ sanity-run functions add

  $ sanity-run functions add --helpers

  $ sanity-run functions add --name my-function

  $ sanity-run functions add --name my-function --type document-create

  $ sanity-run functions add --name my-function --type document-create --type document-update --lang js

See code: src/commands/functions/add.ts

sanity-run functions dev

Start the Sanity Function emulator

USAGE
  $ sanity-run functions dev [-h <value>] [-p <value>] [-t <value>]

FLAGS
  -h, --host=<value>     The local network interface at which to listen. [default: "localhost"]
  -p, --port=<value>     TCP port to start emulator on. [default: 8080]
  -t, --timeout=<value>  Maximum execution time for all functions, in seconds. Takes precedence over function-specific
                         `timeout`

DESCRIPTION
  Start the Sanity Function emulator

  Runs a local, web-based development server to test your functions before deploying.

  Open the emulator in your browser to interactively test your functions with the payload editor.

  Optionally, set the host and port with the --host and --port flags. Function timeout can be configured with the
  --timeout flag.

  To invoke a function with the CLI, use 'functions test'.

EXAMPLES
  $ sanity-run functions dev --host 127.0.0.1 --port 8974

  $ sanity-run functions dev --timeout 60

See code: src/commands/functions/dev.ts

sanity-run functions env add NAME KEY VALUE

Add or set an environment variable for a deployed function

USAGE
  $ sanity-run functions env add NAME KEY VALUE

ARGUMENTS
  NAME   The name of the Sanity Function
  KEY    The name of the environment variable
  VALUE  The value of the environment variable

DESCRIPTION
  Add or set an environment variable for a deployed function

  Sets an environment variable in a deployed Sanity Function. If the variable already exists, its value is updated.

  Environment variables are useful for API keys, configuration values, and other secrets that shouldn't be hardcoded.
  Changes take effect on the next function invocation.

EXAMPLES
  $ sanity-run functions env add MyFunction API_URL https://api.example.com/

See code: src/commands/functions/env/add.ts

sanity-run functions env list NAME

List environment variables for a deployed function

USAGE
  $ sanity-run functions env list NAME

ARGUMENTS
  NAME  The name of the Sanity Function

DESCRIPTION
  List environment variables for a deployed function

  Displays all environment variables (keys only) configured in a deployed Sanity Function.

  Use 'functions env add' to set variables or 'functions env remove' to delete them.

EXAMPLES
  $ sanity-run functions env list MyFunction

See code: src/commands/functions/env/list.ts

sanity-run functions env remove NAME KEY

Remove an environment variable from a deployed function

USAGE
  $ sanity-run functions env remove NAME KEY

ARGUMENTS
  NAME  The name of the Sanity Function
  KEY   The name of the environment variable

DESCRIPTION
  Remove an environment variable from a deployed function

  Deletes an environment variable from a deployed Sanity Function. The change takes effect on the next function
  invocation.

  Use 'functions env list' to see current variables before removing.

EXAMPLES
  $ sanity-run functions env remove MyFunction API_URL

See code: src/commands/functions/env/remove.ts

sanity-run functions logs [NAME]

Retrieve or delete logs for a Sanity Function

USAGE
  $ sanity-run functions logs [NAME] [-u] [-f [-d | -l <value> | -j]] [-w]

ARGUMENTS
  [NAME]  The name of the Sanity Function

FLAGS
  -d, --delete         Delete all logs for the function
  -f, --force          Skip confirmation for deleting logs
  -j, --json           Return logs in JSON format
  -l, --limit=<value>  [default: 50] Total number of log entries to retrieve
  -u, --utc            Show dates in UTC time zone
  -w, --watch          Watch for new logs (streaming mode)

DESCRIPTION
  Retrieve or delete logs for a Sanity Function

  Fetches execution logs from a deployed function, useful for debugging production issues or monitoring activity.

  Use --watch (-w) to stream logs in real-time. Use --delete to clear all logs for a function (requires confirmation
  unless --force is specified).

EXAMPLES
  $ sanity-run functions logs <name>

  $ sanity-run functions logs <name> --json

  $ sanity-run functions logs <name> --limit 100

  $ sanity-run functions logs <name> --delete

See code: src/commands/functions/logs.ts

sanity-run functions test [NAME]

Invoke a local Sanity Function

USAGE
  $ sanity-run functions test [NAME] [--data-before <value> | [-d <value> | -f <value> | --document-id <value>] |  |
    | --file-before <value> | --file-after <value> | --document-id-before <value> | --document-id-after <value>]
    [--data-after <value> |  |  |  |  |  |  | ] [-e create|update|delete] [-t <value>] [-a <value>] [--with-user-token]
    [--media-library-id <value> | --project-id <value> | --dataset <value>]

ARGUMENTS
  [NAME]  The name of the Sanity Function

FLAGS
  -a, --api=<value>                 Sanity API Version to use
  -d, --data=<value>                Data to send to the function
  -e, --event=<option>              Type of event (create, update, delete)
                                    <options: create|update|delete>
  -f, --file=<value>                Read data from file and send to the function
  -t, --timeout=<value>             Execution timeout value in seconds
      --data-after=<value>          Current document
      --data-before=<value>         Original document
      --dataset=<value>             The Sanity dataset to use
      --document-id=<value>         Document to fetch and send to function
      --document-id-after=<value>   Current document
      --document-id-before=<value>  Original document
      --file-after=<value>          Current document
      --file-before=<value>         Original document
      --media-library-id=<value>    Sanity Media Library ID to use
      --project-id=<value>          Sanity Project ID to use
      --with-user-token             Prime access token from CLI config

DESCRIPTION
  Invoke a local Sanity Function

  Executes a function locally with the provided payload, simulating how it would run when deployed. Use this to test
  your function logic before deploying.

  Provide test data via --data (inline JSON), --file (JSON file), or --document-id (fetch from Sanity). For update
  events, use the before/after flag pairs to simulate document changes.

EXAMPLES
  $ sanity-run functions test <name> --data '{ "id": 1 }'

  $ sanity-run functions test <name> --file 'payload.json'

  $ sanity-run functions test <name> --data '{ "id": 1 }' --timeout 60

  $ sanity-run functions test <name> --event update --data-before '{ "title": "before" }' --data-after '{ "title": "after" }'

See code: src/commands/functions/test.ts

sanity-run help [COMMAND]

Display help for sanity-run.

USAGE
  $ sanity-run help [COMMAND...] [-n]

ARGUMENTS
  [COMMAND...]  Command to show help for.

FLAGS
  -n, --nested-commands  Include all nested commands in the output.

DESCRIPTION
  Display help for sanity-run.

See code: @oclif/plugin-help