> For AI agents: the complete Sanity documentation index is available at [https://www.sanity.io/docs/llms.txt](https://www.sanity.io/docs/llms.txt).

# Blueprints scopes reference

Project versus organization scope, which resource types need which scope, and how the CLI resolves scope.

## The two scopes

##### The two scopes

| Scope | Boundary | Stored as |
| --- | --- | --- |
| Project | One Sanity project. Resources default to that project. | projectId in the config file |
| Organization | An organization. Project-scoped resources must name their project. Unlocks org-scoped resource types. | organizationId in the config file |

The blueprint file doesn't encode scope. Scope lives in `.sanity/blueprint.config.json` and is derived from which ID it holds.

## What needs which scope

Most resource types are project-scoped: they belong to a single project, and on an organization-scoped stack you give each one a `project`. A few require organization scope, such as scheduled (cron) functions. Roles are unscoped.

Deploying an organization-scoped type to a project-scoped stack fails; promote the stack first (see [Promote a stack to organization scope](https://www.sanity.io/docs/blueprints/promote-stack-to-organization-scope)). For the current scope of each resource type, see the [typed API reference](https://reference.sanity.io/_sanity/blueprints/).

## How the CLI resolves scope

For each of `organizationId`, `projectId`, and `stackId`, the CLI takes the first source that resolves, in this order:

1. Command-line flags (`--organization-id`, `--project-id`, `--stack`)
2. Environment variables (`SANITY_ORGANIZATION_ID`, `SANITY_PROJECT_ID`, `SANITY_BLUEPRINT_STACK_ID`)
3. IDs exported from the blueprint file module
4. The local config file, `.sanity/blueprint.config.json`

Scope is derived as specifically as possible: if a project ID resolves, the scope is project; otherwise, if an organization ID resolves, the scope is organization.

## After promotion

When you [promote](https://www.sanity.io/docs/blueprints/promote-stack-to-organization-scope) a stack to organization scope, it remembers its original project. Project-scoped resources that don't set a `project` fall back to that project automatically, so your existing resources keep working. Set an explicit `project` on a resource to target a different one.

#### Related

[Stacks and scope](https://www.sanity.io/docs/blueprints/stacks-and-scope)
How one blueprint file maps to many stacks, and what project versus organization scope means.

[Promote a stack to organization scope](https://www.sanity.io/docs/blueprints/promote-stack-to-organization-scope)
Learn how to promote an existing project-scoped blueprint stack to organization scope to unlock scheduled functions.

[Blueprint configuration reference](https://www.sanity.io/docs/blueprints/blueprint-config)
Reference documentation for the Blueprint configuration files.