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.
• pnpm as a package manager.
• A terminal or agentic development environment that has access to a bash tool.

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.

Anthropic

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 Cowork

To install the Retool CLI for use in 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>.

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

OpenAI

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

Codex

In a Codex 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 ChatGPT documentation for more information about installing plugins.

ChatGPT Work

To install the Retool CLI on ChatGPT Work, complete the following steps:

1. Navigate to the latest release of the tryretool/agent-plugins repository. Click retool-openai-plugin.zip to download a zip file of the plugin.
2. Navigate to ChatGPT in the desktop app. In the dropdown on the top left, select ChatGPT.
3. In the sidebar, click Plugins.
4. Click Add, and select Create plugin from the dropdown.
5. In the plugin creator interface, upload the zip file that you downloaded in the first step, and submit the prompt. You may need to confirm tool calls as the agent sets up your plugin.
6. Navigate to Plugins > Personal, and select Retool. Install the plugin, and click Try now.
7. Ask ChatGPT to help you authenticate and set up the Retool CLI.

   Help me set up the Retool CLI plugin. Connect to <example.retool.com>.

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

note

Because ChatGPT in the browser does not have a bash tool, it is unable to use the Retool CLI.

Terminal

To install the CLI in other terminal-based tools, complete the following steps:

1. Install the CLI launcher: pnpm i -g @tryretool/cli
2. Authenticate with your Retool instance:
   • For most CLI interfaces, use: retool auth login --host <example.retool.com>.
   • If you're using a headless shell, such as a container, SSH session, or agent sandbox with no local browser, use: retool auth login --device --host <example.retool.com>. Open the printed URL on any machine, confirm the code matches, and approve.
3. The CLI includes a skill that teaches a coding agent how to shape a Retool app. You can install it in one of two ways:
   • Run retool skill install to install it for every detected agent.
   • If your agent can't read installed skill files, such as a sandboxed agent whose shell is on a different filesystem, run retool skill show retool-ready and pass the output into its context instead.

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.
5. Publish your app with retool publish, which enforces permissions and requires function approvals.

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.