Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.

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.

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 two skills, which agents use to help you work with the CLI to develop and validate Retool apps:

  • retool-cli teaches your agent how to run the CLI. It includes information about authentication, validating the CLI installation, and troubleshooting.
  • retool-ready 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.

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

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.