@sanity/runtime-cli 17.4.0 → 17.5.0

package/skills/blueprints-config.md

@@ -0,0 +1,33 @@
+# `npx @sanity/cli blueprints config`
+
+Read or update `.sanity/blueprint.config.json`, written next to the Blueprint manifest, which connects the local Blueprint to a Sanity scope and Stack.
+
+## Inspect first
+
+Run from the Blueprint directory and request structured output:
+
+```sh
+npx @sanity/cli blueprints config --json
+```
+
+Without `--edit`, the command only displays the current configuration; with no config file on disk, `--json` emits nothing and exits `0`. Treat the project or organization ID and Stack ID as a single target; changing one can redirect later plan, deploy, info, logs, promote, or destroy commands.
+
+## Update
+
+For agent-driven changes, pass the intended values instead of using the interactive editor:
+
+```sh
+npx @sanity/cli blueprints config --edit --project-id PROJECT_ID --stack NAME_OR_ID --json
+```
+
+Use `--organization-id ORGANIZATION_ID` instead of `--project-id` for an organization scope. The two scope flags are mutually exclusive. `--stack` accepts a Stack name or ID.
+
+Scope or Stack flags without `--edit` write nothing: the command prints `To update the Blueprint config, use the --edit flag.` (suppressed under `--json`) and exits `0`, so a successful exit does not mean the change was applied.
+
+## Switching scope
+
+An update only sets the keys it was given. Adding `--organization-id` to a config that already holds `projectId` leaves both in the file, and project scope takes precedence over organization scope, so the switch has no effect on later commands.
+
+To move a Blueprint from project to organization scope, either edit `.sanity/blueprint.config.json` to remove `projectId`, or use `blueprints promote`, which clears it as part of the scope change.
+
+After an update, run `blueprints config --json` again and verify every ID before executing a mutating command.

package/skills/blueprints-deploy.md

@@ -0,0 +1,36 @@
+# `npx @sanity/cli blueprints deploy`
+
+Apply the local Blueprint to a remote Stack. This command can create, update, and remove remote resources.
+
+## Preflight
+
+1. Locate and inspect the Blueprint manifest.
+2. Resolve the target from local configuration, or pass an explicit scope and `--stack`.
+3. Run `npx @sanity/cli blueprints plan --json`.
+4. Review all planned changes, especially replacements and removals.
+
+Do not deploy when the target or plan is ambiguous.
+
+## Deploy
+
+Include a message that records the reason for the change:
+
+```sh
+npx @sanity/cli blueprints deploy --message "Deploy order processing changes" --json
+```
+
+To target another Stack, pass `--stack NAME_OR_ID`, adding `--project-id PROJECT_ID` or `--organization-id ORGANIZATION_ID` when the scope also differs.
+
+Use `--no-wait` only when the caller does not need a confirmed result. Follow an asynchronous deployment with:
+
+```sh
+npx @sanity/cli blueprints info --json
+```
+
+Exit code `0` means the deployment completed, or was accepted when `--no-wait` is set. Exit code `2` means it failed. Exit code `75` means the request was accepted but completion could not be confirmed; inspect `blueprints info` and `blueprints logs` before retrying.
+
+The command refuses to start while the Stack has a `QUEUED` or `IN_PROGRESS` operation, so a retry during one fails with that message rather than deploying twice. Once the earlier operation settles, a retry does deploy again.
+
+Use `--new-stack-name NAME` only when the deployment should also rename the Stack.
+
+Set `SANITY_ASSET_TIMEOUT` in seconds to raise the 180-second per-asset limit on processing resource assets when large Functions time out during preparation. Set `SANITY_ASSET_CONCURRENCY` to change how many assets are processed at once (default 4).

package/skills/blueprints-destroy.md

@@ -0,0 +1,30 @@
+# `npx @sanity/cli blueprints destroy`
+
+Permanently destroy a remote Stack and its provisioned resources. The local Blueprint manifest and resource files remain, and a matching local Stack ID is cleared from `.sanity/blueprint.config.json`.
+
+## Required safety checks
+
+1. Obtain explicit authorization to destroy the Stack.
+2. Resolve the exact project or organization scope and Stack ID.
+3. Run `npx @sanity/cli blueprints info --json` for that target.
+4. Present the resolved target and affected resources before continuing.
+
+Do not infer authorization from a request to clean up files, redeploy, or fix configuration.
+
+## Run
+
+Interactive use prompts for confirmation:
+
+```sh
+npx @sanity/cli blueprints destroy
+```
+
+For an authorized non-interactive destruction, provide the complete target:
+
+```sh
+npx @sanity/cli blueprints destroy --project-id PROJECT_ID --stack NAME_OR_ID --force --json
+```
+
+Use `--organization-id` instead of `--project-id` for an organization-scoped Stack. The explicit scope flags require both `--stack` and `--force`.
+
+Use `--no-wait` only when asynchronous destruction is intended: it exits `0` as soon as the request is accepted. While waiting, exit code `75` means the request was accepted but completion could not be confirmed. Check `blueprints info` before retrying.

