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 - LTS version (22.x or later). 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 will need your Console email address and your instance UUID, which you can find in the Console or under Settings in Instance Admin.

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

The CLI will prompt you for your Console password. Once authenticated, the environment is saved locally 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:

Enter your Insites Console account password to proceed.

To confirm your environments are set up correctly, run:

This lists all configured environments and their associated instances.

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 uploads your project files, and the instance processes the deployment. You will see progress output in your terminal as it runs.

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.

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 environment credentials, including instance UUIDs and authentication tokens. It is created automatically when you run .

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