> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/references/v1/resources/vulcan/concepts/run-and-plan.md).

# Run and plan

`vulcan plan` and `vulcan run` are the two commands that move a project from local files to fresh, deployed data. They answer different questions, and confusing them is the most common mistake in daily Vulcan use.

```
Changed the project shape? Use plan.
Refreshing data on an applied shape? Use run.
```

## Plan: apply project changes

Use `vulcan plan` when you changed models, semantics, metadata, tests, checks, or configuration. Vulcan compares your local project with applied state, shows impact, and prepares the next safe version of the data product.

```bash
vulcan plan
```

`vulcan plan` does not just run data. It reviews what changed, classifies the impact, and decides what must be built before the next version is exposed:

1. Loads your project files and configuration.
2. Builds the dependency graph.
3. Compares local state with applied state.
4. Detects added, removed, direct, indirect, and metadata-only changes.
5. Computes intervals that need backfill or restatement.
6. Shows the plan before anything is applied.

Vulcan supports two planning modes, depending on whether your project uses a virtual layer:

* [**Plan without a virtual layer**](/references/v1/resources/vulcan/concepts/run-and-plan/plan-guide.md) - models are written directly with their original names.
* [**Plan with a virtual layer**](/references/v1/resources/vulcan/concepts/run-and-plan/plan-with-vde.md) - consumer-facing names stay stable while Vulcan manages versioned physical snapshots behind them.

## Run: refresh applied data

Use `vulcan run` when the shape is already applied and you only need to process new or missing data. It does not redesign the data product and does not pick up new local code changes; it only works with the version that has already been applied.

```bash
vulcan run
```

See [**Run and scheduling**](/references/v1/resources/vulcan/concepts/run-and-plan/run-and-scheduling.md) for how `vulcan run` finds missing intervals, respects schedules and signals, and runs scheduled refreshes in production.

## Choosing the right command

| Question                                                 | Use `vulcan plan` | Use `vulcan run` |
| -------------------------------------------------------- | ----------------- | ---------------- |
| Did the model SQL or Python change?                      | Yes               | No               |
| Did a metric, semantic model, check, or metadata change? | Yes               | No               |
| Do you need Vulcan to review what changed?               | Yes               | No               |
| Do you only need to process new data?                    | No                | Yes              |
| Do you want scheduled refreshes?                         | No                | Yes              |

Use `vulcan plan` first when the project changed. Then use `vulcan run` after the new shape is applied and you want ongoing scheduled execution.

For the broader workflow, see [Data product lifecycle](/references/v1/resources/vulcan/concepts/data-product-lifecycle.md).

## Choose a page

* [**Plan without a virtual layer**](/references/v1/resources/vulcan/concepts/run-and-plan/plan-guide.md)
* [**Plan with a virtual layer**](/references/v1/resources/vulcan/concepts/run-and-plan/plan-with-vde.md)
* [**Run and scheduling**](/references/v1/resources/vulcan/concepts/run-and-plan/run-and-scheduling.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/references/v1/resources/vulcan/concepts/run-and-plan.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.