package/skills/blueprints-doctor.md

@@ -0,0 +1,31 @@
+# `npx @sanity/cli blueprints doctor`
+
+Runs five checks: Host online, Authenticated, Manifest valid, Stack ready, User has access. Run this before changing files when another Blueprint command fails for an unclear reason.
+
+## Diagnose
+
+Run from the project directory:
+
+```sh
+npx @sanity/cli blueprints doctor
+```
+
+Use `--path PATH` when the Blueprint manifest is outside the current directory or cannot be discovered automatically. `SANITY_BLUEPRINT_PATH` provides the same path through the environment.
+
+Read the reported diagnostics and warnings before proposing changes. Do not assume every warning requires a fix.
+
+## Read the exit code, not just the JSON
+
+The command exits non-zero unless every check passes; a check that cannot be determined also fails the run. `--json` suppresses the report: a clean run prints `{"diagnostics": {"online": true, "tokenValid": true, ...}}` with `true`, `false`, or `null` per check, and a failing run prints an error object with no diagnostics. Rerun without `--json` to see which checks failed and why.
+
+## Fix
+
+`--fix` prompts for scope and Stack, then writes `.sanity/blueprint.config.json`:
+
+```sh
+npx @sanity/cli blueprints doctor --fix
+```
+
+`--fix` cannot be combined with `--path`, including a path supplied through `SANITY_BLUEPRINT_PATH`. It also requires authentication and a readable Blueprint manifest; without either it reports what is missing and changes nothing.
+
+Use `--fix` only when interactive input is available and the user has authorized configuration changes. Otherwise, apply a specific, reviewed fix and rerun the read-only diagnostic command.

package/skills/blueprints-info.md

@@ -0,0 +1,23 @@
+# `npx @sanity/cli blueprints info`
+
+Read the current state and deployed resources of one remote Stack, including the status of its most recent deploy or destroy operation. Use it to verify a target before mutation.
+
+## Run
+
+Use the locally configured Stack:
+
+```sh
+npx @sanity/cli blueprints info --json
+```
+
+Query a specific target when local configuration is absent or should not be trusted:
+
+```sh
+npx @sanity/cli blueprints info --project-id PROJECT_ID --stack NAME_OR_ID --json
+```
+
+Use `--organization-id` instead of `--project-id` for an organization scope. `--stack` accepts a Stack name or ID. `--verbose` (`-v`) adds each resource's ID and external ID to human-readable output.
+
+The JSON result contains a `stack` object with `id`, `name`, `scopeType`, `scopeId`, `resources`, and `recentOperation`. Check `recentOperation.status` rather than relying on a successful exit alone.
+
+Run this command after `deploy --no-wait`, `destroy --no-wait`, or exit code `75`. Use `blueprints stacks --json` first when the Stack ID is unknown.

package/skills/blueprints-init.md

