Academy

Welcome to the Using CLI training session. Here's what we'll cover:

• How to setup CLI on Windows & macOS
• How to connect with a site using CLI
• Understanding Add, Pull, Sync, Deploy & more
  
• Important best practices when using CLI

If you've not followed a training session before, then there are a few things to note about how you can use this page:

1. First, click a "Segment" on on the right-hand side of a page to skip the video to the beginning of that specific segment and start watching.
2. Second, any important links and pages we discuss during a training session can also be found on the right hand side of this page, below Segments.
3. Finally, the Overview section will outline key steps you can follow to achieve what is shown in the video. Either follow along with the video, or follow the Segment Overview, it's totally up to you!

Step 1 - Windows, macOS & Linux

The CLI is distributed via Node Package Manager (NPM) and so you will need NodeJS installed on your machine. The easiest way to get this is to visit https://nodejs.org/ and download the LTS version as this has better support.

Step 2 - macOS & Linux Only

If you are using a windows computer, skip to the next step. If you are using macOS then please follow this step.

Click the link and follow the instructions step by step to: Install NPM.

If you are using zsh as your shell then the commands here will have to be run against the ~/.zshrc file, not ~/.profile which is used for bash.

zsh is the default for Macs since macOS Catalina, to find out which shell you are using you can run echo ${SHELL} in terminal. The response will be /bin/zsh if you are using zsh, or /bin/bash if you are using bash.

If the ~/.zshrc or ~/.profile files do not already exist then you may need to create them first before running the export PATH command. To create whichever file you need, use touch ~/.zshrc or touch ~/.profile.

Step 3 - Windows, macOS & Linux

Write the following command in Terminal to Install CLI:

npm i -g @siteglide/siteglide-cli

When an update is released for the CLI, you can use the same command as above to install the updated version.

Step 1 - Project Folder

Create a new folder on your machine to store your project files within. Typically you would call this folder the name of the site you will be working on so you can find it easily later.

Step 2 - Add

The first time you use the CLI with a project on your device, you will need to create an environment. This is essentially a config file that authorises your connection.

Open a Terminal window, type in cd (change directory), then drag your project folder into the window and hit enter to work within that folder.

Write the following command into Terminal:

siteglide-cli add < env > --email me@mydomain.com --url https://my_great_site.com

You must use the email of your Siteglide Portal account to replace me@mydomain.com and the development domain of the website you are connecting with to replace https://my_great_site.com.

Command flags such as < command >, < env > and < flags > should be replaced with the relevant data. For example, < env > should be replaced with the chosen name for the environment such as production.

Siteglide CLI offers a range of commands including Sync, Pull, Deploy, Export Migrate, GUI and more.

Find all available CLI commands you can use within the doc Introducing Siteglide CLI.

Best practices while using CLI:

1. Maintaining Staging vs Production

   1. We currently recommend that you create a staging (trial) copy of the production (live) site when you would like to work with a site in staging to avoid errors to a live site. Once you are finished working and have deployed to the production site, delete the staging site. Next time you need to work on the site in staging, repeat the process.

   2. Later we will be releasing functionality that allows for a tighter integration between production & staging on an ongoing basis. See the roadmap task for more info: Staging Environments

2. Create first in Admin to receive the correct structure if you are unsure

   1. If you are unsure of how to structure YAML, data or other files, create an example first in the site Admin with data in all the fields you might want to use, then pull the site to view the structure the system uses.

3. Avoid using a cloud folder location (such as DropBox) to prevent infinite loops

   1. We recommend avoiding putting your project folder within a space that is connected to a third party cloud system (such as DropBox) as this can create infinite sync loops between the cloud service and CLI upload as both actions edit the files slightly and therefore trigger each other.

4. You can compile Sass/Scss with Sync turned on, useful for build tools such as Webpack/Gulp etc

   1. Using CLI you can write large Sass/Scss files outside of the marketplace_builder folder which you compile on your machine to a minified version. You can store that minified resulting file within the marketplace_builder folder structure which can then be synced or deployed to your site, minimising use of storage on the site.