# Core Rudder CLI Commands Reference


> Core Rudder CLI commands, flags, and options for authentication, import, validation, apply, and destroy, plus pointers to resource-specific subcommands.



This guide covers the **core workflow commands** available in the [Rudder CLI tool](https://www.rudderstack.com/docs/rudder-cli/) for managing resources like Tracking Plans, Data Catalog, SQL Models, destinations, connections, and Transformations.

For resource-specific commands (for example SQL model preview or transformation tests), see the sections below and the linked how-to guides.

## Authentication

Before running any commands, you must authenticate the CLI tool with your RudderStack workspace.

```bash
rudder-cli auth login
```

You will be prompted to enter your [workspace-level Service Access Token](https://www.rudderstack.com/docs/access-management/service-access-tokens/#workspace-sat) or [Personal Access Token](https://www.rudderstack.com/docs/access-management/personal-access-tokens/) (for **Free** and **self-hosted** plans).

## Commands

Use the following commands to manage various RudderStack resources.

### `import workspace`

Import existing resources from your RudderStack workspace into your local project directory. Use it to adopt a workspace that you've managed in the dashboard so far: run it from an empty directory, then link the imported resources with `apply`.

```bash
rudder-cli import workspace -l <project-directory>
```

The command only imports resources that no CLI project manages yet, and writes them under `<project-directory>/imported/`. It fails with `import not allowed as project has changes to be synced` if your project differs from the CLI-managed resources in the workspace, for example because another project already manages some of them. Don't run `apply` to clear that error; see [Project has changes to be synced](https://www.rudderstack.com/docs/rudder-cli/import-resources/troubleshooting/#unsynced-changes-in-project).

**Supported resources for import**

- Data Catalog (Events, Properties, Categories, Custom Types)
- Tracking Plans
- Event Stream sources (SDK-based)
- Destinations
- Event Stream connections
- Reverse ETL connections (see [Manage Reverse ETL Connections using Rudder CLI](https://www.rudderstack.com/docs/rudder-cli/retl-connections/))
- Transformations and Transformation Libraries
- SQL Models
- Reverse ETL table sources (see [Manage Reverse ETL Table Sources using Rudder CLI](https://www.rudderstack.com/docs/rudder-cli/retl-tables/))
- Warehouse accounts
- Data Graphs

**Flags**

| Flag | Description |
| :-----| :-----|
| `-l`, `--location` | Path to the project directory. Defaults to the current directory. |
| `--var-file` | Path to a variable file ending in `.vars.yaml` or `.vars.yml`. Repeatable — a later file takes priority over an earlier one. |

Pass `--var-file` when specs already in your project use `{{ .VAR }}` references. Import loads the project before it writes, so unresolved references fail it with the same error `apply` gives. See [Import a project that uses variable substitution](https://www.rudderstack.com/docs/rudder-cli/import-resources/#import-with-var-file).

See [Import Workspace Resources](https://www.rudderstack.com/docs/rudder-cli/import-resources/) for the step-by-step adoption flow, prerequisites, metadata, and troubleshooting.

### `validate`

Validate your local YAML configurations for syntax errors, structural integrity, and resource-specific constraints.

```bash
rudder-cli validate -l <project-directory>
```

**What it checks**

- YAML syntax and schema compliance
- Resource referencing (for example, ensuring an event references a valid property, or a connection references a source and destination in the same project)
- Transformation code syntax
- SQL syntax and warehouse connectivity
- Destination `config` for the selected destination type
- Event Stream and Reverse ETL connection eligibility and topology rules
- Reverse ETL connection schedules, mappings, and sync modes

### `apply`

Sync your local configurations to your RudderStack workspace.

```bash
rudder-cli apply -l <project-directory>
```

`apply` compares your project with every CLI-managed resource in the workspace. It creates resources that are only in your project, updates resources that differ, links imported resources, and **deletes** CLI-managed resources that aren't in your project. It prints the plan and asks you to confirm before it changes anything.

**Warning**

**`apply` can delete resources that aren&#39;t in your project**

Running `apply` on an empty or partial project deletes every CLI-managed resource in the workspace that the project doesn&#39;t contain, including resources that another CLI project manages.

- Always run `apply --dry-run` first and review the plan. Everything listed under **Removed resources** is deleted when you apply.
- Never run `apply` just to clear the `import not allowed as project has changes to be synced` error. See [Project has changes to be synced](https://www.rudderstack.com/docs/rudder-cli/import-resources/troubleshooting/#unsynced-changes-in-project).
- Manage each workspace with only one CLI project. See [One project per workspace](https://www.rudderstack.com/docs/rudder-cli/import-resources/#one-project-per-workspace).

If your YAML uses `{{ .VAR }}` references, pass `--var-file`. See [How to Use Variable Substitution in Rudder CLI](https://www.rudderstack.com/docs/rudder-cli/variable-substitution/).

```bash
rudder-cli apply -l <project-directory> --var-file ./credentials.vars.yaml
```

| Flag | Description |
| :--- | :--- |
| `-l`, `--location` | Path to the project directory or a specific file. Defaults to the current directory. |
| `--dry-run` | Prints the plan without applying it. |
| `--confirm` | Asks for confirmation before applying. Defaults to `true`. In a non-interactive shell, such as a CI job, `apply` can't prompt and exits without applying unless you pass `--confirm=false`. |
| `--var-file` | Path to a variable file ending in `.vars.yaml` or `.vars.yml`. Repeatable — a later file takes priority over an earlier one. |

#### Dry run

Run `apply` with the `--dry-run` flag first to preview the changes to your workspace. A dry run never changes the workspace.

```bash
rudder-cli apply -l <project-directory> --dry-run
```

The plan groups resources under **Importable resources**, **New resources**, **Updated resources**, and **Removed resources**. Resources whose only difference is a secret value appear under **Always re-applied (secret values can't be read back)**.

If your specs use variable substitution, include `--var-file` on dry run as well.

### `destroy`

Use this command to **permanently remove** every resource that Rudder CLI manages in your workspace. It doesn't read your local project, so it also removes CLI-managed resources that aren't in your project files.

**Danger**

This is a destructive operation.

```bash
rudder-cli destroy
```

Rudder CLI lists what it plans to remove and asks you to confirm before anything is deleted. Run `rudder-cli destroy --dry-run` to see the list without deleting anything. Pass `--confirm=false` to skip the prompt in a non-interactive shell.

**Tip**

Flags and behavior can change between CLI releases — run `rudder-cli destroy --help` for the options your build supports, and prefer dry runs (`validate`, `apply --dry-run`) in CI before you use destroy in production.

## Additional command groups

The CLI also exposes subcommands for specific workflows. See the linked docs for syntax, flags, and examples:

| Resource | Example commands | Documentation |
|------|---------------------|----------------|
| SQL Models (Reverse ETL) | <ul><li>`rudder-cli workspace accounts list`</li><li>`rudder-cli workspace retl-sources list`</li><li>`rudder-cli import retl-sources ...`</li><li>`rudder-cli retl-sources preview ...`</li><li>`rudder-cli retl-sources validate ...`</li></ul> | <ul><li>[Create SQL Models](https://www.rudderstack.com/docs/rudder-cli/sql-models/create/)</li><li>[Import SQL Models](https://www.rudderstack.com/docs/rudder-cli/sql-models/import/)</li><li>[Validate and Preview SQL Models](https://www.rudderstack.com/docs/rudder-cli/sql-models/validate/)</li></ul> |
| Table sources (Reverse ETL) | <ul><li>`rudder-cli retl-sources preview ...`</li><li>`rudder-cli retl-sources validate ...`</li><li>`rudder-cli import workspace ...`</li></ul> | [Manage Reverse ETL Table Sources](https://www.rudderstack.com/docs/rudder-cli/retl-tables/) |
| Transformations | <ul><li>`rudder-cli transformations test ...`</li><li>`rudder-cli transformations show-default-events`</li></ul> | <ul><li>[Transformations Quickstart](https://www.rudderstack.com/docs/rudder-cli/transformations-walkthrough/)</li><li>[Transformation YAML Reference](https://www.rudderstack.com/docs/rudder-cli/yaml-transformations/)</li></ul> |
| Code Generation | <ul><li>`rudder-cli typer generate ...`</li><li>`rudder-cli typer options kotlin`</li><li>`rudder-cli typer options swift`</li><li>`rudder-cli typer options typescript`</li></ul> | [RudderTyper v2 Command Reference](https://www.rudderstack.com/docs/rudder-cli/ruddertyper-v2-command-reference/) |
| Local event capture (experimental) | <ul><li>`rudder-cli sources listen ...`</li><li>`rudder-cli sources events ...`</li></ul> | <ul><li>[How to Verify App Events Locally](https://www.rudderstack.com/docs/rudder-cli/verify-events-locally/)</li><li>[Sources Listen Command Reference](https://www.rudderstack.com/docs/rudder-cli/sources-listen-command-reference/)</li></ul> |

Run `rudder-cli --help` and `rudder-cli <command> --help` locally for the full list of subcommands and flags for your CLI version.