Intro to the Retool CLI

Learn about how the Retool CLI works.

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.

This page includes information about how the Retool CLI works and the mechanisms it uses to stay up to date and to authenticate with multiple instances. Refer to the installation guide to learn how to get started.

note

Retool also provides an MCP server for app development and organization management. Refer to Build from anywhere to learn more about the difference between these tools, and when to use each.

Use cases

Common use cases for the Retool CLI include:

• Build a new app from scratch.
• Edit an existing app.
• Import a React app from another tool.
• Convert a classic app to a React-based app.

The following video provides a demo of importing a React app from another tool using the Retool CLI:

App development workflow

The Retool CLI is designed to work with common developer workflows:

1. Initialize a new app, or clone an existing one.
2. Develop your app. In the meantime, run validation that your app is valid code.
3. When you're ready, push your changes and review a preview URL.
4. Publish your changes.

You can use the CLI commands to execute this workflow manually, or you can utilize the help of a development agent, which leverage the skills packaged with the agent.

Skills

Your installation of the Retool CLI includes retool-ready, a skill that teaches your agent how to write Retool apps. It includes information about file structure, the required data patterns, how to perform Retool's strict typechecks, and other key information for building valid React apps.

If you installed the CLI through the Claude or OpenAI plugin, it also includes retool-cli, a separate skill scoped to that plugin's cloud sandbox. It bootstraps the CLI there, since the sandbox has no install step of your own, and isn't relevant if you installed the CLI yourself in a terminal.

By using an agent that has access to these skills, you don't need to remember or reference the full list of CLI commands.

Running retool init or retool clone prints a line telling your agent to run retool skill show retool-ready, so an agent that starts from either command can find the skill on its own. You only need to run retool skill install when you want your agent to know about the CLI before it runs retool init or retool clone for the first time, such as starting a fresh agent session in a folder where neither command has run yet. The command writes a small retool-ready pointer skill into each detected agent's skills directory (for example, ~/.claude/skills, ~/.codex/skills, or ~/.cursor/skills), and the CLI refreshes that file automatically when you upgrade.

AI credits

During the public beta, using the Retool CLI does not incur any Retool AI credit spend. All app building is done locally, by yourself or by another development agent. Any token spend occurs only with your chosen development agent.

Versions

The Retool CLI has two components: the launcher and the core, which are versioned independently. You install a particular version of the launcher from the public npm registry. When you authenticate the installed Retool CLI with a particular instance, Retool updates the core to correspond with the version of Retool that your instance runs, whether that is Retool Cloud or a specific self-hosted release.

This separation ensures that you get the CLI functionality that is associated with your Retool version, and makes it possible to install one version of the Retool CLI and use it on several different instances, even if each of those instances use different versions.

Authenticating multiple Retool instances

One CLI installation works with several authenticated Retool instances, each referred to as a host. Most commands work against a Retool host and need an active session. You create one with retool auth login, using browser OAuth, or a --device code, so a browser isn't required.

Commands that require a Retool host

• apps
• start
• clone
• init
• pull
• checkout
• push
• preview
• publish
• feedback
• resource
• whoami

Hosts are managed slightly differently depending on where you are calling commands.

Inside a local app directory

When inside a local app directory, the CLI uses the host recorded in that directory's .retool/app.json file:

• auth login, auth status, auth logout, whoami, apps, resource create, and feedback target it, and reject a --host that names a different host.
• The commands that act on the app itself, such as check and push, always use it and accept no --host at all.
• retool auth use still changes the global default, and warns you that commands run in the local app directory keep targeting the app's host.

When a command picks a host implicitly, it prints the host and where it came from: retool: using https://example.retool.com (your default host). If no host resolves, the command exits and tells you to pass --host, set RETOOL_HOST, or choose a default.

Outside a local app directory

When outside a local app directory, every command picks its host in this order:

1. The --host flag.
2. The RETOOL_HOST environment variable.
3. Your saved default host.

note

Refer to the Authentication section for information on updating the default host.

retool auth login, retool auth use, retool init, and retool clone all set the saved default. To switch the default without signing in or out, run retool auth use <example.retool.com>. To see every host you're signed in to, with the default marked, run retool auth status.

Edit protected apps

The Retool CLI clones each app from Retool's internal repository, the same one that the app builder uses to track changes and branches. Each app has its own repository, so the local app directory that you use with the CLI is scoped to a single app.

This repository is independent from your organization's Source Control configuration, which uses an external repository and holds every protected app together as a monorepo. For an app that isn't protected, the CLI only works with Retool's internal repository. For a protected app, the CLI makes edits in Retool's internal repository, but also keeps the matching branch in your external repository in sync.

note

The CLI does not support protecting an app. You must first publish your app, and then protect it. The CLI recognizes the change the next time you run a command.

To work with a protected app using the CLI, use the following flow:

1. Make your edits locally, then run retool push. The command pulls any external changes into its branch first, applies your changes, then pushes the result to the matching feature branch in both Retool's internal repository and your configured external repository, using the same mechanism as syncing a branch from the app builder.
2. Run retool publish, which prints a link to open a pull request. Retool doesn't open or merge the pull request for you. This step mirrors the process of publishing an app.
3. Open and merge the pull request in your source control manager. Retool imports the new main branch and publishes your app. Pass --wait to retool publish to poll until the merge completes and print the live URL when it deploys.
4. Run git pull in your external source control repository to see the change there.

retool pull also works in the other direction: it brings changes made directly on the external feature branch into your local app, and retool pull --from main brings in a newer published main branch. If main has changes that your branch doesn't contain, retool pull, retool start, and retool publish all warn you and point you to retool pull --from main.

Generated types

The CLI downloads TypeScript declarations for your organization's resources and workflows so that local validation (retool check, retool start) can resolve references to them the same way the app builder does. These declarations refresh automatically when you run retool clone or retool pull. Run retool status to check whether your local declarations are stale.