> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sqlbuild.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scope Explorer

> Inspect visibility, explain resolution, browse declarations, and preview moves offline.

Scope Explorer exposes the compiler's declaration index through `sqb scope`. It is read-only and
offline: it never connects to the warehouse, moves files, or edits configuration.

Use this page for common workflows. See the [`sqb scope` CLI reference](/cli/scope) for every flag,
filter, text section, and JSON field.

## Inspect a resource

Start with a model, test, scenario, hook, function, audit, source, or declaration identity:

```bash theme={null}
sqb scope model:stg_orders
sqb scope test:orders__completed_only
sqb scope macro:normalize_order_status
```

The report separates concepts that are easy to conflate:

| Section            | What it answers                                             |
| ------------------ | ----------------------------------------------------------- |
| Scope chain        | Which exact-local, inherited, and global tiers apply?       |
| Available          | What can this resource resolve through its lexical path?    |
| Used declarations  | What did compilation actually consume?                      |
| Relationship scope | Which expected models granted constants or enums?           |
| Nearby unavailable | Which close declarations are outside scope? This is opt-in. |
| Placement          | Is each narrow declaration at its closest valid location?   |

## Explain one declaration

Ask why a declaration is visible, inaccessible, used, or granted:

```bash theme={null}
sqb scope model:stg_orders --explain enum:customer_status
sqb scope test:orders__completed_only --explain constant:order_status
```

Explanation output retains the resolution route. Expected-model grants remain distinct from path
visibility, and macro dependency routes retain the consuming macro.

## Browse nearby declarations

Use nearby output when you know the resource but not the declaration name:

```bash theme={null}
sqb scope model:stg_orders --include-nearby
sqb scope model:stg_orders --include-nearby --nearby-depth 2
```

Browse the scope index like a deterministic tree when exploring a larger project:

```bash theme={null}
sqb scope model:stg_orders --browse .
sqb scope model:stg_orders --browse global
sqb scope model:stg_orders --list global/macros/finance/payments
```

Filters for declaration kind, definition path, glob matching, and actual usage can be combined. Use
pagination for large reports rather than trimming the compiler facts.

## Check a prospective path

Inspect what a resource would see before its file exists:

```bash theme={null}
sqb scope --at models/commerce/finance/new_revenue.sql
sqb scope --at tests/unit/commerce/orders/
```

Use `--as-path` to evaluate an existing resource from a proposed destination without moving it:

```bash theme={null}
sqb scope model:stg_orders --as-path models/commerce/staging/stg_orders.sql
```

## Preview a resource move

Use `--as-path` to preview moving an existing authored resource such as a model, test, hook, or
function. The report shows retained, gained, and lost declarations and direct usages the move would
invalidate:

```bash theme={null}
sqb scope model:stg_orders \
  --as-path models/marts/orders/stg_orders.sql
```

The destination must be valid for that resource kind. Scope Explorer does not move the file or
preview moving declaration files themselves.

## Automation

Use `--json` for editor integrations and repository tooling. Scope JSON has a versioned schema,
stable ordering, value-free declaration metadata, completeness facts, filters, pagination, and move
preview results. Secret connection settings and declaration values are not included.

<CardGroup cols={2}>
  <Card title="Visibility and Resolution" icon="eye" href="/concepts/declaration-scopes/visibility">
    Review the compiler rules behind the report.
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli/scope">
    See all selectors, filters, pagination options, output sections, and JSON behavior.
  </Card>
</CardGroup>