> 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/resources/vulcan/cli.md).

# CLI commands

Every Vulcan CLI command, its options, and example output: planning and running models, auditing data quality, diffing environments, and managing state.

The Vulcan CLI is your primary interface for your data pipeline. Use it to plan changes, run models, check data quality, and manage your project.

```
Usage: vulcan [OPTIONS] COMMAND [ARGS]...

  Vulcan command line tool.

Options:
  --version            Show the version and exit.
  -p, --paths TEXT     Path(s) to the Vulcan config/project.
  --config TEXT        Name of the config object. Only applicable to
                       configuration defined using Python script.
  --gateway TEXT       The name of the gateway.
  --ignore-warnings    Ignore warnings.
  --debug              Enable debug mode.
  --log-to-stdout      Display logs in stdout.
  --log-file-dir TEXT  The directory to write log files to.
  --dotenv PATH        Path to a custom .env file to load environment
                       variables.
  --help               Show this message and exit.

Commands:
  audit                   Run audits for the target model(s).
  check_intervals         Show missing intervals in an environment,...
  clean                   Clears the Vulcan cache and any build artifacts.
  create_deploy_yaml      Generate a DataOS Vulcan resource deploy YAML...
  create_external_models  Create a schema file containing external model...
  create_test             Generate a unit test fixture for a given model.
  destroy                 The destroy command removes all project resources.
  diff                    Show the diff between the local state and the...
  environments            Prints the list of Vulcan environments with its...
  evaluate                Evaluate a model and return a dataframe with a...
  export                  Commands for exporting the DAG, joins, metadata,...
  fetchdf                 Run a SQL query and display the results.
  format                  Format all SQL models and audits.
  import_semantic_view    Import a Snowflake Semantic View into the current...
  info                    Print information about a Vulcan project.
  init                    Create a new Vulcan repository.
  invalidate              Invalidate the target environment, forcing its...
  lint                    Run the linter for the target model(s).
  migrate                 Migrate Vulcan to the current running version.
  plan                    Apply local changes to the target environment.
  render                  Render a model's query, optionally expanding...
  review                  Run an AI-assisted review of model changes.
  rewrite                 Rewrite a semantic SQL query against an...
  rollback                Rollback Vulcan to the previous migration.
  run                     Evaluate missing intervals for the target...
  table_diff              Show the diff between two tables or a selection...
  table_name              Prints the name of the physical table for the...
  test                    Run model unit tests.
  transpile               Transpile a semantic SQL query or REST payload.
```

## audit

Run data quality audits for your models. This command executes the audits attached to your models as assertions and reports pass/fail. Use it to validate data quality before deploying changes.

```
Usage: vulcan audit [OPTIONS]

  Run audits for the target model(s).

Options:
  --model TEXT           A model to audit. Multiple models can be audited.
  -s, --start TEXT       The start datetime of the interval for which this
                         command will be applied.
  -e, --end TEXT         The end datetime of the interval for which this
                         command will be applied.
  --execution-time TEXT  The execution time (defaults to now).
  --help                 Show this message and exit.
```

<details>

<summary>Example</summary>

```
$ vulcan audit
  Found 11 audit(s).
  unique_values on model sales.daily_sales ✅ PASS.
  not_null on model sales.daily_sales ✅ PASS.
  positive_values on model sales.daily_sales ✅ PASS.
  positive_values on model sales.daily_sales ✅ PASS.
  unique_values on model raw.raw_products ✅ PASS.
  not_null on model raw.raw_products ✅ PASS.
  unique_values on model raw.raw_customers ✅ PASS.
  not_null on model raw.raw_customers ✅ PASS.
  unique_values on model raw.raw_orders ✅ PASS.
  not_null on model raw.raw_orders ✅ PASS.
  positive_values on model raw.raw_orders ✅ PASS.

  Finished with 0 audit errors and 0 audits skipped.
  Done.
```

</details>

## check\_intervals

Check which time intervals are missing for your models in a given environment. Use this to see what data needs backfilling or processing. By default, it respects signals (like upstream dependencies); disable that to see all missing intervals.

```
Usage: vulcan check_intervals [OPTIONS] [ENVIRONMENT]

  Show missing intervals in an environment, respecting signals.

Options:
  --no-signals         Disable signal checks and only show missing intervals.
  --select-model TEXT  Select specific models to show missing intervals for.
  -s, --start TEXT     The start datetime of the interval for which this
                       command will be applied.
  -e, --end TEXT       The end datetime of the interval for which this command
                       will be applied.
  --help               Show this message and exit.
```

## clean

