Retool CLI reference

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.

note

Most commands need an active, authenticated session on a Retool instance. You can work in one or more Retool instances at a time.

Authentication

`retool auth login`

Options

--host <url>

The Retool instance to sign in to.

Type	string
Example	`retool auth login --host example.retool.com`

--device

Authenticate with a device code for a headless shell, such as a container, SSH session, or agent sandbox with no local browser. Polls in this process by default.

Type	boolean
Example	`retool auth login --device --host example.retool.com`

--no-wait

With --device, start authorization, save its state, and exit without polling.

Type	boolean
Example	`retool auth login --device --no-wait --host example.retool.com`

--resume

With --device, resume polling saved authorization state for this instance.

Type	boolean
Example	`retool auth login --device --resume --host example.retool.com`

--wait <secs>

With --device --resume, bound polling in seconds. Set to 0 to perform a single token request.

Type	number
Default	60
Example	`retool auth login --device --resume --wait 120 --host example.retool.com`

--json

With --device, print one machine-readable start or resume result.

Type	boolean
Example	`retool auth login --device --json --host example.retool.com`

--token <token>

Store an access token with the react_apps:write scope for use in CI.

Type	string
Default	$RETOOL_TOKEN
Example	`retool auth login --token retool_a1b2c3d4e5f6g7h8 --host example.retool.com`

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

Options

--host <url>

The Retool instance to show session details for.

Type	string
Example	`retool auth status --host example.retool.com`

--json

Print machine-readable output. Emits the same payload in every context: scopes, expiry, and whether the token has expired.

Type	boolean
Example	`retool auth status --json`

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

Options

--host <url>

The Retool instance to sign out of.

Type	string
Example	`retool auth logout --host example.retool.com`

`retool whoami`

Show the signed-in user's cached name, email, and instance.

Options

--host <url>

The Retool instance to report the signed-in user for.

Type	string
Example	`retool whoami --host example.retool.com`

--json

Print machine-readable output.

Type	boolean
Example	`retool whoami --json`

App lifecycle

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

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

Options

--host <url>

The Retool instance to list apps from.

Type	string
Example	`retool apps --host example.retool.com`

--json

Print machine-readable output.

Type	boolean
Example	`retool apps --json`

`retool branches <app>`

List the branches for an app. <app> is an app UUID or editor URL. Pass a branch name from this list to clone --branch.

Options

--host <url>

The Retool instance that contains the app.

Type	string
Example	`retool branches f47ac10b-58cc-4372-a567-0e02b2c3d479 --host example.retool.com`

--json

Print machine-readable output.

Type	boolean
Example	`retool branches f47ac10b-58cc-4372-a567-0e02b2c3d479 --json`

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

Options

--dir <path>

The directory to scaffold into. Mutually exclusive with the [dir] argument.

Type	string
Default	The current directory.
Example	`retool init --dir ./my-app`

--host <url>

The Retool instance to create the app on.

Type	string
Example	`retool init my-app --host example.retool.com`

--force

Overwrite existing files, and allow scaffolding inside a git repository.

Type	boolean
Example	`retool init my-app --force`

--name <name>

The name for the new app. With no [dir] argument, the CLI prompts you in an interactive terminal, or falls back to the directory name.

Type	string
Default	The PascalCased `[dir]` argument.
Example	`retool init --dir ./my-app --name "My App"`

--json

Print machine-readable output: the app UUID, name, branch, instance, and directory, or why the command stopped.

Type	boolean
Example	`retool init my-app --json`

`retool clone <app>`

Download an existing app to a local directory. <app> is an app UUID or editor URL.

Options

--branch <ref>

An existing branch to check out. Run retool branches <app> to see the names.

Type	string
Default	Creates a new branch.
Example	`retool clone f47ac10b-58cc-4372-a567-0e02b2c3d479 --branch jane/update-user-management`

--dir <path>

The target directory to clone into.

Type	string
Default	The app UUID.
Example	`retool clone f47ac10b-58cc-4372-a567-0e02b2c3d479 --dir ./my-app`

--host <url>

The Retool instance to clone the app from.

Type	string
Example	`retool clone f47ac10b-58cc-4372-a567-0e02b2c3d479 --host example.retool.com`

