Retool CLI reference
Use the Retool CLI to build Retool apps from the command line.
This reference lists every command available in the Retool CLI, grouped by function. To install the CLI and learn the recommended build flow, refer to the installation guide.
Most commands need an active, authenticated session on a Retool instance. You can work in one or more Retool instances at a time.
Authentication
Sign in to a Retool instance, choose which instance commands target, and manage your session.
retool auth signup <email>
Create a free Retool account for an email address.
retool auth login
Sign in to a Retool instance. Opens a browser to authenticate by default.
retool auth status
Show the session for one instance, with token scopes and expiry. With no --host, and outside a local app directory, lists every instance you're signed in to and marks the one commands target by default.
retool auth use <url>
Set the default Retool instance for commands that get no --host. Does not sign you in or out.
retool auth logout
Sign out and remove stored credentials for an instance.
retool whoami
Show the signed-in user's cached name, email, and instance.
App lifecycle
List, scaffold, validate, preview, and publish apps.
retool apps list
List every app and classic app in your organization, with its name, UUID, and folder ID. retool apps on its own runs this command. Use it to find the app that apps clone requires. apps clone can only access apps, not classic apps. Apps in the Trash are omitted by default.
retool branch
List an app's branches. The branch your local app is on is marked with *. This command does not support creating, renaming, or deleting a branch.
retool apps init [dir]
Provision a new Retool app and scaffold it locally, then pull its resource types. With [dir], creates that directory and names the app after it, PascalCased. In an empty directory, apps init scaffolds in place. If the current directory already has files, it creates a subdirectory named after the app instead, which needs --name when you aren't at an interactive terminal. It refuses to run inside a git repository, or to overwrite existing files, unless you pass --force. retool init is an alias.
retool gallery list
List the App Gallery apps that your instance can use to start a new app, as an id and name. Pass an id to init --gallery <id>. The instance owns this catalog, so a newer app can appear here without a CLI update.
retool apps clone <app> [dir]
Download an existing app to a local directory. <app> is an app UUID, an editor URL, the exact app name, or the app's public URL slug. A value that matches more than one app lists the candidates. Without [dir] or --dir, the CLI names the directory after the app's public URL slug, or its name in slug form when the app has never been published. retool clone is an alias.
retool apps protect
Protect the app in the current local directory. The command pushes a branch that adds the app to your protected repository and prints the pull request to merge. Once that pull request merges and the next source control deployment runs, retool publish creates a pull request. Requires source control to be configured for your organization.
Run this command from inside the local app directory.
retool check
Validate the app once and report any errors. Regenerates the use<Fn> hooks first. Validation runs offline; an authenticated local app may also send one best-effort analytics request, which doesn't affect the result.
Run this command from inside the local app directory.
retool start
Pull resource types for a linked app, then watch the local app and re-validate on every save. Runs until you stop it with Ctrl-C. If the local branch doesn't contain the latest commit on main, it prints a warning and suggests retool pull --from main or retool status.
Run this command from inside the local app directory.
retool status
Report the app's server state: local and server branch commits, whether the branch contains main, preview state, pending function approvals, and whether generated backend types, including resource and workflow declarations, are stale.
Run this command from inside the local app directory.
retool pull
Fast-forward the local app to its branch on the server, then refresh its resource types and generated hooks. If the two have diverged, pull stops and prints the git command to run. If main has changes that your branch doesn't contain, pull prints a warning telling you to run retool pull --from main to merge them in.
If your app is protected, this command also fast-forwards your changes on the branch of your external source control repository.
Run this command from inside the local app directory.
retool checkout <ref>
Switch the current local app to an existing app branch, or create one with --create. Refuses a switch that would overwrite local files, or a local target branch that holds commits absent from the server.
Run this command from inside the local app directory.
retool push
Validate the app locally, then push your changes to Retool and start a preview build. Local validation failures block the push before anything is committed. After a successful push, push reports any functions that still need approval, along with the resource or workflow each one writes to. This doesn't block the push, but the preview build runs those functions without approval, and retool publish still requires approval before they can run live.
If your app is protected this command also applies your changes to the branch in your external source control repository.
In a local package directory, push works differently. Refer to Shared commands in a package directory.
Run this command from inside the local app directory.
retool preview
Return the current preview URL, or the build state, without pushing again.
Run this command from inside the local app directory.
retool publish
Publish the app to a live URL. Blocks and lists any functions that still need approval. If main has changes that your branch doesn't contain, publish stops and tells you to run retool pull --from main first.
If your app is protected, this command prints a link to open a pull request in your source control manager. It doesn't open or merge the pull request for you, and your changes are not published until you merge it.
In a local package directory, publish works differently. Refer to Shared commands in a package directory.
Run this command from inside the local app directory.
Classic apps
Export a classic app's Toolscript so you, or a local coding agent, can rebuild it as a React-based app.
retool classic export <app>
Download a classic app's Toolscript bundle into a directory. <app> is an app UUID, an editor URL, or the exact app name (case-insensitive; an ambiguous or unknown name lists the candidates). Requires edit access to the classic app, and refuses an app that's already a Retool-native React app.
Resources
Inspect the resources your app code can call, and create new ones.
retool resource explore
Read backend TypeScript from stdin and run it against your organization's resources, so you can inspect their real data and shape before writing code against them. Works with or without a local app. Inside a local app directory, the code runs as that app and can import from its backend/ directory. Outside one, it runs against the organization and can't import other files. The CLI classifies the code locally and runs read-only code by default. A refused run exits 1 with empty stdout and the reason on stderr.
retool resource types
Download the TypeScript declarations for your organization's resources into backend/resources/, so code can call them by name and check can resolve them. clone, pull, and start refresh them automatically.
retool resource create
Create a resource for your organization. With no credentials, Retool creates the resource and prints the URL where you finish configuring it. Resources are org-global, so this command needs no local app checked out.
Packages
Reach out to your account manager for access to packages, which are in private beta for Enterprise organizations. Retool must enable both access to packages and package creation via the CLI.
List the packages your organization publishes, create or clone a package to edit, and test a function that uses one. Packages are stored as independent directories, separate from any app.
retool packages list
List published packages. Each row shows the package name to install (@retool.org.<scope>/<name>), its latest published version, whether Source Control protects it, how many functions it exports, and its display name. retool packages on its own also lists packages.
retool packages init [name]
Create a package on your Retool instance and scaffold a local package directory for it, then pull its resource types. [name] is the display name. Retool derives the package name (@retool.org.<scope>/<name>) from it and refuses a name that is already taken. With no [name], the CLI prompts you in an interactive terminal, or falls back to the directory name. The directory starts with one function, backend/hello.ts. packages init refuses to scaffold into a directory that has files, or inside a git repository, unless you pass --force.
retool packages clone <ref> [dir]
Download a package that you can edit to a local package directory. <ref> is the package ID, the full package name (@retool.org.<scope>/<name>), the name after the slash, or the display name. The target directory must be empty or not exist yet.
retool packages run <script>
Run a shared function from an app directory or from a package directory. <script> is a .ts file under backend/ that default-exports an async function. The package must be installed first. You must approve a function run if it is mutative.
Run this command from inside the local app directory.
Shared commands in a package directory
retool packages init and retool packages clone create a local package directory. The following commands also run in a local package directory, where they act on the package instead of an app.
| Command | Behavior in a local package directory |
|---|---|
| retool check | Validates the package with the rules and generates no hooks. A package must include only functions in backend/ and its root package.json. After a push, check also lists the functions that need approval. |
| retool start | Pulls resource types, then validates with the package rules on every save. |
| retool status | Reports the state of the package branch and any pending function approvals. |
| retool pull | Fast-forwards the local package directory to its branch on the server. --from <ref> merges another branch of the package. |
| retool branch and retool checkout <ref> | List, switch, and create branches of the package. |
| retool push | Validates the package, pushes its branch, and lists the functions that still need approval. Packages have no preview build, so push refuses --wait and --timeout. |
| retool publish | Publishes a version of the package. --release is required and takes patch, minor, or major. Retool sets the version number. publish refuses --identifier, --tag, --publish-behavior, and --folder, and stops while any function needs approval. Publishing protected packages is not supported. |
| retool resource explore and retool resource types | Run against the package instead of an app. |
Skills
Give your coding agent retool-ready, the skill that describes the shape a Retool app has to take. It is the only skill the CLI ships, and the name is optional in both commands.
retool skill install retool-ready
Install the skill into each agent's skills directory. The installed file points at skill show, so it stays current as the CLI updates.
retool skill show retool-ready
Print the skill to stdout. Use it for an agent that can't read an installed skill file.
Feedback
Report a CLI bug or a rough edge.
retool feedback
Send feedback about the CLI. Attaches your CLI and platform versions, plus the app and branch identifiers when you run it in a local app. It sends no logs or file contents.
Updates
Keep the CLI core in step with your Retool instance.
retool update
Install the CLI version your instance recommends. The new version takes effect on your next command.
Global flags
These flags apply to every command. --host is not a global flag; only a subset of commands accept it.
Environment variables
Set environment variables to include flags and their values with every command automatically. This is useful for using the CLI programmatically, such as in CI and other non-interactive contexts.