@@ -0,0 +1,48 @@
+# `npx @sanity/cli blueprints init`
+
+Initialize a local Blueprint and connect it to a new or existing remote Stack. Use this at the start of a Blueprint project or to configure an existing manifest.
+
+## Before running
+
+- Authenticate with Sanity.
+- Choose the target directory and whether the Stack belongs to a project or an organization.
+- Check the target directory and its parents for an existing manifest (`sanity.blueprint` or `blueprint`, with `.json`, `.js`, `.mjs`, or `.ts`). When one is found, the command configures it instead of creating another manifest.
+- Confirm whether to create a Stack or attach an existing one.
+
+## Run
+
+Pass `.` to initialize the current directory without the directory confirmation prompt:
+
+```sh
+npx @sanity/cli blueprints init . --project-id PROJECT_ID --stack-name development
+```
+
+To connect to an existing Stack, provide its ID and scope:
+
+```sh
+npx @sanity/cli blueprints init . --project-id PROJECT_ID --stack-id STACK_ID
+```
+
+Use `--organization-id` instead of `--project-id` for an organization-scoped Stack. `--stack-id` and `--stack-name` are mutually exclusive, and either one requires an explicit project or organization scope.
+
+For a new local Blueprint, choose the manifest format with `--blueprint-type json|js|ts`. JavaScript and TypeScript setups add `@sanity/blueprints` to `devDependencies`, writing a `package.json` with `"type": "module"` if the directory has none. A `js` manifest is written as `sanity.blueprint.mjs` when a `package.json` already exists there without `"type": "module"`. The command also writes `.sanity/blueprint.config.json` and a `.gitignore` covering `node_modules`, `.env`, and function build output; the `.sanity` config itself is not ignored. `--example NAME` takes a different path: it scaffolds a published example into the named directory (or `./NAME` when none is given), creates a project-scoped Stack called `example-NAME`, and cannot be combined with `--blueprint-type`, `--stack-id`, or `--stack-name`.
+
+## Avoid the prompts
+
+A fresh initialization is interactive unless every decision is supplied up front. Pass all four:
+
+```sh
+npx @sanity/cli blueprints init . --project-id PROJECT_ID --stack-name development --blueprint-type ts
+```
+
+Omitting `--blueprint-type` prompts for the manifest format. Omitting both `--stack-id` and `--stack-name` prompts for Stack selection. Omitting the scope starts a full organization and project wizard. Omitting the directory prompts to confirm the current one.
+
+## Verify
+
+Inspect the created files, then preview the first deployment:
+
+```sh
+npx @sanity/cli blueprints plan --json
+```
+
+Do not deploy until the plan targets the expected Stack and contains the expected resource changes.

package/skills/blueprints-logs.md

@@ -0,0 +1,33 @@
+# `npx @sanity/cli blueprints logs`
+
+Retrieve deployment logs for one remote Stack. Prefer bounded, one-shot queries for agent work.
+
+## Query logs
+
+Request structured output with an explicit limit:
+
+```sh
+npx @sanity/cli blueprints logs --limit 100 --json
+```
+
+Narrow a query with ISO 8601 timestamps:
+
+```sh
+npx @sanity/cli blueprints logs --since 2026-07-29T00:00:00Z --limit 100 --json
+```
+
+Use `--before` to page toward older entries. `--limit` must be between 1 and 500; without it the API's default page size applies. When entries are found, the JSON result contains `logs` and `hasMore`; an empty range returns no JSON payload.
+
+Pass `--stack NAME_OR_ID` with `--project-id PROJECT_ID` or `--organization-id ORGANIZATION_ID` when overriding the locally configured target.
+
+## Watch mode
+
+`--watch` (`-w`, alias `--follow`) prints the 10 most recent entries, then polls for new ones until interrupted. It cannot be combined with `--json`, `--limit`, `--since`, or `--before`.
+
+Use watch mode only when continuous monitoring is requested:
+
+```sh
+npx @sanity/cli blueprints logs --watch
+```
+
+If no expected logs appear, run `blueprints info --json` and verify the Stack ID and deployment status.

package/skills/blueprints-mint-deploy-token.md

@@ -0,0 +1,25 @@
+# `npx @sanity/cli blueprints mint-deploy-token`
+
+Create a robot token for deploying Blueprints from CI, scoped to one project or organization. The role granted is `blueprints-deployer` for a project, `blueprints-deployer-robot` for an organization.
+
+## Protect the credential
+
+- Obtain authorization before creating a new robot credential.
+- Confirm the exact scope and use a label that identifies the CI system or deployment purpose.
+- Send the token only to the user-approved secret destination.
+- Never write the token to source files, commit it, paste it into an issue, or include it in a response or log.
+- Revoke unused tokens in Sanity Manage.
+
+## Run
+
+The default command prints the robot label, ID, and expiry, then prompts for clipboard, terminal, or discard handling. For automation, `--print` emits only the raw token:
+
+```sh
+npx @sanity/cli blueprints mint-deploy-token --project-id PROJECT_ID --label "production-ci" --print
+```
+
+Use `--organization-id ORGANIZATION_ID` instead of `--project-id` for organization scope. The two scope flags are mutually exclusive.
+
+`--json` returns the full robot response, including sensitive token material. Do not use it when output is collected in ordinary build logs.
+
+A `ROLE_UNAVAILABLE` error means the role does not exist in that project or organization. Other access or permission errors mean the account needs project or organization administrator access. Do not mint repeated replacement tokens without checking whether the earlier request succeeded.

