Skip to main content

Build apps with the Retool CLI

Use the Retool CLI to build Retool apps from the command line.

The Retool CLI enables you to build, manage, and publish Retool-native React apps from the command line and with the help of your chosen code development agent harness, like Claude Code or Codex.

With this tool, you can write app code directly to your machine and check that it is valid Retool code. You can use the CLI independently, or pair it with a local development agent. Retool recommends using the CLI in combination with Source Control to manage contributors and app versions. For more information about how the Retool CLI works, refer to the concepts section.

note

Because code is written and validated locally, Retool CLI commands do not incur AI credit spend.

Prerequisites​

Before you install the Retool CLI, you need:

  • Edit permissions to create and build apps.
  • A terminal or agentic development environment that has access to a bash tool.
  • Node.js 22
  • git
  • pnpm

Install the Retool CLI​

The steps for installing the Retool CLI vary based on your preferred development environment.

note

Retool recommends pairing the CLI with the use of an agent harness. Retool provides a skill file that teaches the agent how to shape a Retool app.

Use the following instructions to install the Retool CLI on an Anthropic tool.

Claude Code

In a Claude Code session, complete the following steps:

  1. Install the CLI launcher: pnpm i -g @tryretool/cli.
  2. Authenticate with your Retool instance: retool auth login --host <example.retool.com>.
  3. Install the skill that teaches your coding agent how to shape a Retool app: retool skill install.

Refer to the Claude documentation for more information about installing plugins.

Claude

To install the Retool CLI for use in Claude (formerly Claude Chat and Claude Cowork), complete the following steps:

  1. Navigate to the latest release of the tryretool/agent-plugins repository. Click retool-claude-plugin.zip to download a zip file of the plugin.
  2. Navigate to Claude in the desktop app or browser.
  3. In the sidebar, click Customize, then Plugins.
  4. Click Add, and select Upload plugin from the dropdown.
  5. Upload the zip file that you downloaded in the first step.
  6. Open a new chat, and ask Claude to help you authenticate and set up the Retool CLI. 
    Help me set up the Retool CLI plugin. Connect to <example.retool.com>.
note

If your Retool instance uses a self-hosted or custom domain, an admin must add that domain to Claude's network egress allowlist before the plugin's sandbox can reach it. Configure this under Admin settings > Capabilities in Claude. This setting is managed at the organization level, so ask your Claude admin to add the domain if you don't have access to it yourself.

Refer to the Claude documentation for more information about installing plugins.

The Retool CLI inherits the same permissions as the authenticated user. For example, if you do not have Edit permissions for an app, you cannot edit that app using the Retool CLI.

Build apps​

Use the following recommended flow to create Retool apps.

  1. Start building a React app:
    • retool init creates a new app and scaffolds it locally. It needs an empty directory that is not already inside a git repository. Pass --force to override either check.
    • retool clone pulls an existing app to your local machine.
  2. Install dependencies from the root of the local app: pnpm install. Both init and clone print this as their next step, and validation fails without it.
  3. Validate Retool code.
    • retool start begins a validation loop that checks your code as you (or an agent) write it.
    • retool check performs a one-time check on the validity of your code.
  4. Send the app back to Retool with retool push, which starts a preview build. Add --wait to block until the build finishes and print the preview URL, or fetch it later with retool preview --wait. If any functions still need approval, push lists them along with the resource or workflow each one writes to.
  5. Publish your app with retool publish, which enforces permissions and requires function approvals.

At any point, run retool status to check the app's state, including pending function approvals and whether your branch is missing changes from main.

Use a private registry​

If your organization has configured private registries, retool init and retool clone copy the registry URLs and scope routing into the app's .npmrc. This configures the pnpm install command to use the same routing rules for package installation that are configured in your settings.

The CLI doesn't write credentials for your private registries, so you must add them yourself. If a registry requires authentication, add a line for it to your user-level ~/.npmrc. The CLI prints the exact lines to add:

  • npm.example.com/:_authToken=<your token> for registries that require a bearer token.
  • npm.example.com/:_auth=<base64 of username:password> for registries that require a username and password.

If your organization changes its registry settings, run retool pull to update the app's routing. The CLI prints the authentication lines again when the registries change.

Working on branches​

If the app's branch is updated on the server, such as when someone edits it in Retool or an agent thread pushes to it, run retool pull to bring your local app back in sync before you keep working.

To move your local work onto a different branch of the same app, such as one someone else created in the app builder, run retool checkout <branch>. The CLI refuses to switch if doing so would overwrite uncommitted local files, or if your local target branch holds commits the server doesn't have.

Refer to the Threads and branches for more information about branches.

Troubleshooting​

Use this section to diagnose and resolve common issues with the Retool CLI.

Why does the CLI fail with a certificate error?​

On a corporate network with an intercepting TLS proxy, Retool CLI commands can fail with a self-signed certificate error. Set the NODE_EXTRA_CA_CERTS environment variable to your corporate certificate to resolve this:

export NODE_EXTRA_CA_CERTS=/path/to/corporate.crt

Commands that use git, such as retool push and retool pull, also need the GIT_SSL_CAINFO environment variable set to the same certificate, in addition to NODE_EXTRA_CA_CERTS:

NODE_EXTRA_CA_CERTS=/path/to/corporate.crt GIT_SSL_CAINFO=/path/to/corporate.crt retool push