Getting Started
This guide is dedicated to getting you up and running with Homey App development within about 15 minutes. Even if you have no previous experience with the tools being used, this guide should have you covered.
We recommend installing a Node.js version using the Node Version Manager (NVM). This tool allows you to easily install and switch between different Node.js versions. Alternatively you can download the official Node.js installer from the Node.js website.
By installing Node.js you have gained access to the Node Package Manager (NPM). This is a command-line tool that manages dependencies of Node.js projects. NPM allows you to install Homey CLI with a single command.
The Homey command-line interface (CLI) is the tool you need for Homey App development. It enables you to create and run apps on Homey for development and debugging purposes. Additionally, it contains various utilities that make Homey App development faster and easier.
Open a command line and execute the following command. This installs the Homey CLI globally on your system and exposes the homey command.
npm install --global homey
You may need superuser rights to install packages globally.
After installing the Homey CLI you can use the homey app create command to create a basic project directory for your Homey App. This command will start an interactive prompt that asks a few questions such as what the ID of your app should be.
homey app create
The ID of your app should be in "reverse domain name notation" so if you're creating a Homey App for https://solarpanels.acme.org, the ID should be org.acme.solarpanels.
After answering the questions the CLI will create a new project directory named after your chosen Homey App ID.
cd org.acme.solarpanels
The project directory will contain a number of files and folders required for your Homey App to run on Homey. Don't be scared by this, you don't need to understand what all these files and folders mean at this point, we will explain the purpose of all the files and folders in the next section.
For sake of brevity, this guide will not cover what a Homey App is made off. If you are interested in what files and folders homey app create just created, you can read the App guide.
Now you should have a very basic Homey App automatically generated by Homey CLI. In just a few steps we can upload and run this Homey App on a Homey to see it at work.
First, make sure that Homey is either:
directly connected to your PC/laptop over USB, or
connected to the same Wi-Fi network as the PC/laptop you are working on.
From within your Homey App project directory, run the following command to start uploading your Homey App to Homey.
homey app run
If this is the first time you are running a Homey App on Homey a browser window will open that will ask you to login with your Athom account.
After you are logged in Homey CLI presents you with a list of available Homeys connected to your Athom account in the command-line window. Select the Homey on which you want to run the Homey App and it will start uploading and running automatically.
While the Homey App is running it will print debug logging to the command-line window. In order to quit running the Homey App, press CTRL + C and it will be uninstalled.
A number of commands which might be useful are listed below:
Login with a different account using:
homey logout/homey loginSwitch to a different Homey using:
homey selectRun a Homey App in development mode without keeping your command-line window open:
homey app installPublish a Homey App to the Homey App Store:
homey app publish
If you want to learn about all other functionalities provided by Homey CLI use the --help flag to list all possible commands.
homey --help
To see sub-commands, you can type:
homey app --help
You're off to a great start, after creating and running your Homey App there is a lot more to discover. Homey Apps can offer a lot of functionality for Homey users, for example with Flows and Devices. Continue reading The Basics to see what is possible and extend your Homey App to your liking.
