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. 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.

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:

• Retool permissions to create and build apps,
• pnpm as a package manager.

Installation

Complete the following steps to install the Retool CLI. Open your preferred command line interface and run the following commands:

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.
   • For a non-interactive CI, sign in with an access token that has the react_apps:write scope: retool auth login --token <token> --host <example.retool.com>.
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.

note

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

Multiple Retool hosts

One CLI installation works with several 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, a --device code, or a --token, so a browser isn't required.

The following commands require a Retool host:

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

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

Outside a local app repository

When outside a local app repository, 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.

Inside a local app repository

When inside a local app repository, the CLI uses the host recorded in that repo'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 repository 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.

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.

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.

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 npm public 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 they use different versions.

MCP vs. CLI

In addition to the Retool CLI, Retool provides an MCP server. These tools are similar, in that they both allow app development through a local agent, but they have several key differences:

Characteristic	MCP	CLI
Engagement model	Agent-to-agent: Your local development agent passes your prompt to Retool's app building agent.	Agent-to-code: Your local development agent writes code directly.
Where code is written	In Retool's app building environment.	On your machine.
Who writes the code	Retool's app building agent.	You, or your local development agent.
Codebase context	Limited to what is exposed through MCP tools.	Complete context of your local codebase.
Best fit	Exploring resources and existing apps, sharing apps once published, managing organizations and users.	Writing or editing app code.

Command reference

The following reference lists all retool commands, grouped by function.

Behavioral notes

• Most commands work against a Retool host and need an active session.
• check, start, pull, push, preview, publish, and resource explore find the app by walking up from the current directory to the nearest .retool/app.json, so run them from inside the local app repository.
• Always pass --publish-behavior when you use --release. Using --release on its own fails.

Authentication

Sign in to a Retool host, choose which host commands target, and manage your session.

Command	Description	Options
auth login	Sign in to a Retool host. Opens a browser to authenticate by default.	--host <url> (Retool host) --device (use a device code for a headless shell; polls in this process by default) --no-wait (with --device, start authorization, save its state, and exit without polling) --resume (with --device, resume polling saved authorization state for this host) --wait <secs> (with --device --resume, bound polling in seconds; default 60, 0 performs a single token request) --json (with --device, print one machine-readable start or resume result) --token <token> (store an access token with react_apps:write for CI; default: $RETOOL_TOKEN)
auth status	Show the session for one host, with token scopes and expiry. With no --host, and outside a local app repository, lists every host you're signed in to and marks the one commands target by default.	--host <url>
auth use <url>	Set the default Retool host for commands that get no --host. Does not sign you in or out.
auth logout	Sign out and remove stored credentials for a host.	--host <url>
whoami	Show the signed-in user's cached name, email, and host.	--host <url> --json (machine-readable output)

App lifecycle

List, scaffold, validate, preview, and publish apps.

Command	Description	Options
apps	List every app and classic app in your organization, with its name, UUID, and folder ID. Use it to find the app UUID that clone requires. clone can only access apps, not classic apps.	--host <url> --json (machine-readable output)
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. Requires an empty directory outside any git repository.	--dir <path> (directory to scaffold into; mutually exclusive with [dir]) --host <url> --force (overwrite existing files, and allow scaffolding inside a git repo) --name <name> (app name)
clone <app>	Download an existing app to a local directory. <app> is an app UUID or editor URL.	--branch <ref> (existing branch to check out; default: create a new one) --dir <path> (target directory; default: the app UUID) --host <url>
check	Validate the app once and report any errors. Regenerates the use<Fn> hooks first. Makes no network call.	--json (machine-readable output) --skip-build (skip the production builds; static validation and tsc still run)
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.	--json (machine-readable output on each run)
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.	--json (machine-readable output)
push	Validate the app locally, then push your changes through the gate and start a preview build. Local validation failures block the push before anything is committed.	-m, --message <message> (commit message shown in the app's Change History; default: retool push) --wait (wait until the preview build is ready or failed) --timeout <seconds> (max seconds to wait; requires --wait; default 180) --json
preview	Return the current preview URL, or the build state, without pushing again.	--wait (wait until the preview build is ready or failed) --timeout <seconds> (default 180) --json
publish	Publish the app to a live URL.	--identifier <slug> (public URL identifier; required on first publish) --tag <tag> (publish tag) --release <type> (major|minor|patch) --publish-behavior <behavior> (latest|current|previous; required with --release) --folder <id> (folder to move the app into) --approve-functions (approve pending functions before publishing) --json

Resources

Inspect the resources your app code can call, and create new ones.

Command	Description	Options
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. The CLI classifies the code locally and runs read-only code by default.	--environment <name> (default: org default) --rows <n> (max rows for an array result; default 100) --allow-mutative (run code classified as mutative) --json
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.	--type <type> (resource type, required) --list-types (print the built-in types and exit) --name <name> (display name) --config <path> (JSON file of connection fields, or - to read them from stdin) --host <url> --json

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.

Command	Description	Options
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.	--agent <name> (claude-code|codex|cursor; default: all detected agents) --dir <path> (custom skills directory)
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.

Command	Description	Options
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.	-d, --description <text> (the feedback, 4000 characters max) --host <url> --json

Updates

Keep the CLI core in step with your Retool host.

Command	Description	Options
update	Install the CLI version your host recommends. The new version takes effect on your next command.	--host <url> --check-only (report the recommended version without installing) --quiet (print nothing)

Global flags

These flags apply to every command.

Flag	Description
--debug	Log network requests for troubleshooting. Never logs secrets. Also enabled by setting RETOOL_DEBUG=1.
--version	Print the CLI version.

--host is not a global flag. Only auth login, auth status, auth logout, whoami, apps, clone, init, resource create, feedback, and update accept it. Refer to Multiple Retool hosts for how the other commands pick a host.

Environment variables

You can set environment variables to include flags and respective values with every command automatically. This is useful for using the CLI programmatically, such as CI development and other non-interactive contexts.

Variable	Description
RETOOL_HOST	Default host for commands that get no --host flag. Refer to Multiple Retool hosts.
RETOOL_TOKEN	Default access token for auth login --token.
RETOOL_DEBUG	Set to 1 to log network requests, the same as --debug.
RETOOL_CREDENTIALS_PATH	Path to the credential store where signed-in tokens are cached (default: ~/.retool/credentials.json). Set it to a writable path when $HOME is read-only, such as in CI.