Clear Vulcan's cache and any build artifacts. Useful for troubleshooting or starting fresh. It does not delete your models or data, only the cached files.

```
Usage: vulcan clean [OPTIONS]

  Clears the Vulcan cache and any build artifacts.

Options:
  --help  Show this message and exit.
```

## create\_external\_models

Generate a schema file for external models that Vulcan can reference. Use this for tables or views that live outside your Vulcan project but that your models still need to reference.

The command writes to `inputs.yaml` in the project root. If your project already uses `inputs.yml`, it writes to that file instead. See [External models](https://v2.dataos.info/references/resources/vulcan/models/data-models/types/external-models.md) for the file format.

```
Usage: vulcan create_external_models [OPTIONS]

  Create a schema file containing external model schemas.

Options:
  --strict  Raise an error if the external model is missing in the database
  --help    Show this message and exit.
```

<details>

<summary>Example</summary>

```
$ vulcan create_external_models
```

</details>

## create\_deploy\_yaml

Generate a DataOS Vulcan resource deploy YAML file. Use this to package your Vulcan project into a deployment manifest you can apply in DataOS environments.

This is a deterministic renderer: every value in the output is either derived from your project, defaulted, or explicitly set in the `deployment:` block in `config.yaml`. There are no placeholder values left for you to fill in by hand. By default the manifest is written to `<project_name>-deploy.yaml` in the project root, and the command fails if that file already exists unless you pass `--overwrite`. Pass `-o -` to write to stdout instead. See [Configurations](https://v2.dataos.info/references/resources/vulcan/configurations.md#deployment) for the `deployment:` field reference.

If the `deployment:` block sets resources with the deprecated singular keys (`resource`, `request`, `limit`), the command prints a warning. Switch to `resources`, `requests`, and `limits`; see [Deployment](https://v2.dataos.info/references/resources/vulcan/deployment.md).

```
Usage: vulcan create_deploy_yaml [OPTIONS]

  Generate a DataOS Vulcan resource deploy YAML file.

Options:
  -o, --output TEXT  Output path for the generated DataOS Vulcan resource
                     YAML. Defaults to '<project_name>-deploy.yaml' in the
                     project root.
  --overwrite        Overwrite the output file if it already exists.
  --help             Show this message and exit.
```

<details>

<summary>Example</summary>

```
$ vulcan create_deploy_yaml
```

Write the manifest to a specific path, replacing the file if it already exists:

```
$ vulcan create_deploy_yaml -o ./deploy.yaml --overwrite
```

Pipe the result straight into `dataos-ctl` instead of writing a file first:

```
$ vulcan create_deploy_yaml -o - | dataos-ctl resource apply --in
```

</details>

## create\_test

Generate a unit test fixture for a model. The command creates the test file structure and can generate sample data from queries you provide. Use it to set up model tests without writing the boilerplate yourself.

```
Usage: vulcan create_test [OPTIONS] MODEL

  Generate a unit test fixture for a given model.

Options:
  -q, --query <TEXT TEXT>...  Queries that will be used to generate data for
                              the model's dependencies.
  -o, --overwrite             When true, the fixture file will be overwritten
                              in case it already exists.
  -v, --var <TEXT TEXT>...    Key-value pairs that will define variables
                              needed by the model.
  -p, --path TEXT             The file path corresponding to the fixture,
                              relative to the test directory. By default, the
                              fixture will be created under the test directory
                              and the file name will be inferred based on the
                              test's name.
  -n, --name TEXT             The name of the test that will be created. By
                              default, it's inferred based on the model's
                              name.
  --include-ctes              When true, CTE fixtures will also be generated.
  --help                      Show this message and exit.
```

<details>

<summary>Example</summary>

```
$ vulcan create_test sales.daily_sales --query raw.raw_orders "SELECT * FROM raw.raw_orders"
```

</details>

## destroy

⚠️ **Use with caution!** This command permanently removes all Vulcan-managed resources from your data warehouse, including state tables, the cache, and all project resources. It deletes all tables, views, and schemas that Vulcan manages, as well as any external resources created by other tools within those schemas. This is a destructive operation that can't be undone, so make sure you really want to do this before running it.

```
Usage: vulcan destroy

  Removes all state tables, the Vulcan cache and all project resources, including warehouse objects. This includes all tables, views and schemas managed by Vulcan, as well as any external resources that may have been created by other tools within those schemas.

Options:
  --help               Show this message and exit.
```

<details>

<summary>Example</summary>

```
$ vulcan destroy
[WARNING] This will permanently delete all engine-managed objects, state tables and Vulcan cache.
The operation may disrupt any currently running or scheduled plans.

Schemas to be deleted:
  • warehouse.raw
  • warehouse.sales

Snapshot tables to be deleted:
  • warehouse.vulcan__raw.raw__raw_customers__1474975870
  • warehouse.vulcan__raw.raw__raw_orders__1032938324
  • warehouse.vulcan__raw.raw__raw_products__3337559381
  • warehouse.vulcan__sales.sales__daily_sales__2671854529

This action will DELETE ALL the above resources managed by Vulcan AND
potentially external resources created by other tools in these schemas.

Are you ABSOLUTELY SURE you want to proceed with deletion? [y/n]: y
Environment 'prod' invalidated.

Deleted object warehouse.raw
Deleted object warehouse.sales
Deleted object warehouse.vulcan__raw.raw__raw_products__3337559381__dev
Deleted object warehouse.vulcan__raw.raw__raw_customers__1474975870__dev
Deleted object warehouse.vulcan__sales.sales__daily_sales__2671854529__dev
Deleted object warehouse.vulcan__sales.sales__daily_sales__2671854529
Deleted object warehouse.vulcan__raw.raw__raw_customers__1474975870
Deleted object warehouse.vulcan__raw.raw__raw_products__3337559381
Deleted object warehouse.vulcan__raw.raw__raw_orders__1032938324__dev
Deleted object warehouse.vulcan__raw.raw__raw_orders__1032938324
State tables removed.
Destroy completed successfully.
```

</details>

## diff

See what's different between your local project state and a target environment. Use it to review changes before running a plan. The output shows model changes, semantic layer changes, and quality check modifications in a clear diff format.

```
Usage: vulcan diff [OPTIONS] ENVIRONMENT

  Show the diff between the local state and the target environment.

Options:
  --help  Show this message and exit.
```

<details>

<summary>Example</summary>

```
$ vulcan diff prod

Differences from the `prod` environment:

Models:
└── Directly Modified:
    └── sales.daily_sales
        --- .../daily_sales.sql

        +++ .../daily_sales.sql

        @@ -20,10 +20,11 @@

          grains (order_date)
        )
        SELECT
          CAST(order_date AS TIMESTAMP) AS order_date,
          CAST(COUNT(order_id) AS INT) AS total_orders,
          CAST(SUM(total_amount) AS DOUBLE PRECISION) AS total_revenue,
        -  CAST(MAX(order_id) AS VARCHAR) AS last_order_id
        +  CAST(MAX(order_id) AS VARCHAR) AS last_order_id,
        +  COUNT(DISTINCT product_id) AS total_products
        FROM raw.raw_orders
        GROUP BY
          order_date
Semantics:
└── Indirectly Modified:
    ├── semantic-model:sales.daily_sales
    ├── semantic-metric:order_volume
    └── semantic-metric:revenue_trends
Quality Checks:
└── Indirectly Modified:
    ├── check-suite:sales.daily_sales:accuracy
    ├── check-suite:sales.daily_sales:timeliness
    ├── check-suite:sales.daily_sales:completeness
    └── check-suite:sales.daily_sales:validity
```

</details>

## environments

List all your Vulcan environments and see when they expire. This is helpful for managing development environments and understanding which ones might need cleanup.

```
Usage: vulcan environments [OPTIONS]

  Prints the list of Vulcan environments with its expiry datetime.

Options:
  --help             Show this message and exit.
```

<details>

<summary>Example</summary>

```
$ vulcan environments
Number of Vulcan environments are: 2
prod - No Expiry
dev - 2025-12-23 00:00:00
```

</details>

## evaluate

Preview a model's output without materializing it. Use it for debugging and quick iteration; you see what the model produces without running a full plan or run. Default limit is 1000 rows; you can adjust it.

```
Usage: vulcan evaluate [OPTIONS] MODEL

  Evaluate a model and return a dataframe with a default limit of 1000.

Options:
  -s, --start TEXT       The start datetime of the interval for which this
                         command will be applied.
  -e, --end TEXT         The end datetime of the interval for which this
                         command will be applied.
  --execution-time TEXT  The execution time (defaults to now).
  --limit INTEGER        The number of rows which the query should be limited
                         to.
  --help                 Show this message and exit.
```

<details>

<summary>Example</summary>

```
$ vulcan evaluate sales.daily_sales
   order_date  total_orders  total_revenue last_order_id  total_products
0  2024-01-05             1          70.77          O001               1
1  2024-01-10             1          44.22          O002               1
2  2024-01-15             1          65.52          O003               1
3  2024-01-20             1          79.42          O004               1
4  2024-02-01             1          91.35          O005               1
....
19 2024-05-15             1          38.38          O020               1
```

</details>

## export

Export project artifacts, such as the model DAG, join graph, contracts, metadata, OKF bundles, and product definitions. Use these commands to generate files that describe your project for downstream tools or integrations.

```
Usage: vulcan export [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  contract
  dag
  joins
  metadata
  okf
  product
```

### contract

Export the contract for a model, or for the project, to a file.

```
Usage: vulcan export contract [OPTIONS] [MODEL] [FILE]

Options:
  -e, --environment, --env TEXT  Environment to export (defaults to config
                                 default_target_environment). Requires the
                                 environment to exist in state (after plan).
  --help                         Show this message and exit.
```

### dag

Generate a visual dependency graph (DAG) of your data pipeline as an HTML file. Use it to see how models connect and how data flows through your pipeline. Open the file in any browser to explore the graph interactively.

```
Usage: vulcan export dag [OPTIONS] [FILE]

Options:
  --select-model TEXT  Limit the graph to these model selection expressions.
  --help               Show this message and exit.
```

<details>

<summary>Example</summary>

```
$ vulcan export dag ./dag.html
```

</details>

### joins

Export the join graph between your models as an HTML file. Use it to see how models are joined together, separately from the model dependency DAG.

```
Usage: vulcan export joins [OPTIONS] [FILE]

Options:
  --help  Show this message and exit.
```

<details>

<summary>Example</summary>

```
$ vulcan export joins ./joins.html
```

</details>

### metadata

Export metadata for an environment to a file.

```
Usage: vulcan export metadata [OPTIONS] [FILE]

Options:
  -e, --environment, --env TEXT  Environment to export (defaults to config
                                 default_target_environment). Requires the
                                 environment to exist in state (after plan).
  --help                         Show this message and exit.
```

<details>

<summary>Example</summary>

```
$ vulcan export metadata ./metadata.json --environment prod
```

</details>

### okf

Export an OKF bundle for an environment. The bundle is written as a zip archive by default; use `--format` to write a `tar.gz` archive or a plain directory tree instead.

```
Usage: vulcan export okf [OPTIONS] [OUTPUT]

Options:
  -e, --environment, --env TEXT  Environment to export (defaults to config
                                 default_target_environment). Requires the
                                 environment to exist in state (after plan).
  --format [zip|tar.gz|dir]      Output format: zip (default), tar.gz, or dir
                                 (write the bundle as a directory tree).
                                 [default: zip]
  --help                         Show this message and exit.
```

<details>

<summary>Example</summary>

```
$ vulcan export okf ./bundle --format dir --environment prod
```

</details>

### product

Export the product definition for an environment to a file.

```
Usage: vulcan export product [OPTIONS] [FILE]

Options:
  -e, --environment, --env TEXT  Environment to export (defaults to config
                                 default_target_environment). Requires the
                                 environment to exist in state (after plan).
  --help                         Show this message and exit.
```

## fetchdf

Run a raw SQL query against your data warehouse and see the results. Use it for quick data exploration or debugging queries without opening a separate database client.

```
Usage: vulcan fetchdf [OPTIONS] [SQL]

  Run a SQL query and display the results.

Options:
  -f, --file FILENAME            Read SQL from file. Use '-' to read from
                                 stdin.
  --format [table|csv|json|raw]  Output format: 'table' (formatted table),
                                 'csv' (CSV), 'json' (JSON), 'raw' (simple
                                 table).
  --help                         Show this message and exit.
```

<details>

<summary>Example</summary>

```
$ vulcan fetchdf "select count(*) from sales.daily_sales"
┏━━━━━━━┓
┃ count ┃
┡━━━━━━━┩
│ 20    │
└───────┘
```

</details>

## format

Format all SQL models and audits according to your formatting preferences. Keeps your codebase consistent and readable. Customize options like indentation, comma placement, and function name casing.

```
Usage: vulcan format [OPTIONS] [PATHS]...

  Format all SQL models and audits.

Options:
  -t, --transpile TEXT            Transpile project models to the specified
                                  dialect.
  --check                         Whether or not to check formatting (but not
                                  actually format anything).
  --rewrite-casts / --no-rewrite-casts
                                  Rewrite casts to use the :: syntax.
  --append-newline                Include a newline at the end of each file.
  --max-text-width INTEGER        The max number of characters in a segment
                                  before creating new lines in pretty mode.
  --leading-comma                 Determines whether or not the comma is
                                  leading or trailing in select expressions.
                                  Default is trailing.
  --normalize-functions TEXT      Whether or not to normalize all function
                                  names. Possible values are: 'upper', 'lower'
  --indent INTEGER                Determines the indentation size in a
                                  formatted string.
  --pad INTEGER                   Determines the pad size in a formatted
                                  string.
  --normalize                     Whether or not to normalize identifiers to
                                  lowercase.
  --help                          Show this message and exit.
```

## import\_semantic\_view

Import a Snowflake Semantic View into your Vulcan project. Vulcan reads the view definition from Snowflake via `SYSTEM$READ_YAML_FROM_SEMANTIC_VIEW()` and writes one `kind: semantic` YAML file per table under `models/snowflake_semantic/<VIEW_NAME>/`. Use this to bring an existing Snowflake Semantic View into the Vulcan semantic layer without writing the YAML by hand.

```
Usage: vulcan import_semantic_view [OPTIONS] VIEW_NAME

  Import a Snowflake Semantic View into the current Vulcan project.

Options:
  -c, --connection TEXT  Snowflake gateway/connection name to fetch the view
                         from. Required when VIEW_NAME is a fully-qualified
                         Snowflake identifier (e.g.
                         ECOMMERCE_PLATFORM.GOLD.MY_VIEW). If omitted the view
                         is resolved from local managed/imported YAML files.
  --output-dir TEXT      Base output directory for the imported semantic model
                         YAMLs. A subfolder named after the semantic view is
                         always created inside this directory (e.g.
                         models/TPCH_DEEP_CHAIN/). Defaults to
                         models/snowflake_semantic/.
  --help                 Show this message and exit.
```

<details>

<summary>Example</summary>

```
# Import by view name
$ vulcan import_semantic_view MY_SEMANTIC_VIEW --connection default

# Import using a fully qualified name
$ vulcan import_semantic_view MYDB.GOLD.MY_SEMANTIC_VIEW --connection default
```

</details>

For the full import workflow including `inputs.yaml` fixes and querying via the REST API, see [Import Snowflake Semantic Views](https://v2.dataos.info/references/resources/vulcan/advanced-features/import-snowflake-semantic-views.md).

## info

Show an overview of your Vulcan project. It reports how many models and macros you have and tests your connections to both the data warehouse and state backend. Run it first when setting up a new project or troubleshooting connection issues.

```
Usage: vulcan info [OPTIONS]

  Print information about a Vulcan project.

  Includes counts of project models and macros and connection tests for the
  data warehouse.

Options:
  --skip-connection  Skip the connection test.
  -v, --verbose      Verbose output. Use -vv for very verbose output.
  --help             Show this message and exit.
```

<details>

<summary>Example</summary>

```
$ vulcan info
Models: 4
Macros: 0
Data warehouse connection succeeded
State backend connection succeeded
```

</details>

## init

Initialize a new Vulcan project. Sets up the project structure and configuration files. Choose the default template or start with an empty project, and optionally set the tenant, project name, and description written to `config.yaml`.

`vulcan init` also adds `.vulcan/` to `.gitignore`: it holds the default local state database (see [State connection](https://v2.dataos.info/references/resources/vulcan/configurations.md#state-connection)) and shouldn't be committed.

```
Usage: vulcan init [OPTIONS] [ENGINE]

  Create a new Vulcan repository.

Options:
  -t, --template TEXT  Project template. Supported values: default, empty.
  --tenant TEXT        Project tenant to write into config.yaml.
  --name TEXT          Project name to write into config.yaml.
  --description TEXT   Project description to write into config.yaml.
  --help               Show this message and exit.
```

<details>

<summary>Example</summary>

```
$ vulcan init postgres
```

</details>

## invalidate

Mark an environment for deletion. The janitor process cleans it up on its next run. Use this to remove a development environment you no longer need. Deletion is asynchronous by default; use `--sync` to wait for it to complete.

```
Usage: vulcan invalidate [OPTIONS] ENVIRONMENT

  Invalidate the target environment, forcing its removal during the next run
  of the janitor process.

Options:
  -s, --sync  Wait for the environment to be deleted before returning. If not
              specified, the environment will be deleted asynchronously by the
              janitor process. This option requires a connection to the data
              warehouse.
  --help      Show this message and exit.
```

<details>

<summary>Example</summary>

```
$ vulcan invalidate dev
Environment 'dev' invalidated.
```

</details>

## migrate

Upgrade Vulcan's internal state to match the current version you're running. This is typically needed when you upgrade Vulcan itself. **Important:** This command affects all Vulcan users, so make sure to coordinate with your team and contact your Vulcan administrator before running it.

```
Usage: vulcan migrate [OPTIONS]

  Migrate Vulcan to the current running version.

Options:
  --help  Show this message and exit.
```

{% hint style="danger" %}
**Caution**

The `migrate` command affects all Vulcan users. Contact your Vulcan administrator before running.
{% endhint %}

## plan

Create and apply a plan that compares your local project state with a target environment and determines what changes to make. Use it to deploy model changes, add new models, and backfill data. The plan shows you exactly what will happen so you can review changes before you apply them.

```
Usage: vulcan plan [OPTIONS] [ENVIRONMENT]

  Apply local changes to the target environment.

Options:
  -s, --start TEXT                The start datetime of the interval for which
                                  this command will be applied.
  -e, --end TEXT                  The end datetime of the interval for which
                                  this command will be applied.
  --execution-time TEXT           The execution time (defaults to now).
  --create-from TEXT              The environment to create the target
                                  environment from if it doesn't exist.
                                  Default: prod.
  --skip-tests                    Skip tests prior to generating the plan if
                                  they are defined.
  --skip-linter                   Skip linting prior to generating the plan if
                                  the linter is enabled.
  -r, --restate-model TEXT        Restate data for specified models and models
                                  downstream from the one specified. For
                                  production environment, all related model
                                  versions will have their intervals wiped,
                                  but only the current versions will be
                                  backfilled. For development environment,
                                  only the current model versions will be
                                  affected.
  --no-gaps                       Ensure that new snapshots have no data gaps
                                  when comparing to existing snapshots for
                                  matching models in the target environment.
  --skip-backfill, --dry-run      Skip the backfill step and only create a
                                  virtual update for the plan.
  --empty-backfill                Produce empty backfill. Like --skip-backfill
                                  no models will be backfilled, unlike --skip-
                                  backfill missing intervals will be recorded
                                  as if they were backfilled.
  --forward-only                  Create a plan for forward-only changes.
  --allow-destructive-model TEXT  Allow destructive forward-only changes to
                                  models whose names match the expression.
  --allow-additive-model TEXT     Allow additive forward-only changes to
                                  models whose names match the expression.
  --effective-from TEXT           The effective date from which to apply
                                  forward-only changes on production.
  --no-prompts                    Disable interactive prompts for the backfill
                                  time range. Please note that if this flag is
                                  set and there are uncategorized changes,
                                  plan creation will fail.
  --auto-apply                    Automatically apply the new plan after
                                  creation.
  --no-auto-categorization        Disable automatic change categorization.
  --include-unmodified            Include unmodified models in the target
                                  environment.
  --select-model TEXT             Select specific model changes that should be
                                  included in the plan.
  --backfill-model TEXT           Backfill only the models whose names match
                                  the expression.
  --no-diff                       Hide text differences for changed models.
  --run                           Run latest intervals as part of the plan
                                  application (prod environment only).
  --enable-preview                Enable preview for forward-only models when
                                  targeting a development environment.
  --diff-rendered                 Output text differences for the rendered
                                  versions of the models and standalone
                                  audits.
  --explain                       Explain the plan instead of applying it.
  --ignore-cron                   Run all missing intervals, ignoring
                                  individual cron schedules. Only applies if
                                  --run is set.
  --min-intervals INTEGER         For every model, ensure at least this many
                                  intervals are covered by a missing intervals
                                  check regardless of the plan start date
  --migrate                       Run state migration before planning.
  -v, --verbose                   Verbose output. Use -vv for very verbose
                                  output.
  --help                          Show this message and exit.
```

## render

See the SQL Vulcan will execute for a model. Use it to debug and understand how Vulcan transforms model definitions into executable SQL. Optionally expand referenced models to see the full query with all dependencies inlined.

```
Usage: vulcan render [OPTIONS] MODEL

  Render a model's query, optionally expanding referenced models.

Options:
  -s, --start TEXT            The start datetime of the interval for which
                              this command will be applied.
  -e, --end TEXT              The end datetime of the interval for which this
                              command will be applied.
  --execution-time TEXT       The execution time (defaults to now).
  --expand TEXT               Whether or not to expand materialized models
                              (defaults to False). If True, all referenced
                              models are expanded as raw queries. Multiple
                              model names can also be specified, in which case
                              only they will be expanded as raw queries.
  --dialect TEXT              The SQL dialect to render the query as.
  --no-format                 Disable fancy formatting of the query.
  --max-text-width INTEGER    The max number of characters in a segment before
                              creating new lines in pretty mode.
  --leading-comma             Determines whether or not the comma is leading
                              or trailing in select expressions. Default is
                              trailing.
  --normalize-functions TEXT  Whether or not to normalize all function names.
                              Possible values are: 'upper', 'lower'
  --indent INTEGER            Determines the indentation size in a formatted
                              string.
  --pad INTEGER               Determines the pad size in a formatted string.
  --normalize                 Whether or not to normalize identifiers to
                              lowercase.
  --help                      Show this message and exit.
```

<details>

<summary>Example</summary>

```
$ vulcan render sales.daily_sales

SELECT
  CAST("raw_orders"."order_date" AS TIMESTAMP) AS "order_date",
  CAST(COUNT("raw_orders"."order_id") AS INT) AS "total_orders",
  CAST(SUM("raw_orders"."total_amount") AS DOUBLE PRECISION) AS "total_revenue",
  CAST(MAX("raw_orders"."order_id") AS VARCHAR) AS "last_order_id",
  COUNT(DISTINCT "raw_orders"."product_id") AS "total_products"
FROM "warehouse"."vulcan__raw"."raw__raw_orders__1032938324" AS "raw_orders" /* warehouse.raw.raw_orders */
GROUP BY
  "raw_orders"."order_date"
ORDER BY
  "order_date"
```

</details>

## review

Run an AI-assisted review of your model changes against a target environment. Vulcan compares your working tree to the environment's live metadata and plan state, then sends the diff to the LLM configured under `review:` in `config.yaml` (see [Configurations → Review](https://v2.dataos.info/references/resources/vulcan/configurations.md#review)). `review.model` is required — the command raises without it. The report is written as an HTML file, by default under `.vulcan/reviews`.

Requires the `review` extra: `pip install "./vulcan-0.228.1.32-py3-none-any.whl[review]"`.

```
Usage: vulcan review [OPTIONS]

Options:
  -e, --environment, --env TEXT  Environment to compare the working tree
                                 against for live metadata and plan state.
  --llm, --llm-model TEXT        LLM model to be used for the review.
  --output DIRECTORY             Directory for the report. Defaults to
                                 .vulcan/reviews.
  --report-format [html]         Report artifact to persist: html.
  --debug                        Raise logging to DEBUG for this run.
  --help                         Show this message and exit.
```

## rewrite

Rewrite a semantic SQL query against an environment. Pass the query as an argument, read it from a file, or pipe it through stdin. Like `transpile`, it accepts a caller id and security context attributes, so you can test how row/column-level security applies to a query.

```
Usage: vulcan rewrite [OPTIONS] [SQL]

Options:
  --file TEXT                    File path ('-' = stdin)
  --user TEXT                    Caller id (default: vulcan-cli)
  -sc, --security-context TEXT   Security context key=value (repeatable).
  --style [pretty|compact]       pretty or compact
  -e, --environment, --env TEXT  Environment (default: from config)
  --help                         Show this message and exit.
```

<details>

<summary>Example</summary>

```
$ vulcan rewrite "SELECT * FROM sales.daily_sales" --environment prod
```

Read the query from a file and pass a security context attribute:

```
$ vulcan rewrite --file ./query.sql --security-context group=alpha --style compact
```

</details>

## rollback

Revert Vulcan's internal state to the previous migration version. This is useful if a migration caused issues and you need to go back. **Important:** Like `migrate`, this command affects all Vulcan users, so coordinate with your team and contact your Vulcan administrator before running it.

```
Usage: vulcan rollback [OPTIONS]

  Rollback Vulcan to the previous migration.

Options:
  --help  Show this message and exit.
```

{% hint style="danger" %}
**Caution**

The `rollback` command affects all Vulcan users. Contact your Vulcan administrator before running.
{% endhint %}

## run

Process missing time intervals for your models in a target environment. `run` executes scheduled work based on cron schedules; `plan` deploys changes. Use `run` to process new or missing data without changing model definitions.

```
Usage: vulcan run [OPTIONS] [ENVIRONMENT]

  Evaluate missing intervals for the target environment.

Options:
  -s, --start TEXT              The start datetime of the interval for which
                                this command will be applied.
  -e, --end TEXT                The end datetime of the interval for which
                                this command will be applied.
  --execution-time TEXT         The execution time (defaults to now).
  --skip-janitor                Skip the janitor task.
  --ignore-cron                 Run for all missing intervals, ignoring
                                individual cron schedules.
  --select-model TEXT           Select specific models to run. Note: this
                                always includes upstream dependencies.
  --exit-on-env-update INTEGER  If set, the command will exit with the
                                specified code if the run is interrupted by an
                                update to the target environment.
  --no-auto-upstream            Do not automatically include upstream models.
                                Only applicable when --select-model is used.
                                Note: this may result in missing / invalid
                                data for the selected models.
  --migrate                     Run state migration before run.
  --help                        Show this message and exit.
```

## table\_diff

Compare data between two tables or models to see what's different. Use it to validate that changes produce the expected results, compare environments, or debug data discrepancies. Compare entire tables or specific models, and customize how the comparison works.

```
Usage: vulcan table_diff [OPTIONS] SOURCE:TARGET [MODEL]

  Show the diff between two tables or a selection of models when they are
  specified.

Options:
  -o, --on TEXT            The column to join on. Can be specified multiple
                           times. The model grain will be used if not
                           specified.
  -s, --skip-columns TEXT  The column(s) to skip when comparing the source and
                           target table.
  --where TEXT             An optional where statement to filter results.
  --limit INTEGER          The limit of the sample dataframe.
  --show-sample            Show a sample of the rows that differ. With many
                           columns, the output can be very wide.
  -d, --decimals INTEGER   The number of decimal places to keep when comparing
                           floating point columns. Default: 3
  --skip-grain-check       Disable the check for a primary key (grain) that is
                           missing or is not unique.
  --warn-grain-check       Warn if any selected model is missing a grain,
                           and compute diffs for the remaining models.
  --temp-schema TEXT       Schema used for temporary tables. It can be
                           `CATALOG.SCHEMA` or `SCHEMA`. Default:
                           `vulcan_temp`
  -m, --select-model TEXT  Specify one or more models to data diff. Use
                           wildcards to diff multiple models. Ex: '*' (all
                           models with applied plan diffs), 'demo.model+'
                           (this and downstream models),
                           'git:feature_branch' (models with direct
                           modifications in this branch only)
  --schema-diff-ignore-case  If set, when performing a schema diff the case of
                           column names is ignored when matching between the
                           two schemas. For example, 'col_a' in the source
                           schema and 'COL_A' in the target schema will be
                           treated as the same column.
  --help                   Show this message and exit.
```

## table\_name

Get the physical table name Vulcan uses for a model. Use this when you need to reference the table directly in SQL or other tools, since Vulcan's internal naming may differ from your model name.

```
Usage: vulcan table_name [OPTIONS] MODEL_NAME

  Prints the name of the physical table for the given model.

Options:
  --environment, --env TEXT  The environment to source the model version from.
  --prod                     If set, return the name of the physical table
                             that will be used in production for the model
                             version promoted in the target environment.
  --help                     Show this message and exit.
```

## test

Run unit tests for your models. Tests validate that your SQL logic works correctly with the test fixtures you've defined. Use it to catch bugs before deploying to production.

```
Usage: vulcan test [OPTIONS] [TESTS]...

  Run model unit tests.

Options:
  -k TEXT              Only run tests that match the pattern of substring.
  -v, --verbose        Verbose output. Use -vv for very verbose output.
  --preserve-fixtures  Preserve the fixture tables in the testing database,
                       useful for debugging.
  --help               Show this message and exit.
```

## lint

Run linting rules on your models to catch issues and enforce code quality standards. Lint specific models or all models in your project. Use it to keep code quality consistent and catch common mistakes early.

```
Usage: vulcan lint [OPTIONS]

  Run the linter for the target model(s).

Options:
  --models, --model TEXT  A model to lint. Multiple models can be linted. If
                          no models are specified, every model will be linted.
  --help                  Show this message and exit.

```

## transpile

Transpile a semantic SQL query or a REST-style semantic payload against an environment. Use it to see how a semantic query gets translated, propagating a user and security context attributes for testing row/column-level security.

```
Usage: vulcan transpile [OPTIONS] [QUERY]

Options:
  --format [sql|rest]             sql or rest  [required]
  --file TEXT                     File path ('-' = stdin)
  --user TEXT                     Caller id (default: vulcan-cli)
  -sc, --security-context TEXT    Security context key=value (repeatable).
  --disable-post-processing       Skip transpiler post-processing
  --inline-params / --no-inline-params
                                  Inline bound parameters into SQL (default:
                                  enabled).
  --style [pretty|compact]        pretty or compact
  -e, --environment, --env TEXT   Environment (default: from config)
  --help                          Show this message and exit.
```

<details>

<summary>Example</summary>

```
$ vulcan transpile "SELECT * FROM sales.daily_sales" --format sql --environment prod
```

</details>


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://v2.dataos.info/references/resources/vulcan/cli.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
