Core Rudder CLI Commands Reference Beta

This guide covers the core workflow commands available in the Rudder CLI tool 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.

rudder-cli auth login

You will be prompted to enter your workspace-level Service Access Token or Personal Access Token (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.

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.

Supported resources for import

• Data Catalog (Events, Properties, Categories, Custom Types)
• Tracking Plans
• Event Stream sources (SDK-based)
• Destinations
• Event Stream connections
• Transformations and Transformation Libraries
• SQL Models
• Warehouse accounts
• Data Graphs

Flags

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.

See Import Workspace 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.

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 connection eligibility and topology rules

apply

Sync your local configurations to your RudderStack workspace.

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.

apply can delete resources that aren’t in your project

Running apply on an empty or partial project deletes every CLI-managed resource in the workspace that the project doesn’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.
• Manage each workspace with only one CLI project. See One project per workspace.

If your YAML uses {{ .VAR }} references, pass --var-file. See How to Use Variable Substitution in Rudder CLI.

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

Dry run

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

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.

This is a destructive operation.

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.

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:

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