Getting Started

How to create your first Homey app.

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.

1. Install Homey CLI

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.

To use the Homey CLI you will need to have the following prerequisites installed:

• Node.js v18 or higher

• Docker, for Homey Cloud and Homey Pro (Early 2023)

You can download the official Node.js installer from the Node.js website. 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.

If you want to create apps that run in our Cloud environment, you will also need to have Docker running on your machine to test your apps. You can download the Docker installer from the Docker 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.

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 --no-optional homey

You may need superuser rights to install packages globally.

2. Create a Homey app

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.

Note: the Homey or Athom name cannot be used in your app ID.

After answering the questions the CLI will create a new Homey app in a directory named after your chosen Homey App ID. The rest of this guide expects that your current working directory is the Homey App folder so you should change your directory to it:

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.

3. Run the Homey app

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 order to see this basic app at work let's run it on a Homey. 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.

Useful commands

A number of commands which might be useful are listed below:

• Login with a different account using: homey logout/homey login

• Switch to a different Homey using: homey select

• Run a Homey App in development mode without keeping your command-line window open: homey app install

• Publish 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

What's Next

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.