package/skills/blueprints-plan.md

@@ -0,0 +1,28 @@
+# `npx @sanity/cli blueprints plan`
+
+Preview the resource changes produced by the local Blueprint without creating, modifying, or deleting deployed resources.
+
+## Run
+
+Run after editing the Blueprint and before every deployment:
+
+```sh
+npx @sanity/cli blueprints plan --json
+```
+
+The JSON result contains the resolved local `resources` and the remote deployment `plan`. Review the operations instead of treating a zero exit code as approval to deploy.
+
+To plan against a Stack other than the locally configured one, pass its name or ID, and the scope when that differs too:
+
+```sh
+npx @sanity/cli blueprints plan --project-id PROJECT_ID --stack NAME_OR_ID --json
+```
+
+Use `--organization-id` instead of `--project-id` for organization scope. The scope flags are mutually exclusive.
+
+## Review
+
+- Confirm the Stack ID and scope.
+- Match planned resources to the requested change.
+- Flag unexpected deletions, replacements, or unrelated changes.
+- Stop when the target or impact cannot be determined.

package/skills/blueprints-promote.md

@@ -0,0 +1,31 @@
+# `npx @sanity/cli blueprints promote`
+
+Promote a deployed Stack from project scope to organization scope. Promotion cannot be reversed, and the local Blueprint configuration is updated to the organization scope after success.
+
+## Required safety checks
+
+1. Obtain explicit authorization for the scope change.
+2. Run `npx @sanity/cli blueprints info --json`.
+3. Confirm the exact Stack ID, current project scope, and deployed resources.
+4. Confirm the caller has organization admin access.
+
+The command requires a local Blueprint manifest and an existing `.sanity/blueprint.config.json` to update.
+
+## Run
+
+Interactive use prompts for confirmation:
+
+```sh
+npx @sanity/cli blueprints promote --project-id PROJECT_ID --stack NAME_OR_ID
+```
+
+`--force` skips that prompt. Use `--new-stack-name NAME` to rename during promotion, which is required when the destination organization already holds a Stack with the current name; it is rejected on a Stack that is already organization-scoped.
+
+After success, run:
+
+```sh
+npx @sanity/cli blueprints config --json
+npx @sanity/cli blueprints info --json
+```
+
+If the remote promotion succeeds but the local config update fails, repair the configuration with `blueprints config --edit`; do not promote the Stack again.

package/skills/blueprints-stacks.md

@@ -0,0 +1,28 @@
+# `npx @sanity/cli blueprints stacks`
+
+List remote Stacks for a project or organization. Use this read-only command to discover a Stack ID before running a targeted info, logs, config, deploy, promote, or destroy command.
+
+## Run
+
+List Stacks for the locally configured scope:
+
+```sh
+npx @sanity/cli blueprints stacks --json
+```
+
+Select a scope explicitly when working outside the local Blueprint:
+
+```sh
+npx @sanity/cli blueprints stacks --project-id PROJECT_ID --json
+npx @sanity/cli blueprints stacks --organization-id ORGANIZATION_ID --json
+```
+
+The JSON result contains `stacks`, `scopeType`, and `scopeId`; each entry carries `resourceCount` rather than a full `resources` array. Zero results prints `No stacks found` and emits no JSON. Match both the Stack and its scope; names alone may be ambiguous.
+
+To also include Stacks scoped to the organization's projects:
+
+```sh
+npx @sanity/cli blueprints stacks --organization-id ORGANIZATION_ID --include-projects --json
+```
+
+`--include-projects` requires `--organization-id`, cannot be combined with `--project-id`, and only queries the organization's first 50 projects. This command does not change the local Blueprint target; use `blueprints config --edit` for that.

package/skills/functions-add.md

