React Builder CLI Reference
This page lists the ToolJet CLI commands, flags, environment variables and files for React Builder apps. For a walkthrough, see Build Locally.
Install​
Install the CLI from the ToolJet instance:
npm i -g https://tooljet.example.com/api/code-mode/cli/tooljet-cli.tgz
Replace https://tooljet.example.com with the instance's address. Each instance serves the CLI it was built with, so the CLI's React Builder commands match the instance. The Open locally view in the editor shows this command with the instance's address filled in.
Run this even if tooljet is already installed. It replaces any older tooljet installed from npm. Older versions don't have the auth, app and skill commands.
If the instance doesn't serve the CLI, install @tooljet/cli@beta from npm. The CLI needs Node.js 18 or later.
Sign In​
The CLI signs in with a personal access token. Browser sign-in creates the token automatically. A token can also be pasted, or set in the environment for CI.
Sign In Through the Browser​
tooljet auth login --url https://tooljet.example.com
- The CLI prints an address and an eight-letter code, such as
BCDF-GHJK, and opens the address in the browser. Add--no-browserto stop it from opening the browser. - On the Sign in the ToolJet CLI page, type the code from the terminal and click Continue. The browser must be signed in to ToolJet.
- The page shows what is asking to act on the user's behalf, and in which workspace. Approve only a sign-in that was just started with
tooljet auth login. Click Approve. - Go back to the terminal. The CLI finishes signing in by itself and prints
✓ Signed in to <instance> as <email>.
The code works for 10 minutes. If it expires, run tooljet auth login again.
The CLI gets a personal access token for the workspace open in the browser. It stores the token in ~/.tooljet/credentials.json, readable only by the current user, and never prints it. The token doesn't refresh: when it expires, run tooljet auth login again. For how long it lasts, see tooljet auth login.
To revoke the token, go to Workspace settings > Personal access token and click Revoke next to it. The token is named after the computer and the sign-in date, for example tooljet CLI on my-laptop (2026-11-13).
Sign In to More Than One Instance​
The CLI keeps one login per instance. A project always uses the login for the instance it was cloned from, so the CLI can be signed in to several instances, with projects from each.
The first login becomes the default, used outside a project. A login to another instance doesn't replace the default unless --default is added:
tooljet auth login --url https://staging.tooljet.example.com --default
To run a command with another instance's login, add --instance <url> to it. See Choose the Instance and Token.
Sign In With a Personal Access Token​
If the instance doesn't support browser sign-in, or to paste a token instead, use tooljet login. It asks for the ToolJet origin URL and a personal access token. To create a token, see Create a Personal Access Token.
Sign In From CI​
In CI, set both environment variables instead of signing in:
export TOOLJET_URL=https://tooljet.example.com
export TOOLJET_PAT=<personal access token>
TOOLJET_URL and TOOLJET_PAT override any stored login. Set both, or neither. --url and --token can also be passed on a command.
Commands​
Command | Run From | What It Does |
|---|---|---|
tooljet auth login --url <url> | Anywhere | Signs in through the browser. |
tooljet login | Anywhere | Signs in with a pasted personal access token. |
tooljet app init <dir> | Anywhere | Creates a new React Builder project. |
tooljet app clone <appId> [dir] | Anywhere | Creates a project linked to an existing app. |
tooljet app install | Project folder | Installs dependencies without install scripts. |
tooljet app pull | Project folder | Reads the app's queries, tables and pages, and writes tooljet.gen.ts. |
tooljet app check | Project folder | Checks the code against the app, and runs the security scan. |
tooljet app dev | Project folder | Builds on every save and shows the app live in the editor. |
tooljet app publish | Project folder | Saves the draft as a version. |
tooljet app checkout [version] | Project folder | Picks the version the project works on. |
tooljet app source-pull | Project folder | Brings code changed in the editor or by AI into the project. |
tooljet app vet <packages...> | Anywhere | Checks npm packages before they are added. |
tooljet skill install | Project folder | Writes instructions for coding agents. |
A project folder is any folder at or below the one that holds app.json. Outside one, project commands fail with No app.json here or above: run this inside an app project (tooljet app init / clone).
The tooljet library commands are for custom component libraries. See that section's CLI Reference and Limits.
Choose the Instance and Token​
These flags work on app init, app clone, app pull, app check, app dev, app publish, app checkout and app source-pull:
Flag | Description |
|---|---|
--url | ToolJet API origin. Use with --token. |
--token | Personal access token. Use with --url. |
--instance | Use the stored login for this instance, even in a project that belongs to another one. |
The CLI picks the instance and token in this order:
--urland--token, else theTOOLJET_URLandTOOLJET_PATenvironment variables. Give both a URL and a token.- The stored login for
--instance. - The stored login for the project's instance, recorded in
.tooljet/instance.jsonwhen the app is cloned. - The default stored login.
If --url or TOOLJET_URL names another instance than the project's, the command stops. Add --instance <url> to run it against that instance anyway.
tooljet auth login​
Signs in through the browser. The CLI shows a code, the code is approved on the instance's Sign in the ToolJet CLI page, and the CLI stores a personal access token. The token is never printed. For the steps, see Sign In Through the Browser.
Flag | Default | Description |
|---|---|---|
--url | Required | The ToolJet instance (its API origin). Must use https://, except for localhost and 127.0.0.1. |
--browser, --no-browser | --browser | Open the approval page in the browser. |
--default | false | Make this the default login even when another instance is signed in. |
- The code works for 10 minutes.
- The token is valid for 30 days by default. The server's
TOOLJET_CLI_TOKEN_DAYSsets this, from 1 to 90 days. - The CLI keeps one login per instance. A new login replaces the earlier one for the same instance.
tooljet auth login --url https://tooljet.example.com
tooljet login​
Asks for the ToolJet origin URL and a personal access token, checks them and stores them. It has no flags. Use it when the instance doesn't support browser sign-in, or when a token already exists.
tooljet login
tooljet app init​
Creates a React Builder project: app.json and the React and TypeScript source in frontend/.
Argument or Flag | Default | Description |
|---|---|---|
<dir> | Required | Folder for the project. Must not exist or be empty. |
--name | Required | The app name. |
--create | false | Create the app in ToolJet now and record its ID in app.json. |
--install, --no-install | --install | Install dependencies. No install scripts run. |
Without --create, app.json has no app ID, so commands that talk to ToolJet fail until the app is created or an existing app is cloned.
tooljet app init orders-desk --name "Orders Desk" --create
tooljet app clone​
Creates a project linked to an existing app. It writes the app's routes into app.json, writes the code stored on ToolJet into frontend/, reads the app's queries, and links the folder to the instance. With GitSync, it reads the draft of the Git branch the folder is on. If ToolJet doesn't store the app's code, the folder holds a starter project, and the CLI prints a note to copy the code from the repository.
Argument | Default | Description |
|---|---|---|
<appId> | Required | The ToolJet app ID. |
[dir] | The app slug | Folder for the project. |
clone doesn't install dependencies. Run tooljet app install next.
tooljet app clone 55414690-beaa-4fa6-b41b-b8102bd7d1d8 orders-desk
tooljet app install​
Installs the project's dependencies without running any package's install scripts. It picks npm, pnpm or yarn from the lockfile in frontend/, and uses npm when there is none. It also installs the custom component SDK types that match the instance. Use it instead of npm install. To add a package, run npm install --ignore-scripts <package> in frontend/.
Flag | Default | Description |
|---|---|---|
--frozen | false | Install exactly the lockfile, and fail if package.json disagrees. |
app install doesn't take --url, --token or --instance.
tooljet app install
tooljet app pull​
Reads the app's queries, ToolJet Database tables and pages, and writes typed hooks to frontend/src/tooljet.gen.ts. It reads the checked-out version, else the draft of the current Git branch, else the editing version. Run it after a query changes in ToolJet.
tooljet app pull
tooljet app check​
Fails when the code names a query, route, link or page the app doesn't have, or when the security scan fails the gate. It also lists accessibility warnings, which never fail the check.
Flag | Default | Description |
|---|---|---|
--offline | false | Check against the last tooljet app pull instead of reading the app now. The scan skips its network checks and reports them as "not run". |
--scan, --no-scan | --scan | Run the security scan. |
--sarif <file> | Write the security scan as SARIF 2.1.0 to this file. | |
--policy <file> | Scan policy JSON. The workspace policy decides at publish. | |
--json | false | Print one JSON report instead of text. |
It checks that:
- Every
useQuery('<name>')anduseAppQuery('<name>')names a query the app has. - Every
routePath('<id>')names a route inapp.json. - Every
navigate('/<path>'),<Link to>and<NavLink to>path matches a route inapp.json. - Every
<Route path>equals a path inapp.json. - Every
goToPage('<handle>')names a page the app has. - No code casts
useAppQuery, itsrun, or the values passed torun.
It exits with 1 when there is a problem or the scan fails the gate.
tooljet app check --sarif scan.sarif --json
tooljet app dev​
Builds the app on every save in frontend/src and shows it live in the ToolJet editor. The first build links the app: it creates the code page and one hidden page per screen. It needs a draft version. TypeScript errors stop a build from uploading, and the canvas keeps showing the last good build. For a walkthrough, see Build Locally.
Flag | Default | Description |
|---|---|---|
--debounce <ms> | 200 | Milliseconds to wait after a save. |
--once | false | Build, upload and link once, then exit. For agents and CI. |
--scan, --no-scan | --scan | Scan each build and send the result to the editor's Security panel. Never blocks the build. |
--no-source | false | Don't store the code on ToolJet after each build. By default, dev stores it when the code is edited on ToolJet. |
--source <owner> | Also store the code on ToolJet: platform hands editing to the ToolJet editor, repository keeps the repository as the owner and the editor read-only. | |
--source-replace | false | Replace code that was edited in the ToolJet editor. Otherwise the upload stops with a conflict. |
--trust-remote-config | false | Pull and build code from ToolJet even when it changes what a build runs on the local computer, such as build config, package.json, the lockfile or .npmrc. |
--verbose | false | Also print the stored code's revision and owner. |
tooljet app dev
tooljet app dev --once --source platform
Who Sees Local Saves​
Whether local saves reach other people depends on where the app's code is edited:
- The code is stored on ToolJet and edited there (the usual case, for apps made in the editor or with AI): each build also saves the code to ToolJet. The CLI prints
Each build also saves its code in ToolJet, where the editor and AI work on it. The draft, the Code panel and the AI all see the changes. - The code isn't saved by
app dev(--no-sourcewas passed, or the code is owned by a Git repository): only the developer's own canvas shows the local build, and their editor header shows On your computer. Everyone else sees the code stored on ToolJet.
The On your computer menu has these options:
- Show the ToolJet version: See the code stored on ToolJet, as everyone else does. The local copy stays as it is.
- Save my copy to ToolJet: Copies
tooljet app dev --source platform. Run it in the app's folder instead oftooljet app dev, and every save then goes to ToolJet.
Newer Code on ToolJet​
When the app's code is edited on ToolJet, someone can change it in the Code panel, or the AI can change it, during local development. While it runs, dev checks ToolJet for newer code every 5 seconds:
- If no local files changed since the last sync, it pulls the newer code and rebuilds. It prints
Pulled revision <n> (changed in the editor or by AI). - If there are local changes, it doesn't overwrite them and stops uploading. It prints
ToolJet has newer code (revision <n>, changed in the editor or by AI). Run tooljet app source-pull, then save again.
To bring the newer code in, run tooljet app source-pull.
Status Notes in the Editor​
Next to the version menu, the editor's header can show one of these notes about the local copy or its last build.
Note | What It Means | What to Do |
|---|---|---|
| On your computer | The developer's canvas shows the code on the local computer, not the version stored on ToolJet. | See Who Sees Local Saves. |
| Copy is behind | The local copy is older than the code on ToolJet, so the canvas shows the ToolJet version. | Run tooljet app source-pull in the app's folder to bring the newer code in, then keep working there. Clicking the note copies tooljet app pull, which rewrites the typed hooks but doesn't bring the code in. |
| Last save doesn't build | The last save doesn't build, so the app shows the last working version. | Click the note to open the error in the Code panel. |
Changes That Run Locally​
Some files control what a build runs on the local computer: build config files, package.json, the lockfile, .npmrc, and stylesheets that load Tailwind config or plugins. If someone else changes one of these on ToolJet, dev doesn't pull the change. It stops and prints which files changed.
Review the change in the editor first. If it is trusted, run:
tooljet app dev --trust-remote-config
tooljet app publish​
Saves the app's draft as a version, the same as clicking Save version in the editor. It installs exactly the lockfile, runs the app check rules, builds for production, stores the code on ToolJet, runs the security scan with the workspace policy, and saves the version. ToolJet freezes the code with the version. publish doesn't release or promote the version.
Flag | Default | Description |
|---|---|---|
-n, --name | The draft's name | The version's name. |
-m, --message | A description for the version. | |
--allow-findings | false | Save even when the security scan fails the gate. Releasing then needs Release anyway with a reason. |
--source <owner> | The current owner, else platform | Who edits the code after this: platform or repository. |
--source-replace | false | Replace code that was edited in the ToolJet editor. |
--verbose | false | Also print the stored code's revision and owner. |
publish needs:
- An app ID in
app.json. - A lockfile in
frontend/. Runtooljet app installand commit the lockfile. - A draft version.
- No
app checkproblems and no TypeScript errors.
tooljet app publish --name v3 --message "Adds the returns screen"
tooljet app checkout​
Picks the ToolJet version the project works on, by name or ID. pull, check, dev and publish then use it. It overrides the version picked by the folder's Git branch. The choice is stored in app.json as version and stays on the local computer.
Argument or Flag | Description |
|---|---|
[version] | Version name or ID. |
--list | List the app's versions. The checked-out version is marked *. Also the result with no argument. |
--editing | Follow the app's editing version again. |
pull and check work on any version. dev and publish need a draft.
tooljet app checkout --list
tooljet app checkout v3
tooljet app checkout --editing
tooljet app source-pull​
Brings the code stored on ToolJet into the project when it is newer than the project's last upload or pull, for example after an edit in the Code panel or by AI. It removes files under frontend/src and frontend/styles that ToolJet's copy doesn't have.
If a pull would overwrite locally changed files, it refuses and lists them.
Flag | Default | Description |
|---|---|---|
--force | false | Take ToolJet's code over files changed here. A copy of the changed files goes to .tooljet/before-pull/. |
tooljet app source-pull --force
tooljet app vet​
Checks npm packages before they are added: malware and known vulnerabilities, versions published in the last 7 days, license and the blocklist. Inside a project, it uses the project's npm registry settings. It exits with 1 when the packages fail the gate.
Argument or Flag | Default | Description |
|---|---|---|
<packages...> | Required | One or more name, name@version or name@range. |
--offline | false | Skip the network checks. They report "not run", never "passed". |
--policy <file> | Scan policy JSON. | |
--json | false | Print one JSON report. |
vet needs the security scanner. See Security Scanner.
tooljet app vet date-fns@4.1.0 zod
tooljet skill install​
Writes instructions for building the app with React Builder for coding agents, from one source:
CLAUDE.mdfor Claude CodeAGENTS.mdfor Codex and Windsurf.cursor/rules/tooljet.mdcfor Cursor
In CLAUDE.md and AGENTS.md, only the block between the tooljet:begin and tooljet:end markers is replaced. The rest of the file stays. .cursor/rules/tooljet.mdc is rewritten whole. It has no flags. Run it again after updating the CLI.
tooljet skill install
Security Scanner​
The security scanner isn't part of the CLI. It ships with ToolJet's enterprise server.
app checkandapp devskip the local scan when the scanner isn't on the local computer, and printThe security scanner isn't on this computer, so this code wasn't scanned here. ToolJet scans it when you publish.They don't fail because of it.app vetneeds the scanner and fails without it.app publishdoesn't need it: ToolJet scans the code on the server with the workspace policy.
To scan locally, the CLI looks for the @tooljet/app-scanner package, or for the path to the scanner's tj-app-scan.js in TOOLJET_APP_SCANNER_BIN.
Environment Variables​
Variable | Description |
|---|---|
TOOLJET_URL | ToolJet API origin for app commands. Overrides the stored login. Set it with TOOLJET_PAT. |
TOOLJET_PAT | Personal access token for app commands. TOOLJET_TOKEN also works. |
TOOLJET_APP_URL | The editor's origin, when it differs from the API origin. app dev uses it in the link it prints. |
TOOLJET_SDK_SPEC | An npm spec for the custom component SDK to install, instead of the one the instance serves. |
TOOLJET_APP_SCANNER_BIN | Path to the security scanner's tj-app-scan.js. |
npm commands that the CLI runs, such as installs and app vet, use the normal npm configuration, including npm_config_registry and .npmrc. Which registries a stored lockfile may use is a server setting: TOOLJET_CODE_NPM_REGISTRIES on the ToolJet server. See Dependencies.
Files the CLI Writes​
File | What It Holds |
|---|---|
~/.tooljet/credentials.json | The stored logins, one per instance, and the default. Readable only by the current user (mode 0600). |
.tooljet/instance.json | The instance this project folder belongs to. Written by clone and init --create. Git-ignored. |
.tooljet/snapshot.json | The app's queries, tables and pages from the last pull. Used by check --offline. Git-ignored. |
.tooljet/source.json | The revision of the code stored on ToolJet that the project last synced with. |
.tooljet/before-pull/ | Copies of locally changed files, kept by source-pull --force. |
frontend/src/tooljet.gen.ts | Typed hooks, written by pull and dev. Don't edit. |
Git Branches​
If the workspace uses GitSync, ToolJet commits the app's code to a code/ folder in the app's folder in the repository. tooljet app dev can be run in that folder.
The Git branch of the project folder decides which draft is used. For example, git checkout feature-x and then tooljet app dev works on the feature-x branch's draft. The CLI prints the branch it uses, for example On git branch feature-x: working on its draft.
- To work on a different workspace branch than the folder's Git branch, set
"branch"inapp.json. tooljet app checkout <version>overrides the branch.- If the branch has no draft of the app yet, open the app on that branch in ToolJet first.
Common Errors​
Message | What to Do |
|---|---|
No app.json here or above | Run the command inside the project folder, or clone the app first. |
This project belongs to <instance>, and the CLI is not signed in there. | Run tooljet auth login --url <instance>. |
Not authenticated. Run: tooljet login | Sign in with tooljet auth login --url <instance>. |
The ToolJet token was rejected by <instance>: it may have expired | The token expired or was revoked. Run tooljet auth login again. If TOOLJET_URL is set in the environment, it overrides the stored login: unset it, or set a current TOOLJET_PAT. |
This ToolJet instance does not support browser sign-in yet | Sign in with tooljet login and a personal access token. See Sign In With a Personal Access Token. |
The code expired before it was approved | Run tooljet auth login again and approve within 10 minutes. |
That code is not valid or has expired. (in the browser) | Check the code in the terminal, or run tooljet auth login again. |
app.json has no appId | The project isn't linked to an app. Clone the app, or run tooljet app init --create. |
Version <name> is <status>, which cannot change. | dev and publish need a draft. Run tooljet app checkout to pick a draft, or create one in ToolJet. |
<n> TypeScript error(s); not uploaded | Fix the errors listed. The canvas keeps the last good build. |
ToolJet has newer code (revision <n>...) | Run tooljet app source-pull, then save again. See Newer Code on ToolJet. |
Stopped: revision <n> on ToolJet changes <files>... | Review the change in the editor, then run tooljet app dev --trust-remote-config. See Changes That Run Locally. |
This app's source is owned by its repository | The code is edited in Git. Push the change there, or move editing to ToolJet with --source platform --source-replace. See tooljet app dev. |
No lockfile in frontend/ | Run tooljet app install and commit the lockfile. publish needs one. |
The security scanner isn't on this computer | check and dev skip the local scan. ToolJet scans the code at publish. See Security Scanner. |
The security scan fails the gate | Fix the findings listed, or publish with --allow-findings. Releasing then needs Release anyway with a reason. See App Security. |
<path>: ... React Builder installs packages from the npm registry only | Replace Git, URL, file:, link:, alias or workspace dependencies with versions from the npm registry. See Dependencies. |
app.json: ... | Fix the field named. See app.json. |
This version is locked, so this code wasn't saved. | The version was saved or released while dev ran. Restart tooljet app dev to follow the new draft. |