Archive: How to Manage Workspaces with Rudder CLI

Mon, 01 Jan 0001 00:00:00 +0000

This guide explains how to use import metadata and Rudder CLI to move between development and production workspaces and to streamline deployment.

Overview

workspace_id inside import metadata records where you imported from. When you later run apply against another workspace (for example production), Rudder CLI can create fresh resources there instead of binding to the original import.

You can build and test in a development workspace, then promote the same project to production. The same workflow covers Data Catalog, Tracking Plans, SQL Models, and Event Stream Sources.

Streamline import and production deployment

For production environments, you can streamline the import and deployment process by integrating Rudder CLI with your CI/CD pipeline. This approach allows you to import resources once and then have your automated pipeline handle subsequent deployments.

Workflow

Import: Run import workspace and generate YAML from the workspace
Organize: Place files where your repository expects them
Commit: Push the YAML to version control
Deploy: Run rudder-cli apply from the pipeline

CI/CD authentication and permissions

Configure your pipeline with a workspace-level Service Access Token with the same resource permissions you use for local import and apply. Limit the token to the resource types the pipeline touches.

For token types, legacy RBAC, and Personal Access Token caveats, see Prerequisites in the import guide.

Benefits

Automated deployments: The pipeline applies approved YAML without manual CLI steps
Version control: Every change has a Git history
Consistent environments: The same definitions land in each stage you target
Rollback: You revert through Git when you need to undo a release

See GitHub Actions for a full CI/CD example.

Archive: Troubleshoot Import and Apply Errors

Mon, 01 Jan 0001 00:00:00 +0000

This guide covers common validation and error scenarios when you import workspace resources into a CLI project or run apply afterward.

Unsynced changes in project

If your project has unsynced changes, running the import workspace command will give you the following error:

Error: import not allowed as project has changes to be synced

Fix: Run apply to sync pending changes, then run import workspace again.

Imported directory already exists

If an imported directory already exists in your project, the import workspace command will fail with the following error:

Error: directory for import: my-project/imported already exists

Fix: Move anything you need out of imported/, delete the imported directory, and run import workspace again.

Import fails for a specific resource

When import workspace or a resource-specific import fails:

Confirm the workspace still contains the remote_id you’re importing
Confirm your token includes the required permissions for that resource type
Make sure the local_id doesn’t conflict with an existing CLI-managed resource

Apply fails after import

When apply fails right after an import:

Check that every generated YAML file is present and valid
For SQL models you imported with --sql-location, keep the YAML and the referenced .sql file on the paths Rudder CLI expects
Confirm you’re logged in and the token can reach the workspace
Confirm that no manual changes were made to the resource in the RudderStack dashboard after import — if changes were made outside Rudder CLI, you will be prompted to reconcile them

Resource deleted from dashboard before apply

If you delete a resource from the RudderStack dashboard after running import workspace but before running apply, the apply command will fail with:

Resource with ID not found

Fix: Remove the matching YAML from the project (or rewrite it so Rudder CLI creates a new resource), then run apply again.

RudderStack Docs – How to Import Workspace Resources into Your Rudder CLI Project