Insites CLI Tool Commands and Options

This page lists every command in the Insites CLI 6.4.1, with its options. Commands are grouped the way insites-cli --help groups them: Set up, Build, Deploy, Inspect, Data, Modules, GUI and AI. To install the CLI and add your first environment, see Getting Started.

Run every command from your project folder, one level above the app/ or modules/ folder, or from any subfolder of it. The CLI looks for the .insites file in the current folder, then in each parent folder up to the git root. insites is a short name for insites-cli, and both work everywhere.

Run insites-cli --help to list the commands, and add --help to any command to see its options and examples.

Install and Update

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

npm i -g @insites/insites-cli@latest --no-fund

--no-fund is optional. It hides the npm note about packages that accept donations. The CLI needs Node.js 22 or newer, and Node 24 is recommended. On an older Node it stops with one line that says which Node you have and what to install.

Check the installed version:

insites-cli --version

Once a day the CLI checks for a newer version and prints one line when there is one. It stays silent with --json, when CI is set, and when you are offline. Set INSITES_NO_UPDATE_NOTICE=1 to turn it off.

Set Up

init

Creates the folder structure for a new Insites project, such as app/ and modules/.

insites-cli init

env add

Adds an environment and signs you in to it. An environment is a name for one instance, such as staging or production. You pass that name to every command that talks to an instance. Environments are saved in the .insites file in the folder where you run env add.

Get the instance UUID from the Insites Console: open the instance and go to its CLI Commands tab, or its instance details.

insites-cli env add <environment> --instance-uuid <instance-uuid>

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 sign-in code lasts 5 minutes.

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.

Sign in with an access token

The instance's CLI Commands tab in the Insites Console issues a personal access token, and shows the full command to add it. Copy that command, or give the instance UUID instead of the address:

insites-cli env add <environment> --instance-uuid <instance-uuid> --token <token>

A token is checked against your current role on every request, and each deploy is recorded against your name in the Console. Deploying and syncing need the Developer role. With the Editor role, the token can read and change records. When a request is refused, the CLI prints the reason.

With a token, requests other than assets can be up to about 5 MB. Assets upload straight to storage, so a large asset deploys like any other. If your code and content files are over that size, deploy fewer files at a time with --partial-deploy, or use the browser sign-in for that environment.

env list

Lists your environments. Add --json to print them as one JSON document.

insites-cli env list

env refresh-token

Signs you in again to one environment, and changes only that environment's entry. Use it when a sign-in has expired, or when a command warns that the environment still stores an instance key from an older release.

insites-cli env refresh-token <environment>

doctor

Checks everything that usually goes wrong and prints the command that fixes each problem: your Node.js version, whether a newer CLI is out, the .insites file, how each environment signs in, whether the sign-in works, whether the instance answers and accepts it, and the linter configuration.

insites-cli doctor
insites-cli doctor staging
insites-cli doctor --json

Without an environment name it checks every environment. It exits with 1 when a check fails. It never prints a key or token, so its output is safe to paste into a support request.

Build

sync

Watches your files and sends each change to the instance as soon as you save it. Alias: s.

insites-cli sync staging
insites-cli sync staging --livereload
insites-cli sync staging -f app/views/pages/example.liquid

Sync never watches node_modules, .git or anything listed in .insitesignore. It keeps running when something goes wrong: when an asset upload fails it names the file, and the next save uploads it again. An expired upload link is renewed once automatically. If your computer runs out of file watchers, sync prints the fix once. See Troubleshooting.

check

Checks your Liquid with the linter. check run reports syntax errors, unknown filters, missing partials and performance problems, grouped by file with the line that causes each one.

insites-cli check run
insites-cli check run app/views/pages
insites-cli check run -f json

check run exits with 1 when it finds a problem and 0 when your code is clean. Every run reports how many files it read as filesChecked. When it read none, it exits with 1, because a check that read nothing proves nothing.

check init writes a .insites-check.yml configuration file. check update-docs downloads the latest Liquid documentation the linter checks filters and objects against. See Linting Rules.

audit

Checks the code in your project for deprecated tags, filters and keys, and files in the wrong place. Every deploy runs it first. It takes no options.

insites-cli audit

test run