`retool check`

Validate the app once and report any errors. Regenerates the use<Fn> hooks first. Makes no network call.

note

Run this command from inside the local app directory.

Options

--json

Print machine-readable output.

Type	boolean
Example	`retool check --json`

--skip-build

Skip the production builds. Static validation and tsc still run.

Type	boolean
Example	`retool check --skip-build`

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

note

Run this command from inside the local app directory.

Options

--json

Print machine-readable output on each run.

Type	boolean
Example	`retool start --json`

`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 your app is protected, this command also fast-forwards your changes on the branch of your external source control repository.

note

Run this command from inside the local app directory.

Options

--json

Print machine-readable output.

Type	boolean
Example	`retool pull --json`

`retool checkout <ref>`

Switch the current local app to an existing app branch. Refuses a switch that would overwrite local files, or a local target branch that holds commits absent from the server.

note

Run this command from inside the local app directory.

Options

--json

Print a machine-readable switch result and refresh status.

Type	boolean
Example	`retool checkout my-branch --json`

`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.
If your app is protected this command also applies your changes to the branch in your external source control repository.

note

Run this command from inside the local app directory.

Options

-m, --message <message>

The commit message shown in the app's Change History.

Type	string
Default	retool push
Example	`retool push --message "Add customer table"`

--wait

Wait until the preview build is ready or failed.

Type	boolean
Example	`retool push --wait`

--timeout <seconds>

The maximum number of seconds to wait. Requires --wait.

Type	number
Default	180
Example	`retool push --wait --timeout 300`

--json

Print machine-readable output.

Type	boolean
Example	`retool push --json`

`retool preview`

Return the current preview URL, or the build state, without pushing again.

note

Run this command from inside the local app directory.

Options

--wait

Wait until the preview build is ready or failed.

Type	boolean
Example	`retool preview --wait`

--timeout <seconds>

The maximum number of seconds to wait. Requires --wait.

Type	number
Default	180
Example	`retool preview --wait --timeout 300`

--json

Print machine-readable output.

Type	boolean
Example	`retool preview --json`

`retool publish`

Publish the app to a live URL. Blocks and lists any functions that still need approval.
If your app is protected, this command opens a pull request in your source control manager. Your changes are not published until the pull request is merged.

note

Run this command from inside the local app directory.

Options

--identifier <slug>

The public URL identifier for the app. Required on first publish.

Type	string
Example	`retool publish --identifier my-app`

--tag <tag>

The publish tag to apply.

Type	string
Example	`retool publish --tag production`

--release <type>

The release type to publish. One of major, minor, or patch. Always pass --publish-behavior when you use --release.

Type	string
Example	`retool publish --release minor --publish-behavior latest`

--publish-behavior <behavior>

Which version end users receive. One of latest, current, or previous. Always pass this option when you use --release; passing --release on its own fails.

Type	string
Example	`retool publish --release patch --publish-behavior current`

--folder <id>

The folder to move the app into. When omitted, an app still in Drafts moves to your organization's root folder.

Type	number
Example	`retool publish --folder 128`

--approve-functions

Approve every pending function before publishing. You need edit access to every resource and workflow those functions use. Cannot be combined with --approve-function.

Type	boolean
Example	`retool publish --approve-functions`

--approve-function <path>

Approve one pending function by its exact path. Repeat the flag to approve more than one. Publish stays blocked while any other function is still pending. You need edit access to every resource and workflow the function uses. Cannot be combined with --approve-functions.

Type	string
Example	`retool publish --approve-function queries/getUsers`

--wait

For a protected app, wait for the pull request to merge and for its source control deployment to publish the app. A direct publish already waits.

Type	boolean
Example	`retool publish --wait`

--timeout <seconds>

The maximum number of seconds to wait. Requires --wait.

Type	number
Default	180
Example	`retool publish --wait --timeout 300`

--json

Print machine-readable output.

Type	boolean
Example	`retool publish --json`

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. The CLI classifies the code locally and runs read-only code by default.

note

Run this command from inside the local app directory.

Options

--environment <name>

The resource environment to run against.

Type	string
Default	The organization default environment.
Example	`retool resource explore --environment staging`

--rows <n>

The maximum number of rows to return for an array result.

