Developers · Setup

Setting Up Your Project

Last updated 7 November 2026

Insites operates on the principle that working offline should seldom be necessary. You can create and modify files using a code editor in your local file system while remaining continuously connected to your Instance. This connection allows the Insites engine to analyze and interpret your codebase so that you can deploy changes to your code as needed or have the system make the updates every time changes to a file are made. In essence, you write code locally but execute it remotely.

Insites directory structure

Your code needs to be organized in a specific way for it to be correctly interpreted by Insites. The simplest method for initializing code with the proper folder structure is to use the command.

Start by creating an empty folder for your project named in this example, then navigate to it from the command line:

 mkdir my-project
 cd my-project

Overview of the directory structure

The command creates all of the required folders used by Insites. You need to know the basic directories that store files and web pages. In addition, you must also know the directories that handle data.

Note

Please refer to our Codebase documentation for a comprehensive discussion on the Insites directory structure.

Assets

Store static, public assets in the folder. For code you want to reuse or package as a module, use instead. Images, JavaScript, fonts, CSS files, or any downloadable documents go here. You can organize the files any way you want, but consider using the following structure to separate various asset types:

for images
for JavaScript files
for the page CSS
for the font files

Note

Please take note of the following pointers regarding assets:

You may refer to our documentation on Assets for more details on managing and using assets on your Instance.

Content

Put every content page in . You may refer to the Views: pages, layouts, and partials section for more details.

Data

Put the schema (the structure of your database written in YAML) in .

GraphQL queries and mutations save, retrieve, or modify data in the database. GraphQL also adds or creates items in a database. All these queries and mutations go to .

Now that you are inside the folder create the directory structure by executing the following command:

 insites-cli init

After executing the command, a success message is displayed, confirming that the directory structure was created. Your project's root directory contains a variety of new files and folders. The subsequent sections in this document explain what they are for. Also, note that the command created an example HTML page with a welcome message.

Note

The Getting Started with the Insites CLI Tool documentation presents a deep dive into the topics discussed in the following sections:

Creating an Environment for an Instance

This step establishes a connection between your local codebase and an Instance. This connection allows you to deploy changes from your local codebase onto the Instance.

Use the following command to simultaneously create an environment and add an Instance to it:

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

Your browser opens so you can sign in to the Insites Console and approve the request. The CLI then saves your Console sign-in for this environment. It never stores the instance key: each command asks the Console for it, so removing someone's access in the Console stops their next command. To sign in with an access token instead, see Getting Started with the Insites CLI Tool.

Important

Please take note of the following important pointers:

Run all commands discussed in this tutorial in the project root directory.
Apart from alphanumeric characters, only underscores and dashes can be used in the environment-name. Other special characters could cause an error.
You can find your instance UUID in the Insites Console, on the instance's CLI Commands tab.

Deploying to an Instance

Once you have connected your codebase to an Instance, you can now deploy changes from your codebase in your local machine to your Instance.

The deployment process is initiated by using the following command in the root of your project folder:

 insites-cli deploy <environment-name>

After deployment, the CLI prints how many files of each type were upserted, deleted and skipped, and you can see your project on your Instance. A full deploy removes files from the instance that are not in your project. Add to see what a deploy would change without changing anything.

Syncing a local codebase with an Instance

Syncing is a feature that enables you to set up your codebase and Instance so that any changes you make to your codebase are immediately pushed and reflected on your Instance. To enable syncing, run the following command from the root directory of your project:

 insites-cli sync <environment-name>

Important

We suggest you only use on staging Instances. Using this command on a production Instance causes changes to your codebase to be immediately deployed to a live (production) site and can be dangerous. Proceed with caution if using in a production environment.