How to Sync Retool Custom Components Across Multiple Instances

If you're managing Retool custom components across multiple instances or Spaces, you've probably run into the question: how do I keep everything in sync without manually redeploying to every environment? This guide covers the exact workflow to set up a primary development instance, use npx retool-ccl sync to push to secondary targets, and avoid the most common pitfalls — including the tricky case of repointing an existing component library to a new UAT Space.

What You Need Before You Start

Multiple Retool instances, Spaces, and source control integration are only available on the Enterprise Plan. Before following this guide, make sure you have:

• Access to the retool-ccl CLI (Retool's Custom Component Library toolchain)
• At least two Retool instances or Spaces (e.g. staging and production)
• An access token for each target instance with Custom Component Libraries read and write scopes enabled
• A source control setup (Git) connecting your instances

Step 1: Choose a Primary Instance for Component Development

The most important architectural decision is picking one instance as your primary development environment for custom components. This is the only instance you should log into with the CLI, and the only place where you build and deploy new component versions. Mixing development across instances leads to version conflicts and broken dev branches — don't do it.

Run the following to authenticate against your primary instance:

npx retool-ccl login

All npx retool-ccl dev and npx retool-ccl deploy commands should be run while logged into this primary instance only.

Step 2: Configure Sync Targets With retool-ccl sync

Once your primary instance is set, you can register secondary instances (like production or a UAT Space) as sync targets. Run:

npx retool-ccl sync

This command walks you through selecting or adding a target instance. You'll need a valid access token for each target with the correct scopes. Once configured, that instance will appear as a selectable option every time you run sync going forward — no need to re-enter credentials each time.

Step 3: The Full Development and Deployment Workflow

Here's the end-to-end workflow for developing a custom component change and getting it live across all your Retool environments:

• In your custom component repo, log in to your primary instance: npx retool-ccl login
• In your Retool staging app, create a new branch for your changes
• Start the dev environment: npx retool-ccl dev
• Make and save your component changes locally
• Deploy the updated version: npx retool-ccl deploy
• Sync the new version to your secondary instance(s): npx retool-ccl sync and select the target
• In staging, exit dev mode and update the component to the latest deployed version
• Commit your app changes, open a PR, and merge
• Once merged, your production instance will reflect the updated component via source control

The key principle: component changes always flow from primary → secondary, never the other way around. Your production instance should never be the origin of a component change.

Why retool-ccl dev Shows No Branches in Your UAT Space

This is a common gotcha. If you run npx retool-ccl dev and see no development branches available for your UAT Space — only your main/production Space — it's because the dev environment is always tied to the primary instance where the component was originally deployed.

If you synced a component library to UAT using npx retool-ccl sync but the original npx retool-ccl deploy was run against your production Space, UAT is treated as a read-only sync target, not a development origin. You won't be able to create dev branches there.

The fix: Create a new Custom Component Library and deploy it first to your UAT Space (making UAT the primary instance for that library). Then sync it to production. This is the correct gitflow-compatible setup: develop in UAT, merge to main, have production reflect the merged state via source control.

How to Set Up Custom Components With a UAT-First Gitflow

If you're following a gitflow branching model with a UAT Space that merges into a production main branch, here's how to structure your component library from scratch:

• Log into your UAT Space as the primary instance: npx retool-ccl login
• Initialize and deploy your component library to UAT: npx retool-ccl deploy
• Add your production Space as a sync target: npx retool-ccl sync
• All development branches and npx retool-ccl dev sessions now operate against UAT
• After QA in UAT, sync the approved version to production and let source control handle the app-level merge

This matches how most engineering teams already think about environment promotion and keeps your component versioning predictable.

Taking It Further: CI/CD for retool-ccl

If you want to remove manual steps entirely, you can integrate retool-ccl sync into a CI/CD pipeline. This means every time a component change is merged to your main branch, your pipeline automatically syncs the latest deployed version to all target instances — no human interaction required. This is especially valuable when managing more than two Spaces or when multiple teams are contributing to the same component library.

Quick Troubleshooting Reference

• No dev branches in target Space: You're logged into a secondary/sync target. Log into the primary instance instead.
• Sync command fails with auth error: Check that your access token has both read and write scopes for Custom Component Libraries.
• Component version not updating in production: Confirm the PR was merged and that source control is properly connected to your production instance.
• Need to change the primary instance: Create a new component library deployment targeting the new primary — there is no "repoint" command.

Managing Retool custom components across multiple instances and Spaces is straightforward once you internalize the primary-instance model. Pick one origin, deploy from there, sync everywhere else, and let source control handle the rest. If your current setup has the wrong instance as primary, the cleanest fix is a fresh deploy to the correct environment rather than trying to reassign ownership after the fact.