Runs the Liquid tests in your project on an instance.

insites-cli test run staging
insites-cli test run staging --name signup_creates_profile

Deploy

deploy

Deploys your code and assets to an environment. Alias: d.

insites-cli deploy staging
insites-cli deploy staging --dry-run --verbose

After each deploy the CLI prints the instance's report: for each type of file, how many were upserted, deleted and skipped because they had not changed.

Deploy report:
  Pages     2 upserted  0 deleted  41 skipped
  Partials  1 upserted  1 deleted  88 skipped

A dry run also reports the assets: how many would upload, their total size, and how many match .insitesignore. Deploy does not apply .insitesignore, only sync does, so matching assets are still uploaded. A dry run with an access token checks the release but not the assets, because an asset can only be checked by uploading it.

A release with nothing in it says Nothing to deploy. Keep a release under 50 MB, assets included.

archive

Builds the release zip without deploying it. It goes to ./tmp/release.zip unless you name another file.

insites-cli archive
insites-cli archive -o ./build/release.zip

duplicate init

Copies one environment into another through the Insites Console.

insites-cli duplicate init staging staging-copy

Inspect

logs

Shows the instance's logs as they happen. Alias: l. Press Ctrl+C to stop.

insites-cli logs staging
insites-cli logs staging --filter error
insites-cli logs staging --json

The first logs appear straight away, and a single failed check does not stop the command.

logsv2

The logsv2 commands (search, searchAround, alerts and reports, alias l2) are listed in the help but are not available: log search has no service behind it, so every logsv2 command fails. Use logs instead.

exec liquid

Runs Liquid on the instance without deploying a file.

insites-cli exec liquid staging '{{ context.params.id }}' --params-file params.json
insites-cli exec liquid staging -f scripts/report.liquid

exec graphql

Runs a GraphQL query or mutation on the instance.

insites-cli exec graphql staging -f queries/report.graphql --params-file vars.json

Data

constants

Sets, removes and lists the constants on an instance, such as API keys. Constants are available in your Liquid and GraphQL.

insites-cli constants set staging --name API_KEY --value my-secret-key
insites-cli constants unset staging --name API_KEY
insites-cli constants list staging
insites-cli constants list staging --json

constants list hides the values. Run it as SAFE=1 insites-cli constants list staging to show them. A value can span several lines, such as a PEM key.

data export

Exports the data on an instance. By default it writes a zip file.

insites-cli data export staging --path data.zip
insites-cli data export staging --no-zip --path data.json

data import

Imports data from a JSON or zip file. Files referenced in a JSON import are uploaded too, and a failed upload fails the import.

insites-cli data import staging --path data.json
insites-cli data import staging --zip --path backup.zip

data clean

Removes the records on an instance. The tables stay unless you add --include-schema. This cannot be undone, so the CLI asks you to type CLEAN DATA to confirm.

insites-cli data clean staging

migrations

Migrations are Liquid scripts that run once on each instance to set up or change data.

insites-cli migrations generate staging add_default_categories
insites-cli migrations list staging
insites-cli migrations run 20180701182602 staging
insites-cli migrations status 20180701182602 staging
insites-cli migrations retry 20180701182602 staging

pull

Downloads the app from the instance as a zip file. The default file is app.zip.

insites-cli pull staging
insites-cli pull production -p ./backups/app-backup.zip

A download that fails, or stops, deletes the partial file and exits with 1. This applies to pull, modules pull and data export.

Modules

GUI

gui serve starts a local web interface for an environment. See Graphical User Interface.

insites-cli gui serve staging --open --sync

AI

ai init connects Claude Code, Cursor or VS Code to Insites CloudShell and the Insites tooling. See Connect Your AI Assistant.

insites-cli ai init

JSON Output

Every command that has a --json option prints exactly one JSON document, and everything else goes to the error stream, so the output always parses. A failure prints a JSON object whose status is error and whose error holds the message, and exits with 1. logs --json is the exception: it prints one JSON object per line. You can also set JSON_OUTPUT=true instead of passing --json.

Environment Variables

A request that gets a 503, or an answer asking it to wait, is tried again up to three times. A request that could have changed something on the instance is never tried again.

Configuration Files

The CLI does not read your project's .env file.