@@ -0,0 +1,35 @@
+# `npx @sanity/cli functions add`
+
+Scaffold a local Function and its resource definition for the current Blueprint.
+
+## Before running
+
+- Run from a project containing a Blueprint manifest.
+- Choose a Function name not already used by a Blueprint resource, and one event family: document, media-library asset, scheduled, or sync-tag invalidation.
+- Names must be at least three characters, start with a letter or digit, and otherwise contain only letters, digits, hyphens, and underscores.
+- Decide whether to install `@sanity/functions`, which provides typed helpers for authoring handler code, and which package manager to use.
+
+## Add a Function
+
+Provide flags to avoid interactive prompts:
+
+```sh
+npx @sanity/cli functions add --name process-order --type document-create --type document-update --language ts --helpers --installer npm
+```
+
+No flag is required and any omitted value is prompted for, but `--type` without `--name` is rejected. The accepted `--type` values are `document-create`, `document-update`, `document-delete`, `document-publish`, `media-library-asset-create`, `media-library-asset-update`, `media-library-asset-delete`, `scheduled-function`, and `sync-tag-invalidate`. Repeat the flag for multiple events from the same family; the command rejects a mix of families.
+
+TypeScript is the default language. Use `--language js` or `--javascript` for JavaScript, but do not combine those flags. Use `--no-helpers` when helper installation is not wanted. `--installer` accepts `npm`, `pnpm`, `yarn`, or `skip`.
+
+`--example EXAMPLE_NAME` downloads a Function example from the `sanity-labs/function-recipes` repository into `functions/EXAMPLE_NAME/` instead of running the normal scaffold flow. Browse recipes at https://www.sanity.io/exchange/type=recipes/solution=functions. Each recipe's Quick Start contains the correct `--example` value. Pass it alone: every other scaffold flag is rejected, and the manifest is not updated. Use it only for an example the user requested, then follow the configuration instructions printed by the command.
+
+## Verify
+
+The scaffold writes one file, `functions/NAME/index.ts` (or `index.js`). Only `.json` manifests are edited in place; for `.ts`, `.js`, and `.mjs` manifests the command prints a resource definition that still needs to be added by hand.
+
+Run the Function locally with a payload that matches the handler before deployment:
+
+```sh
+npx @sanity/cli functions test process-order --file payload.json --json
+npx @sanity/cli blueprints plan --json
+```

package/skills/functions-dev.md

@@ -0,0 +1,21 @@
+# `npx @sanity/cli functions dev`
+
+Start the local web emulator for interactive Function development. The command keeps running until interrupted.
+
+## Start the emulator
+
+Use the default host and port:
+
+```sh
+npx @sanity/cli functions dev
+```
+
+The emulator is available at `http://localhost:8080`. Choose another loopback port when needed:
+
+```sh
+npx @sanity/cli functions dev --host 127.0.0.1 --port 3333 --timeout 60
+```
+
+Port 8974 is not available: the emulator's WebSocket server binds it. `--timeout` sets the execution limit in seconds for every Function, taking precedence over each Function's configured `timeout` (default 10 seconds). Bind to a non-loopback interface only when network access is requested and exposing the development server is acceptable.
+
+Run this command in a persistent terminal, report the URL, and stop the process when development is complete. For one bounded invocation without a web server, use `functions test`.

package/skills/functions-env-add.md

@@ -0,0 +1,29 @@
+# `npx @sanity/cli functions env add`
+
+Set or replace one environment variable on a deployed Function. The command writes to the Functions API and does not redeploy the Stack.
+
+Run from the Blueprint directory or a subdirectory; the manifest is required even though the command only touches remote state.
+
+## Confirm the target
+
+Resolve the deployed Function name and Stack before changing remote state. Use `functions env list` to inspect existing keys when replacing a value was not explicitly requested.
+
+Set a non-secret value:
+
+```sh
+npx @sanity/cli functions env add process-order API_URL https://api.example.com/
+```
+
+Override the locally configured Stack with `--stack NAME_OR_ID`.
+
+## Protect secret values
+
+The value is a positional command argument and may be visible in shell history, process inspection, or agent tool transcripts. Do not run the command with a secret until the user has approved both the target and the handling method.
+
+Do not use `--json` or `--trace` for secrets: the JSON result contains the value, and trace output prints the request body. Never paste a secret value into source files, logs, issue comments, or an assistant response.
+
+After setting the variable, verify only its key:
+
+```sh
+npx @sanity/cli functions env list process-order --json
+```

package/skills/functions-env-list.md

@@ -0,0 +1,21 @@
+# `npx @sanity/cli functions env list`
+
+List the environment-variable keys configured on one deployed Function. Values are not returned.
+
+Run from the Blueprint directory or a subdirectory; the manifest is required even though the command only touches remote state.
+
+## Run
+
+Use the locally configured Stack:
+
+```sh
+npx @sanity/cli functions env list process-order --json
+```
+
+Query another Stack:
+
+```sh
+npx @sanity/cli functions env list process-order --stack NAME_OR_ID --json
+```
+
+The JSON result contains the Function `name` and an `envvars` array of keys. Match the Function name and Stack before using the result to add, replace, or remove a variable.

package/skills/functions-env-remove.md

