Insites CLI Tool Commands and Options

Note

Run every command from your project root folder, one level above the or folder.

This page lists every command in the Insites CLI, with its options. Commands are grouped by what they do. To install the CLI and add your first environment, see Getting Started.

Run to list the commands. Run , or add to any command, to see its options.

Install and Update

Install the CLI, or update it to the latest release, with the same command:

Check the installed version:

Environments

An environment is a name for one instance, such as or . You pass that name to every command that talks to an instance. Environments are saved in the file in your project folder.

Instance addresses end in or . The CLI works out where an instance runs from its UUID, so you usually do not need to set it.

Add an Environment

Give the instance UUID. You find it in the Insites Console, on the instance's CLI Commands tab.

Your browser opens the Insites Console sign-in. Check that it shows the same code as your terminal, then approve. The Console checks that you can edit the instance.

The CLI saves your Console sign-in, never the instance key. At the start of every command, it asks the Console for the key again and keeps it only for that command. So when someone's access is removed in the Console, their next command stops working.

If you also give , the CLI ignores it and signs you in through the browser.

Options

• - The instance UUID from the Insites Console
• - Sign in with an access token instead of the browser. See below.
• - The address the Console shows in the access token command
• - Sign in to the staging Insites Console instead of production
• - Set the stack yourself. The value is . This skips the stack check, which needs to reach the Console.
• - Stop waiting for the browser sign-in after this many seconds. The sign-in code lasts 5 minutes, so 300 is the most.

Only letters, numbers, underscores and dashes are allowed in an environment name.

Sign In With an Access Token

An access token lets the CLI reach one instance without a browser sign-in. Get your token on the instance's CLI Commands tab in the Insites Console. See Instance Access Tokens.

Add for an instance in the staging Console. You can also paste the full command the Console shows. It has this shape:

A token environment goes through the Insites proxy, which works like this:

• It checks your role on the instance on every request. Deploying and syncing need the Developer role. With the Editor role, the token can read and change records.
• Every deploy and change is recorded against your name in the instance's activity in the Console.
• When the proxy refuses a request, the CLI prints the reason.
• Assets upload straight to storage, so a large asset deploys like any other file.
• The rest of a release is limited to about 5 MB. If your code and content files are bigger, deploy them in parts with , or use the browser sign-in for that environment.

Publishing a module to the Partner Portal does not go through the proxy, and still needs Partner Portal access.

List Environments

Lists the environments in your file, with the stack, instance and email of each.

Sign In Again

When a sign-in expires, the command says so. Sign in again for that one environment. Only its entry in changes.

An environment that holds an instance key prints a warning on every command. Run to move it onto the Console sign-in.

Use Environment Variables in CI

In a CI pipeline, set these six variables instead of using a file. The CLI then uses them for every command. Take the values from the Access Token card on the instance's CLI Commands tab in the Insites Console.

Variable	Value
	The proxy address the tab shows. It ends in /i/ and the instance UUID.
	The email of the person or service account that deploys
	Your access token
	The instance UUID
	The same access token

Every deploy is then recorded against the person the token belongs to. Set every time: without it, the CLI tries to work out the stack from the URL, and it cannot do that from the proxy address.

To keep the file somewhere else, point the CLI at it with . No command takes a config option.

Check Your Setup

The command checks everything that usually goes wrong, and gives the command that fixes each problem.

It checks:

• Your Node.js version
• Whether a newer CLI is available
• Your file
• How each environment signs in, and whether the sign-in works
• Whether each instance answers and accepts the sign-in
• Your linter configuration

Without an environment name, it checks every environment in . It exits with code 1 when a check fails. It never prints a key or token. Add to get the results as JSON, for scripts and AI agents.

Run it first when a command fails with a sign-in or connection error.

Deployment

Deploy

Sends your code and assets to the instance. This is the standard way to release a change.

The short form is .

Important

A full deploy removes files from the instance that are not in your release. Run a dry run first if you are not sure what will change.

Options

• - Deploy your files without removing files that are missing from your release. Use it to deploy part of a project.
• - Check the release on the instance and show what would change, without changing anything.
• - List every file path in the deploy report, not just the counts
• - Print the result and the report as JSON on stdout. Everything else goes to stderr.
• - The stack the instance is on. It is taken from the environment when you leave it out.

The Deploy Report

After each deploy, the CLI prints a report from the instance. For each type of file, it shows how many were upserted, deleted, and skipped because they had not changed.

Dry Run

A dry run sends the release to the instance, which checks it and reports what would change. Nothing is applied. Every error is listed at once, and each starts with its file path.

Through an access token, a dry run does not send or check assets, because checking them means uploading them. The report lists them as not checked.

Release Size

• With the browser sign-in, the assets travel inside the release. Keep each release under 50 MB, assets included.
• With an access token, assets upload straight to storage. The rest of the release is limited to about 5 MB.

If a release is too big, deploy it in parts with .

A deploy also runs the code audit first (not when the environment variable is ), and runs any pending migrations.

