How to Integrate Retool with Mercurial

The Retool CLI is the core tool for exporting and importing Retool app definitions from the command line. Install it globally using npm, then configure it to connect to your Retool instance. Run: npm install -g retool-cli After installation, configure the CLI to connect to your Retool instance. Generate a Retool API token from Retool Settings → Retool API → Create API token. Copy the token — you will use it to authenticate the CLI. Set up the CLI configuration by running: retool login --host https://your-retool-instance.com --token YOUR_API_TOKEN For Retool Cloud, the host is typically https://yourcompany.retool.com. For self-hosted Retool, use your internal Retool URL. Verify authentication by running: retool apps list — this should display a list of apps in your Retool instance. If it returns an error, check that the API token is correct and that the Retool instance URL does not have a trailing slash. Note that the Retool CLI's app definition export format is JSON. Each exported app creates a single .json file containing the complete app definition including all components, queries, and resource references. The file name typically matches the app's display name with spaces replaced by hyphens or underscores. These JSON files are what you will track in your Mercurial repository.

Establish a consistent directory structure in your Mercurial repository for Retool app definitions. A recommended structure separates app definitions by Retool environment (development, staging, production) or by team/function, depending on your organization's structure. If you are adding Retool app definitions to an existing monorepo, create a new directory at the repository root: retool-apps/ with subdirectories for each environment or team. If Retool apps will be the primary content of the repository, initialize a dedicated repository with the root as the app storage location. Create a directory structure such as: retool-apps/ apps/ — exported Retool app JSON files resources/ — documentation of resource configurations (NOT credentials) README.md — instructions for the export/import workflow Add a .hgignore file at the repository root to exclude any temporary files generated by the Retool CLI: syntax: glob *.tmp .retool-cache/ Create the initial commit with the directory structure: hg add retool-apps/ && hg commit -m 'chore: initialize Retool apps directory structure' For environment branching, create named branches for staging and production: hg branch staging && hg commit -m 'chore: create staging branch' then switch back to default (development) as the primary working branch. This three-branch structure mirrors common Mercurial promotion workflows used in enterprise environments.

1# .hgignore file for Retool app repository
2syntax: glob
3
4# Retool CLI cache files
5.retool-cache/
6*.retool.tmp
7
8# Editor temp files
9*.swp
10*.swo
11.DS_Store
12Thumbs.db
13
14# Node modules if any tooling is co-located
15node_modules/

With the CLI configured and the repository structured, establish the workflow for exporting app definitions and committing them to Mercurial after making changes in the Retool editor. After making changes to a Retool app in the browser editor, export the updated definition using the Retool CLI: retool apps export --app 'App Name' --output ./retool-apps/apps/app-name.json Verify the export by reviewing the generated JSON file. The file contains the full app definition — component tree, query configurations, transformers, event handlers, and layout information. Do not edit this file manually; always edit through the Retool editor and re-export. Check the Mercurial status to see what changed: hg status — the modified .json file appears as 'M' for modified (if it existed before) or '?' for a new untracked file. Stage and commit the change: hg add retool-apps/apps/app-name.json (only needed for new files) hg commit -m 'feat: add user search filter to Customer Support Panel' Write commit messages using conventional commit format (feat:, fix:, chore:) so the history is human-readable and integrates with any automated changelog generation in your CI pipeline. For teams exporting multiple apps simultaneously, the Retool CLI supports exporting all apps at once: retool apps export --all --output ./retool-apps/apps/ — this creates or updates a JSON file for each app. Review hg diff after this export to confirm only the intended apps changed before committing.

