Getting Started with the Insites CLI Tool

Overview

This guide walks you through installing the Insites CLI, connecting it to your instance, and running your first deploy. By the end, you will have a working local development setup with live sync capability.

Requirements

Before you begin, make sure you have the following installed on your machine:

• Node.js - the current LTS version. Download it from nodejs.org.
• npm - Included with Node.js. Used to install the CLI globally.

You can verify your Node.js version by running:

Installation

Install the Insites CLI globally using npm:

Once installed, verify it is working by checking the version number:

You should see a version number like . If you see an error instead, make sure Node.js is installed correctly and that your global npm directory is in your system PATH.

Creating an Environment

An environment connects the CLI to a specific Insites instance. You need your instance UUID. In the Insites Console (console.insites.io), open the instance and go to the CLI Commands tab. To use the CLI, you also need the Developer role or above on the instance.

Run the following command, replacing the placeholder values with your own:

Your browser opens the Insites Console sign-in. Check that it shows the same code as your terminal, then approve. The environment is then saved in a file in your current directory.

You can connect multiple instances to a single codebase. This allows you to deploy your codebase to different environments to suit your development needs. For example, you can deploy to a staging environment for testing, then deploy the same codebase to production once it is ready.

Worked example:

Sign in and approve in the browser window that opens.

The CLI saves your Insites Console sign-in, never the instance key. Each command asks the Console for the key again, so when someone's access is removed in the Console, their next command stops working. When your sign-in expires, the command says so. Sign in again with:

Instances on the Shared Stack

Instances on the private stack have addresses ending in or . Older instances are on the shared stack. The CLI works out which stack an instance is on from its UUID. For an instance on the shared stack, add your Console email. The CLI asks for your Console password instead of opening the browser.

Signing In With an Access Token

For an instance on the private stack, you can sign in with an access token instead of the browser. This suits a machine where you cannot open a browser. Get your token from the Access Token card on the instance's CLI Commands tab in the Console. See Instance Access Tokens.

Add for an instance in the staging Console. You can also paste the full command the Console shows under your token.

A token environment goes through the Insites proxy. It checks your role on every request, and records every deploy and change against your name in the instance's activity in the Console. Deploying and syncing need the Developer role. With the Editor role, the token can read and change records.

To confirm your environments are set up correctly, run:

This lists all configured environments with their stack, instance and email.

Checking Your Setup

If a command fails with a sign-in or connection error, run . It checks Node.js, the CLI version, your environments, their sign-in and the instances, and tells you the command that fixes each problem. It never prints a key or token.

Deploying to an Instance

Deploying pushes your local codebase to a remote instance. Run the deploy command from the root of your project directory, specifying the environment name:

The CLI sends your project files, and the instance processes the deployment. When it finishes, the CLI prints a report: for each type of file, how many were upserted, deleted, and skipped because they had not changed. With the browser sign-in on the private stack, keep each deploy under 50 MB, assets included. See Commands and Options for the other limits.

For example:

Starting a New Project

If you are starting from scratch and do not yet have a project directory structure, use the command to scaffold one:

This creates the standard directory structure that Insites expects. From there, you can add your views, partials, and other files before deploying.

Testing Your Deployment

After a successful deploy, make a small change to verify everything is working. Find a file like in your codebase, change some text, save the file, and deploy again:

Visit your instance URL in a browser and confirm the change is live.

Checking a Deploy First

A full deploy removes files from the instance that are not in your project. To see what a deploy would change without changing anything, run a dry run. It works for instances on the private stack, and lists every error at once with its file path.

To deploy some files without removing the rest, add .

Syncing Your Codebase

Sync watches your local files and pushes changes to the instance in real time as you save them. This is the fastest way to develop, since you do not need to run a full deploy after every change.

The CLI stays running and watches for file changes in your and directories. Press to stop syncing. Sync handles code changes, asset uploads, file renaming, and deletion.

Configuration Files

The CLI uses a small number of configuration files in your project root. Here is what each one does:

.insites

This file stores your environments: each instance's UUID and address, and how you sign in to it. For an instance on the private stack, it holds your Insites Console sign-in, not the instance key. It is created when you run . To keep it somewhere else, set the environment variable to its path.

.insitesignore

Works like a file but for the CLI. Any files or directories matching the patterns in this file are excluded from deploy and sync operations. This is useful for skipping local-only files, build artifacts, or anything else that should not be pushed to the instance.

.insites-check.yml

The settings for the linter, . Create it with . See Linting Rules.

.insites.legacy

If you are working with a project that previously used the legacy configuration format, this file may be present. The CLI reads it for backward compatibility. For new projects, you do not need this file.

Next Steps

You now have a working CLI setup with an environment connected to your instance. From here, explore the full list of available commands and their options in the Commands and Options reference.