How to Integrate Retool with Git

The Retool CLI is a Node.js package that provides commands for managing Retool apps programmatically. Install it globally using npm: npm install -g @tryretool/retool-cli. Verify the installation by running retool --version to confirm it's working. Next, authenticate the CLI with your Retool instance. Run retool login --retoolHost https://your-company.retool.com (replace with your Retool Cloud or self-hosted URL). The CLI will open a browser window for you to sign in to Retool. After signing in, your session is stored locally in a credentials file, and the CLI can make authenticated API calls to your Retool instance. For CI/CD pipelines and automated scripts, use a Retool API token instead of interactive login. Generate a token in Retool by going to Settings → Account → API Tokens → Create Token. Set the RETOOL_ACCESS_TOKEN environment variable to this token, and the CLI will use it automatically without requiring interactive login. Run retool whoami to confirm you're authenticated correctly — this command displays your Retool username and the connected Retool instance URL.

1# Install the Retool CLI
2npm install -g @tryretool/retool-cli
3
4# Authenticate with your Retool instance
5retool login --retoolHost https://your-company.retool.com
6
7# Verify authentication
8retool whoami
9
10# For CI/CD: use environment variable authentication
11export RETOOL_ACCESS_TOKEN=your_api_token
12retool whoami

With the CLI authenticated, export your Retool apps to JSON files that can be committed to Git. Create a directory structure in your Git repository for Retool apps — a common pattern is /retool/apps/ with subdirectories for different app categories or teams. To list all apps available in your Retool instance, run retool apps list. This shows all apps with their names and IDs. Choose which apps to version-control — start with production-critical apps before adding development or testing apps. Export a specific app with retool apps export --appName "Your App Name" --output ./retool/apps/. This creates a JSON file named after the app in the output directory. The JSON file contains the complete app definition: all components and their configurations, all queries with SQL and transformer code, event handlers, page structure, and app settings. For exporting all apps at once, iterate through the app list: retool apps list --output json | jq -r '.[].name' | while read name; do retool apps export --appName "$name" --output ./retool/apps/; done. Add this command to a shell script in your repository for easy re-running. Commit the exported JSON files to Git: git add retool/apps/ && git commit -m 'Export Retool apps for version control'. Push to your remote repository to share with the team.

1# Export a specific app
2retool apps export --appName "Customer Support Panel" --output ./retool/apps/
3
4# Export all apps
5retool apps list --output json | python3 -c "
6import json, sys, subprocess
7apps = json.load(sys.stdin)
8for app in apps:
9    subprocess.run(['retool', 'apps', 'export', '--appName', app['name'], '--output', './retool/apps/'])
10"
11
12# Commit to Git
13git add retool/apps/
14git commit -m 'Export Retool apps - $(date +%Y-%m-%d)'
15git push origin main

Establish a Git branching strategy for Retool app development. The recommended pattern follows the same conventions as application code development: Main branch: Always represents the production-ready state. No direct commits — changes come only through pull requests. When the main branch is updated, import the JSON into your production Retool environment. Staging branch: Merged from main + pending features. Used to deploy to your staging Retool environment for final verification before production. Feature branches: Each developer creates a branch for their Retool changes (e.g., feature/add-refund-button, fix/broken-customer-query). Export the modified app to JSON, commit to the feature branch, and open a pull request. To make a change: (1) Create a feature branch in Git. (2) Make the change in your Retool development environment. (3) Export the updated app JSON. (4) Commit the JSON to the feature branch. (5) Open a pull request for code review. (6) After approval, merge to staging/main and import the JSON to the corresponding Retool environment. Use git diff on the Retool JSON files to review exactly what changed between versions. The diffs show modified queries, added/removed components, and updated transformer logic — giving reviewers a clear picture of the change.

1# Create a feature branch for Retool changes
2git checkout -b feature/add-bulk-refund-button
3
4# Make changes in your Retool development environment, then export
5retool apps export --appName "Order Management" --output ./retool/apps/
6
7# Review what changed
8git diff retool/apps/Order\ Management.json
9
10# Commit the changes
11git add retool/apps/
12git commit -m 'Add bulk refund button to Order Management app'
13git push origin feature/add-bulk-refund-button
14# Open pull request on GitHub/GitLab

After merging a pull request or during a deployment process, import the updated JSON files back into the target Retool environment. This is the 'deploy' step of the Retool version control workflow. To import a single app from a JSON file, use: retool apps import --path ./retool/apps/app-name.json. If the app already exists in Retool with the same name, the CLI updates it. If it doesn't exist, the CLI creates it. For deploying to a different environment (e.g., from staging to production), switch the CLI authentication to the target environment first: set the RETOOL_HOST and RETOOL_ACCESS_TOKEN environment variables to the production Retool instance, then run the import commands. This pattern enables environment-specific deployments from the same Git repository. For automated CI/CD pipelines (GitHub Actions, CircleCI, Jenkins), add a deployment job that triggers on merges to specific branches. The job authenticates to the appropriate Retool environment and imports all changed JSON files. Use git diff --name-only to identify only the files that changed in the merge and import those specifically rather than re-importing every app. Retool's configuration variables (Settings → Configuration Variables) handle environment-specific values like API endpoints and database connections — the same app JSON works across environments because the variable names stay constant while only their values change per environment.

1#!/bin/bash
2# CI/CD deployment script: deploy changed Retool apps to target environment
3# Usage: ./deploy_retool.sh production
4
5ENVIRONMENT=$1
6
7if [ "$ENVIRONMENT" = "production" ]; then
8  export RETOOL_HOST="https://prod.retool.yourcompany.com"
9  export RETOOL_ACCESS_TOKEN="$RETOOL_PROD_TOKEN"
10elif [ "$ENVIRONMENT" = "staging" ]; then
11  export RETOOL_HOST="https://staging.retool.yourcompany.com"
12  export RETOOL_ACCESS_TOKEN="$RETOOL_STAGING_TOKEN"
13fi
14
15# Find JSON files changed in the last merge
16CHANGED_FILES=$(git diff --name-only HEAD~1 HEAD -- 'retool/apps/*.json')
17
18# Import each changed file
19for file in $CHANGED_FILES; do
20  echo "Deploying $file to $ENVIRONMENT..."
21  retool apps import --path "$file"
22done
23
24echo "Deployment to $ENVIRONMENT complete."

For Retool Business and Enterprise plans, Source Code Sync automates the export/import cycle by directly connecting Retool to your Git provider. Instead of manually running CLI commands, every app save in Retool automatically commits to your Git repository, and checking out a branch in your Git provider automatically loads the corresponding app version in Retool. To set up Source Code Sync, go to your Retool instance's Settings → Source Code Sync. Click 'Connect to GitHub' (or GitLab/Bitbucket). Authorize Retool to access your Git organization and select the repository where you want to store app definitions. Configure the branch mapping: specify which Git branch maps to which Retool environment. Typically, the main branch maps to production, a develop branch maps to staging, and feature branches map to development. Retool creates commits automatically with the message format '[Retool] App name - change description'. With Source Code Sync active, every developer working in Retool sees their changes immediately reflected in Git. Code reviewers can view diffs of Retool app changes in pull requests alongside application code changes. This is the most seamless Git workflow for Retool — it eliminates the manual CLI export step entirely. Note that Source Code Sync is bidirectional: changes in Git (e.g., from a merged PR) are synced back to Retool. Be careful about the sync direction — if someone edits the JSON directly in GitHub without going through Retool, those changes will appear in Retool on the next sync.