Getting Started with the Insites CLI Tool

This document walks you through the basic requirements and steps you need to take to start using the Insites CLI tool.

Requirements

The Insites CLI Tool requires Node.js in at least the latest long-term support (LTS) version to work properly.

Visit https://www.npmjs.com/package/@insites/insites-cli to view more details about the Insites CLI tool in npm.

Installation

To install Insites CLI:

1. Once you have Node.js installed on your machine, open a command-line tool.

2. Run the following command to install the Insites CLI:

   The attribute means you are installing the tool globally. Installing in this manner may require higher system permissions.

   
   

   On Unix-based systems, higher system permissions means using sudo, and on Windows, it might require running your command-line tool with the administrative rights (it should be available in the right-click context menu).

3. Verify that the installation was successful by running:

   
   

   If everything went smoothly, the version number of the Insites CLI you installed is displayed (for example: 4.7.1).

Creating an Environment for an Instance

Now that you have both the Instance and Insites CLI set up, it's time to add the Instance to an environment:

Run the following command in the project root directory to add an Instance to an environment:

Please remember that the above example is a template. Replace the values inside the angle brackets with your unique inputs.

You can connect multiple Instances to a single codebase. This capability allows you to deploy your codebase to different environments to suit your software development needs. For example, you can deploy to a staging environment to beta-test your Instance. Once your codebase is ready for production, you can then deploy it to a production environment.

Worked example:

Enter your Insites Console account password to proceed.

Run the following command to view all the available environments and verify that your Instance was added to your preferred environment:

Deploying to an Instance

To deploy to an Instance:

1. Open a terminal.

2. Check the list of available environments by running the following command:

   
   

3. Deploy the Instance by running the following command in the root of your project folder:

   
   

   For example:

   
   

Testing the deployment process

To test the whole deployment process, make some changes in the code.

For example, find a file named in your codebase. Open and change any of its lines using a preferred code editor. For example, locate a line with the welcome message:

Change it into:

Save the file and send the codebase to the Instance by running the command in the command line:

You should see changes when you visit the Instance URL or refresh the previously opened page.

Syncing a local codebase with an Instance

For seamless integration and minimal effort, it is ideal to have the Instance promptly update with any code changes you make. Insites facilitates this through a process known as . To initiate , run the following command from the root directory of your project:

The above command is intended to be run and left open while making code changes.

essentially observes your codebase, automatically uploading any modified files to your Instance the moment you save them. It selectively uploads only the changed files, ensuring a quick and efficient process.

Syncing in action

For this example, try another change in the code, but this time, start the using the following command:

A confirmation message saying the synchronization has started appears, so find another place in the code to test how this works. Locate the 'Hello world' title in the of the demo page and change it to something else, like 'Hello beautiful world.'

After the change, save the file.

In the command line, you should see a confirmation message that the edited page was synced. Refreshing the page in the browser should confirm that everything worked and the new text content is displayed.

Syncing handles not only code changes but all other assets. Images, JavaScript files, or GraphQL queries – any change in your project directories automatically reflects on your Instance. The changes also include file renaming and deletion.

Configuration files

The Insites CLI tool contains the following configuration files:

• - use this file to supply a list of file paths that Git intentionally ignores.
• - contains environment credentials used to connect to the Instance.