Type	number
Default	100
Example	`retool resource explore --rows 25`

--allow-mutative

Run code classified as mutative.

Type	boolean
Example	`retool resource explore --allow-mutative`

--json

Print machine-readable output.

Type	boolean
Example	`retool resource explore --json`

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

Options

--type <type>

The resource type to create. Required.

Type	string
Example	`retool resource create --type postgresql`

--list-types

Print the built-in resource types and exit.

Type	boolean
Example	`retool resource create --list-types`

--name <name>

The display name for the resource.

Type	string
Example	`retool resource create --type postgresql --name "Prod DB"`

--config <path>

A JSON file of connection fields. Pass - to read them from stdin.

Type	string
Example	`retool resource create --type postgresql --config ./db.json`

--host <url>

The Retool instance to create the resource on.

Type	string
Example	`retool resource create --type postgresql --host example.retool.com`

--json

Print machine-readable output.

Type	boolean
Example	`retool resource create --type postgresql --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.

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

Options

--agent <name>

The agent to install the skill for. One of claude-code, codex, or cursor.

Type	string
Default	All detected agents.
Example	`retool skill install retool-ready --agent claude-code`

--dir <path>

A custom skills directory to install into.

Type	string
Example	`retool skill install retool-ready --dir ./.claude/skills`

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

Options

-d, --description <text>

The feedback text. 4000 characters maximum.

Type	string
Example	`retool feedback --description "push --wait sometimes hangs"`

--host <url>

The Retool instance to send feedback for.

Type	string
Example	`retool feedback --description "clone fails on large apps" --host example.retool.com`

--json

Print machine-readable output.

Type	boolean
Example	`retool feedback --description "clone fails on large apps" --json`

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.

Options

--host <url>

The Retool instance to check the recommended version against.

Type	string
Example	`retool update --host example.retool.com`

--check-only

Report the recommended version without installing it.

Type	boolean
Example	`retool update --check-only`

--quiet

Print nothing.

Type	boolean
Example	`retool update --quiet`

Global flags

These flags apply to every command. --host is not a global flag; only a subset of commands accept it.

--debug

Log network requests for troubleshooting. Never logs secrets. Also enabled by setting RETOOL_DEBUG=1.

Type	boolean
Example	`retool push --debug`

--version

Print the CLI version.

Type	boolean
Example	`retool --version`

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.

RETOOL_HOST

Default instance for commands that get no --host flag.

Type	string
Example	`export RETOOL_HOST=example.retool.com`

RETOOL_TOKEN

Default access token for auth login --token.

Type	string
Example	`export RETOOL_TOKEN=retool_a1b2c3d4e5f6g7h8`

RETOOL_DEBUG

Set to 1 to log network requests, the same as --debug.

Type	string
Example	`export RETOOL_DEBUG=1`

RETOOL_CREDENTIALS_PATH

Path to the credential store where signed-in tokens are cached. Set it to a writable path when $HOME is read-only, such as in CI.

Type	string
Default	~/.retool/credentials.json
Example	`export RETOOL_CREDENTIALS_PATH=/tmp/retool/credentials.json`

Authentication​

retool auth login​

retool auth status​

retool auth use <url>​

retool auth logout​

retool whoami​

App lifecycle​

retool apps​

retool branches <app>​

retool init [dir]​

retool clone <app>​

retool check​

retool start​

retool pull​

retool checkout <ref>​

retool push​

retool preview​

retool publish​

Resources​

retool resource explore​

retool resource create​

Skills​

retool skill install retool-ready​

retool skill show retool-ready​

Feedback​

retool feedback​

Updates​

retool update​

Global flags​

Environment variables​

Authentication

`retool auth login`

`retool auth status`

`retool auth use <url>`

`retool auth logout`

`retool whoami`

App lifecycle

`retool apps`

`retool branches <app>`

`retool init [dir]`

`retool clone <app>`

`retool check`

`retool start`

`retool pull`

`retool checkout <ref>`

`retool push`

`retool preview`

`retool publish`

Resources

`retool resource explore`

`retool resource create`

Skills

`retool skill install retool-ready`

`retool skill show retool-ready`

Feedback

`retool feedback`

Updates

`retool update`

Global flags

Environment variables