Skip to main content

CLI Development

The files for the command line interface component of Thermostat are located in the cli folder in the repository. The command line interface is the largest and most complex component of Thermostat. Please be sure you understand the Thermostat CLI Architecture before attempting to make changes to this system.

You can run development commands on the CLI application by using the thermostat run cli command to run the Yarn scripts defined in cli/package.json. You can use the thermostat run update_cli command to build the CLI and replace the version of Thermostat that your local development environment is currently using with the newly built version. This is the primary method for testing changes to the CLI locally, but it must be done with care because if you break your local Thermostat installation you will need to remove it and reinstall it from scratch (remove the containers with Docker and follow the installation process). It is a good idea to back up your Thermostat global configuration file located at /var/lib/thermostat/config/config.yml before making changes to your local Thermostat installation as it will allow you to easily restore your Thermostat application state if you need to re-install Thermostat.

Build Environment Variables​

You need to set the following variables in the cli/.env file in order to build the Thermostat CLI:

  • GITLAB_DEPLOY_TOKEN_USERNAME: This should be the username of a GitLab Deploy Token that has access to read the Thermostat GitLab repository.
  • GITLAB_DEPLOY_TOKEN_PASSWORD: This should be the password of the GitLab Deploy token described in the environment variable above.

Runtime Environment Variables​

You can set some special environment variables when running the Thermostat CLI to customize the behaviour of Thermostat in ways that are sometimes useful when debugging Thermostat locally:

  • THERMOSTAT_DATA_PATH: This is the path on the host system where Thermostat stores its stateful data that needs to persist between restarts, it defaults to /var/lib/thermostat
  • THERMOSTAT_SSH_PORT: This is the port that Thermostat will use to SSH into host system, it defaults to 22
  • THERMOSTAT_DOCKER_SOCKET: This is the sockfile path on the host system that Thermostat uses to connect to the Docker daemon, it defaults to /var/run/docker.sock
  • THERMOSTAT_ROOT_HOME: This is the path to the root user's home directory on the host system (this is primarily used to configure SSH access by modifying the .ssh/authorized_keys file), it defaults to /root
  • THERMOSTAT_API_URL: This is the URL that Thermostat will use to communicate with the Thermostat API, it defaults to api.thermostat.fahrenheit.io.
  • THERMOSTAT_WEB_SERVER_PORTS: This is a comma-separated list of ports that Thermostat will assign exclusively to the web server service (Nginx or Caddy) so other containers cannot bind them, it defaults to 80,443
  • THERMOSTAT_DEBUG: This is a boolean flag that forces verbose logging to always be on in Thermostat, this is useful for debugging issues in the Thermostat startup process that happen before the --verbose parameter is loaded. You can set this environment variable to any non-empty value to enable it or leave it empty to disable it.

Code Files​

This is a brief overview of the purposes of all the important code files in the CLI codebase:

  • cli/package.json: This file contains scripts and dependencies used for CLI development.
  • cli/clean-dependencies.sh: This script is used for "cleaning" the package.json and yarn.lock file so they can be cached by the Docker build system. If you don't clean the files this way then Docker will unnecessarily rebuild all of the dependencies from scratch when you build the CLI (which can be very slow) even if you just did something inconsequential like change the version number. Cleaning the files this way will make it so that it will only rebuild the dependencies if you actually change the dependencies.
  • cli/buildtypes.ts: This script compiles the TypeScript types for the application into JSON Schema definitions that can be used for run-time type checking. You can run it using thermostat run update_cli.
  • cli/updatelocalthermostat.ts: This script builds the CLI and replaces the version of Thermostat that your local development environment is currently using with the newly built version.
  • cli/webpack.config.js: This file contains the build configuration for the CLI application.
  • cli/.env: This file contains environment variables needed for building the CLI application.
  • cli/Dockerfile: This is the Docker image definition file for the main Thermostat Docker container.
  • cli/static/entrypoint: This is the entrypoint script for the main Thermostat Docker container.
  • cli/services: This folder contains the Docker configuration files for the Thermostat service containers. Each subfolder in this folder contains the files needed to produce a single self-contained Docker image that can be run as a Thermostat service. It also contains Docker configuration files for containers that are not normal services but are instead used to supplement special commands like dev-tools and compare.
  • cli/src/types: These are the core TypeScript types used for validating data formats in the application. They are separated in this way to make it easy to compile them into JSON Schema definitions that can be used for run-time type checking.
  • cli/src/templates/script-entrypoint.sh: This is the script entrypoint used for initializing scripts that are run using thermostat run.
  • cli/src/templates/script-entrypoint-no-setup.sh: This is the script entrypoint used for initializing scripts that are run using thermostat run when the skipSetup option is enabled.
  • cli/src/templates/command.sh: This is the bash script that is copied into the /usr/local/bin/thermostat file on the host machine when Thermostat is installed.
  • cli/src/templates/docker-compose.yml: This is the template for the Docker compose file that is used to run the Thermostat services.
  • cli/src/templates/empty.tar.gz: This file is used as a placeholder for an empty archive file when the CLI is sending application data to the API but no data exists in the application.
  • cli/src/index.ts: This file contains the Yargs configuration that defines the primary CLI interface commands and options.
  • cli/src/commands/develop.ts: This file contains the code for executing the thermostat develop command.
  • cli/src/commands/run.ts: This file contains the code for executing the thermostat run command.
  • cli/src/commands/remove.ts: This file contains the code for executing the thermostat remove command.
  • cli/src/commands/init.ts: This file contains the code for executing the thermostat init command.
  • cli/src/commands/upgrade.ts: This file contains the code for executing the thermostat upgrade command.
  • cli/src/commands/upload.ts: This file contains the code for executing the thermostat upload command.
  • cli/src/commands/deploy.ts: This file contains the code for executing the thermostat deploy command.
  • cli/src/commands/entrypoint.ts: This file contains the code that runs in the main Thermostat Docker container.
  • cli/src/utils/services: This folder contains files with utility functions for managing the Thermostat services. Each service is different so you would need to look at the files individually to understand the purposes of the different functions.
  • cli/src/utils/ssh.ts: This file contains utility functions for managing SSH connections to the Thermostat API and the host machine.
  • cli/src/utils/environment.ts: This file contains utility functions for processing Thermostat environment variables.
  • cli/src/utils/setup.ts: This file contains functions that are used for bootstrapping and updating the Thermostat CLI Docker containers and performing general startup processes.
  • cli/src/utils/docker.ts: This file contains utility functions related to interfacing with the Docker daemon in order to query data and manipulate containers.
  • cli/src/utils/api.ts: This file contains utility functions for interfacing with the Thermostat API.
  • cli/src/utils/git.ts: This file contains utility functions for interacting with the Git repository that is in the code folder in Thermostat applications.
  • cli/src/utils/apps.ts: This file contains utility functions for manipulating Thermostat application data.
  • cli/src/utils/config.ts: This file contains utility functions for manipulating the global Thermostat CLI configuration data (generally stored at /var/lib/thermostat/config/config.yml).
  • cli/src/utils/compare.ts: This file contains utility functions for interfacing with the Percy visual comparison tool.
  • cli/src/utils/general.ts: This file contains generic utility functions that are not Thermostat-specific.