1# Shell script for consistent Retool app export and commit
2# Save as retool-apps/export-and-commit.sh
3#!/bin/sh
4
5APP_NAME="$1"
6COMMIT_MSG="$2"
7
8if [ -z "$APP_NAME" ] || [ -z "$COMMIT_MSG" ]; then
9  echo "Usage: ./export-and-commit.sh 'App Name' 'commit message'"
10  exit 1
11fi
12
13# Convert app name to filename (lowercase, spaces to hyphens)
14FILENAME=$(echo "$APP_NAME" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
15
16# Export the app
17retool apps export --app "$APP_NAME" --output "./apps/${FILENAME}.json"
18
19if [ $? -ne 0 ]; then
20  echo "Export failed — check Retool CLI authentication"
21  exit 1
22fi
23
24# Stage and commit
25hg add "./apps/${FILENAME}.json" 2>/dev/null || true
26hg commit -m "$COMMIT_MSG"
27echo "Exported and committed: $APP_NAME"

Establish the promotion workflow that moves Retool app definitions from development to staging to production using Mercurial named branches (or bookmarks). This mirrors the application deployment process your team already uses for code. The workflow: 1. Developer makes changes in the development Retool instance, exports the app definition, commits to the 'default' branch in Mercurial. 2. Code review is conducted on the JSON diff. Reviewers examine what component properties, queries, or layouts changed. 3. After approval, merge the change to the 'staging' branch: hg update staging && hg merge default && hg commit -m 'chore: promote customer-support-panel to staging' 4. The Retool CLI imports the staging branch version into the staging Retool instance: retool apps import --file ./apps/customer-support-panel.json --instance https://staging.retool.yourdomain.com 5. QA validation on the staging Retool instance. 6. If staging looks good, merge to 'production' branch and import into the production Retool instance. For the import step to work on multiple Retool instances, configure separate Retool CLI profiles for each environment, each with its own API token. Use environment variables to switch between profiles: RETOOL_API_TOKEN=staging_token retool apps import ... For complex multi-environment deployments with many apps, RapidDev can help architect a more robust Retool app lifecycle management solution that integrates with your existing Mercurial-based CI/CD infrastructure.

1# hg hook configuration for automated Retool import on branch promotion
2# Add to your .hg/hgrc file on the CI server
3
4[hooks]
5# Trigger after a push to the staging branch
6changegroup.retool-staging = python:hooks/retool_deploy.py:deploy_staging
7
8# Or use a simpler shell hook:
9# changegroup.retool-staging = sh hooks/deploy-to-staging.sh
10
11---
12# hooks/deploy-to-staging.sh
13#!/bin/sh
14BRANCH=$(hg branch)
15if [ "$BRANCH" = "staging" ]; then
16  echo "Deploying Retool apps to staging instance..."
17  RETOOL_API_TOKEN=$RETOOL_STAGING_TOKEN \
18    retool apps import --all --directory ./apps/ \
19    --instance https://staging.retool.yourdomain.com
20fi

One of the key benefits of version-controlling Retool app definitions is the ability to roll back to any previous version using Mercurial's revision history. This is particularly valuable when a Retool app change causes an incident and needs to be reverted immediately. To roll back a specific app to a previous version: 1. Identify the target revision: hg log -l 20 retool-apps/apps/broken-app.json — look for the last known-good commit hash or revision number in the output. 2. Extract the app definition from that revision: hg cat -r {revision_number} retool-apps/apps/broken-app.json > /tmp/rollback-app.json 3. Import the extracted definition into the Retool instance: retool apps import --file /tmp/rollback-app.json 4. Verify the rollback worked by checking the app in the Retool browser interface. 5. Commit the rollback in Mercurial: hg revert -r {target_revision} retool-apps/apps/broken-app.json && hg commit -m 'fix: roll back broken-app to revision {revision_number} (revert breaking change from {bad_revision})' Note that in Mercurial, unlike Git, you should NOT rewrite history using hg strip or hg amend on branches that have been pushed to a shared repository. Instead, always create a new forward commit that reverts the broken change — this preserves the full history including the failed attempt, which is valuable for post-incident review. Document this rollback procedure in your team's runbook alongside application rollback procedures so on-call engineers know the exact steps without needing to research them during an incident.

1#!/bin/sh
2# Retool app rollback script using Mercurial history
3# Usage: ./rollback-app.sh 'app-filename.json' {target_revision}
4
5APP_FILE="$1"
6TARGET_REV="$2"
7
8if [ -z "$APP_FILE" ] || [ -z "$TARGET_REV" ]; then
9  echo "Usage: ./rollback-app.sh apps/app-name.json {revision_number}"
10  echo "Run 'hg log -l 20 apps/app-name.json' to find target revision"
11  exit 1
12fi
13
14# Extract the app definition from the target revision
15hg cat -r $TARGET_REV $APP_FILE > /tmp/retool-rollback.json
16
17if [ $? -ne 0 ]; then
18  echo "Failed to extract revision $TARGET_REV from Mercurial"
19  exit 1
20fi
21
22# Import into Retool (uses RETOOL_API_TOKEN from environment)
23retool apps import --file /tmp/retool-rollback.json
24
25# Commit the rollback in Mercurial
26hg revert -r $TARGET_REV $APP_FILE
27hg commit -m "fix: rollback $APP_FILE to revision $TARGET_REV"
28
29echo "Rollback complete. App has been restored to revision $TARGET_REV."