Sync

Watches your project and sends each file to the instance as soon as you save it. Use it while you develop on a staging instance. Press to stop.

The short form is .

Options

• - Send one file once and exit, without watching
• - Reload the browser when a file changes
• - The most connections at once (default 3)

Important

Do not sync to a production instance. Every save goes live at once. Use for production.

Archive

Builds the release zip file without deploying it. It is saved as unless you give another path.

Pull the App Folder

Downloads the instance's folder into a zip file, by default. This is your code, not your data. To get your data, use .

Data

These commands work on all the data on the instance at once. There is no export or clean for a single table.

Export Data

Exports all the data on the instance to a zip file, by default.

Options

• - Where to save the export
• - Use each object's own instead of its generated

Import Data

Imports data from a JSON file, by default. Add to import a zip file, such as one made by .

Options

• - The JSON or zip file to import
• - The file is a zip file

Clean Data

Deletes all the data on the instance: records, users and the rest. You must type to confirm. The instance answers 422 if data clean is turned off there.

Options

• - Also remove pages, schemas and other files
• - Skip the confirmation

Warning

This cannot be undone. Use it only on a staging instance you are willing to wipe. Export the data first if you may need it.

Modules

List Modules

Lists the modules installed on the instance. It does not list modules you deploy from your own folder.

Start a Module

Creates from the starter structure that comes with the CLI. Nothing is downloaded. It will not write into a module folder that already has files in it.

Pull a Module

Downloads installed modules into a zip file, by default. Add a module name to download one module. Only the module's files are included.

Remove a Module

Removes a module from the instance, with its configuration and its data. Export your data first.

Set a Module Version

Writes the module version into . Add to take the version from .

Constants

Constants are named values stored on the instance, such as API keys. Your Liquid reads them from . Keep secrets in constants, not in your code.

Set a Constant

Creates a constant, or changes its value.

For example:

Remove a Constant

List Constants

Lists the constants on the instance. Values are hidden unless you set . Add for JSON.

Run Liquid or GraphQL

Runs Liquid or a GraphQL query on the instance without deploying a file. Useful for checking data and testing a snippet. Write the type first, then the environment.

Options

• - Run the code in a file instead of the code you type
• - Print the result as JSON

Code Quality

Check

The linter. It parses your Liquid and reports syntax errors, unknown filters, missing partials, pages that take an address they should not, and performance problems. Add a path to check one folder. It exits with 1 when it finds a problem, so you can use it in CI or a pre-commit hook.

Options

• - (default) or
• - Only report the named check. You can repeat it.
• - Apply automatic fixes. This rewrites your files, so commit first.
• - Only print problems, with no success message

writes a configuration file in the current folder. refreshes the Liquid documentation the linter checks against. Run it if a filter you know is valid is reported as unknown. For the checks, the configuration file and how to turn a check off, see Linting Rules.

The same linter runs as a language server, so your editor can show hover help, completions and problems as you type. Point your editor at as the language server for files. You do not run this command yourself. It is hidden from the help.

Audit

Scans your project for deprecated tags, filters and keys, and for files in the wrong place. A deploy runs it first.

The audit always exits with 0, even when it finds something. To fail a CI step on it, check that its summary line says

GUI

Starts a local web interface for the instance, with a GraphQL editor, a Liquid editor, and views of your data, constants and logs. See Graphical User Interface.

Options

• - The port to use (default 3030)
• - Open your browser when the GUI is ready
• - Run sync at the same time, so one command does both

Logs

Shows the instance's logs as they happen, including Liquid errors and the entries your tags write. It keeps running until you press .

The short form is .

Options

• - Only show entries of this type, for example
• - How long to wait between checks, in milliseconds (default 3000)
• - Show only the message, without the context lines
• - Print each entry as one JSON object per line, with , , , and

To find the entries from one piece of code, give its tag its own type, such as , and filter on it with .

Log search and alerts are not available at the moment. Use to follow an instance's logs.

Migrations

A migration is a Liquid file that runs once on each environment, for example to change data after a schema change. A deploy runs every pending migration in timestamp order.

Generate a Migration

Creates an empty migration in . Its name starts with a timestamp. The instance makes the timestamp, so give an environment.

List Migrations

Lists the migrations on the instance and the state of each. Add for JSON.

Run a Migration

Runs one migration, by its timestamp. Give the timestamp, not the full file name.

Check a Migration

Shows the state of one migration, and its error messages if it failed. Add for JSON.

Retry a Migration

Shows the state of a migration, then runs it again. Use it after you fix a migration that failed.

Other Commands

Start a Project

Creates the standard project folders in the current folder. Run it once, in an empty folder.

Duplicate an Environment

Copies one environment into another.

Help

JSON Output

These commands can print JSON instead of text, for scripts, CI and AI agents. Add , or set for every command in your session.

Configuration Files

• - Your environments and how each signs in. Add it to and never commit it.
• - Files and folders that deploy and sync leave out, written like
• - The linter settings, made by