@@ -0,0 +1,22 @@
+# `npx @sanity/cli functions env remove`
+
+Delete one environment variable from a deployed Function. The command does not ask for confirmation and does not redeploy the Stack.
+
+Run from the Blueprint directory or a subdirectory; the manifest is required even though the command only touches remote state.
+
+## Required checks
+
+1. Obtain authorization to remove the key.
+2. Resolve the exact Function and Stack.
+3. Run `functions env list` and confirm that the key is present.
+4. Check whether the Function still requires the variable.
+
+## Remove
+
+```sh
+npx @sanity/cli functions env remove process-order LEGACY_API_URL --json
+```
+
+Override the locally configured Stack with `--stack NAME_OR_ID`.
+
+The JSON result contains the Function name and removed key, not the old value. If the value may be needed again, arrange a user-approved backup before removal; this command cannot retrieve it.

package/skills/functions-logs.md

@@ -0,0 +1,39 @@
+# `npx @sanity/cli functions logs`
+
+Fetch, stream, or delete logs for one deployed Function. Always provide the Function name; omitting it only prints valid names and command help.
+
+Run from the Blueprint directory or a subdirectory; the manifest supplies the valid Function names.
+
+## Fetch logs
+
+Prefer a bounded, structured query for agent work:
+
+```sh
+npx @sanity/cli functions logs process-order --limit 100 --json
+```
+
+`--limit` defaults to 50. Entries without both a level and a message are dropped, so a returned count can be lower than the limit even when more logs exist.
+
+When entries are found, the JSON result contains a `logs` array of `{time, requestId, level, message}`. Human-readable output drops `requestId` and prints local timestamps unless `--utc` is passed. Pass `--stack NAME_OR_ID` to override the locally configured Stack.
+
+Logs may contain payload data or application secrets. Summarize only what is needed and do not reproduce credentials or personal data.
+
+## Stream logs
+
+`--watch` (alias `--follow`, `-w`) keeps running until interrupted and emits human-readable output:
+
+```sh
+npx @sanity/cli functions logs process-order --watch
+```
+
+`--watch` cannot be combined with `--json`. Streamed timestamps are always UTC, so `--utc` is ignored. Use watch mode only when continuous monitoring is requested, and stop it when monitoring is complete.
+
+## Delete logs
+
+Deleting removes all logs for the Function. Obtain explicit authorization and confirm the Function and Stack first:
+
+```sh
+npx @sanity/cli functions logs process-order --delete
+```
+
+The command prompts (defaulting to no) unless `--force` is supplied, and `--force` requires `--delete`. Use `--force` only for an authorized non-interactive deletion. `--delete` is rejected alongside `--limit` or `--json`.

package/skills/functions-test.md

@@ -0,0 +1,31 @@
+# `npx @sanity/cli functions test`
+
+Invoke a local Function with a test payload. Local execution can still make network requests or mutate external systems, so inspect the handler and payload before running it.
+
+## Run a bounded test
+
+Always provide the Function name. Prefer a JSON file for nontrivial payloads:
+
+```sh
+npx @sanity/cli functions test process-order --file payload.json --json
+```
+
+Use `--data '{"orderId":"order-123"}'` for a small inline JSON object. `--data`, `--file`, and `--document-id` are alternative input modes, and each must resolve to a JSON object. File paths are joined to the current working directory, so pass relative paths.
+
+Payloads reach document and media-library Functions only. Scheduled and sync-tag-invalidation Functions are invoked with a fixed scheduled event, and any payload flag is accepted and then ignored.
+
+For document and media-library Functions, the event defaults to `create` and also accepts `update` and `delete`. For an update event, provide one complete before/after pair:
+
+```sh
+npx @sanity/cli functions test process-order --event update --file-before before.json --file-after after.json --json
+```
+
+The Blueprint's `event.filter` and `event.projection` are applied to the payload before the handler runs, and a payload the filter excludes is skipped rather than executed. `--timeout SECONDS` overrides the Function's configured `timeout` for this run (default 10 seconds).
+
+## Remote data and credentials
+
+`--document-id` fetches a document (`--project-id`, `--dataset`) or a media-library asset (`--media-library-id`) with the CLI's stored token before local execution. `--api` sets the API version used for that fetch.
+
+`--with-user-token` injects the authenticated CLI token into the Function context. Use it only for trusted local code when authenticated API behavior is part of the test. Never include the token in payloads or output.
+
+The JSON result contains logs and any Function response. Review logs for sensitive data before sharing them.