> For the complete documentation index, see [llms.txt](https://apps.developer.homey.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apps.developer.homey.app/the-basics/getting-started/homey-cli.md).

# Homey CLI

The [Homey command-line interface (CLI)](/the-basics/getting-started/homey-cli.md) is the tool you need for Homey App development. It scaffolds new apps, runs them against a Homey (locally in a Docker container or on the Homey itself), validates them against App Store requirements, and publishes them. Read the [getting started guide](/the-basics/getting-started.md) first if you have not installed the CLI yet.

This page is a full reference of every command, subcommand and option. Commands are grouped in three sections:

* [**App Commands**](#app-commands) — everything under `homey app …`, for building and shipping apps.
* [**Top-level Commands**](#top-level-commands) — direct access to the Homey API via `homey api …`.
* [**Additional Commands**](#additional-commands) — authentication, Homey selection, and other utilities.

At the bottom you will find a section on [**global options**](#global-options), [**shell completion**](#shell-completion), [**environment variables**](#environment-variables) and a [**troubleshooting**](#troubleshooting) checklist.

{% hint style="info" %}
All `homey app …` commands accept `--path <dir>` (or `-p`) to point at a Homey app that is not in the current working directory. When omitted, the CLI uses `process.cwd()`.
{% endhint %}

## App Commands

The Homey CLI has commands that help when developing a Homey app. These commands all start with `homey app` and expect a Homey app in the current working directory.

### Create a new Homey app

```bash
homey app create
```

Interactive wizard that scaffolds a new empty Homey app. Prompts you for the App ID, name, description, category, color, and language. Creates `app.json`, the `.homeycompose/` layout, `README.md`, locale files, and installs dependencies.

Read the [getting started guide](/the-basics/getting-started.md) for a walkthrough of your first app.

### Adding a new Driver

```bash
homey app driver create
```

Adds a new driver to your Homey app. Prompts you for the driver ID, display name, class, capabilities, and pairing method. Generates the driver folder under `drivers/<id>/` including `driver.js`, `device.js`, and `driver.compose.json`.

### Change the capabilities of a Driver

```bash
homey app driver capabilities
```

Interactive editor that lists every available Homey capability and lets you toggle which ones the driver exposes. Writes the result back to the driver's `driver.compose.json`.

### Add/update firmware updates of a Driver

```bash
homey app driver firmware --driver <path> --firmware <file> [--firmware <file>...]
```

Register a device firmware update against a driver. Supported for Zigbee and Z-Wave drivers.

| Option       | Type           | Description                                                                |
| ------------ | -------------- | -------------------------------------------------------------------------- |
| `--driver`   | string         | Path to the driver folder that the firmware update should be attached to.  |
| `--firmware` | string (array) | Path to a firmware file. Repeat to attach multiple firmware files at once. |

**Example**

```bash
homey app driver firmware \
  --driver ./drivers/my-plug \
  --firmware ./firmware/v1.2.3.bin
```

### Adding a new Flow card for a Driver

```bash
homey app driver flow
```

Interactive wizard for creating a Flow card scoped to a specific driver. Prompts you for the card type (trigger, condition, or action), title, tokens, and generates the card under `drivers/<id>/driver.flow.compose.json`.

### Adding a new Flow card

```bash
homey app flow create
```

Same wizard as above, but for app-level Flow cards (not tied to a driver). Writes the card to `.homeycompose/flow/<type>/<id>.json`.

### Adding a new Widget

```bash
homey app widget create
```

Interactive wizard that scaffolds a new [dashboard widget](/the-basics/widgets.md), including the HTML/CSS/JS files, `widget.compose.json`, and the light/dark preview images.

### Adding a new Discovery Strategy

```bash
homey app discovery create
```

Interactive wizard that adds a [discovery strategy](https://github.com/athombv/gitbook-apps/tree/master/guides/tools/discovery-mdns-sd.md) (mDNS-SD, SSDP, or MAC) to `.homeycompose/discovery/`.

### Install TypeScript utilities

```bash
homey app add-types
```

Installs the Homey Apps SDK type declarations and configures `jsconfig.json` / `tsconfig.json` so your IDE and TypeScript compiler can type-check your app. Read the [TypeScript guide](/guides/tools/typescript.md) for details.

### Add GitHub workflows

```bash
homey app add-github-workflows
```

Copies ready-made GitHub Actions into `.github/workflows/` for validating, versioning, and publishing your app on push. See [Automating within GitHub Actions](/app-store/publishing.md#automating-within-github-actions).

### Build a Homey app for publishing

```bash
homey app build [options]
```

Create a production build of your app. Compiles TypeScript (if applicable), runs Homey Compose, and produces the tarball that `install` and `publish` use.

| Option                 | Type   | Description                                                                                                        |
| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
| `--docker-socket-path` | string | Path to the Docker socket. Useful when Docker is running on a non-standard socket (Colima, Rancher Desktop, etc.). |
| `--find-links`         | string | Additional location to search for candidate Python package distributions (Python apps only).                       |

### Migrate to Homey Compose

```bash
homey app compose
```

Splits a legacy monolithic `app.json` into the `.homeycompose/` file layout. Existing files are preserved. Only useful for apps that predate Homey Compose.

### Validate a Homey app

```bash
homey app validate [--level debug|publish|verified] [options]
```

Validates the app manifest, assets, and compose files. `run`, `install`, and `publish` call this automatically.

| Option                 | Type   | Default   | Description                                                     |
| ---------------------- | ------ | --------- | --------------------------------------------------------------- |
| `--level`, `-l`        | string | `publish` | Validation strictness. See table below.                         |
| `--docker-socket-path` | string | —         | Path to the Docker socket.                                      |
| `--find-links`         | string | —         | Additional location to search for Python package distributions. |

| Level      | When to use                                                                                                                                                             |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `debug`    | During development. Optional fields such as `images`, `brandColor`, and `category` are not required.                                                                    |
| `publish`  | Required to publish to the Homey App Store for Homey Pro.                                                                                                               |
| `verified` | Required for verified developers and Homey Cloud. Adds requirements such as `platforms`, `connectivity`, and `support`. Applied by default when you are a verified dev. |

**Examples**

```bash
homey app validate
homey app validate --level verified
```

### Run a Homey app in development mode

```bash
homey app run [options]
```

Runs and debugs your app. By default it runs in a local Docker container that exposes the app to your selected Homey. For Homey Pro (2016—2019) the app is automatically uploaded to the Homey and run remotely. Console output streams to your terminal. Quitting (`Ctrl+C`) uninstalls the app from Homey.

| Option                 | Type    | Default  | Description                                                                                                                                  |
| ---------------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `--clean`, `-c`        | boolean | `false`  | Delete all userdata, paired devices, and settings before running. Useful when testing pairing flows.                                         |
| `--remote`, `-r`       | boolean | `false`  | Force the app to run on the Homey instead of locally in Docker. Automatically enabled on Homey Pro (2016—2019).                              |
| `--skip-build`, `-s`   | boolean | `false`  | Skip the build step. Use only if you know the build output is already up-to-date.                                                            |
| `--link-modules`, `-l` | string  | `""`     | Comma-separated list of local Node.js modules to link into the runner. Docker mode only.                                                     |
| `--network`, `-n`      | string  | `bridge` | Docker network mode. Must match a name from `docker network ls`. Use `host` if your app needs LAN discovery from the host. Docker mode only. |
| `--docker-socket-path` | string  | —        | Path to the Docker socket.                                                                                                                   |
| `--find-links`         | string  | —        | Additional location to search for Python package distributions.                                                                              |

**Examples**

```bash
homey app run
homey app run --clean
homey app run --remote
homey app run --link-modules ../my-library,../another-library
homey app run --network host
```

### Install a Homey app

```bash
homey app install [options]
```

Builds the app and installs it on the currently selected Homey. Unlike `homey app run`, this leaves the app installed after the command exits and does not stream logs. Good for long-running tests.

| Option               | Type    | Default | Description                                                          |
| -------------------- | ------- | ------- | -------------------------------------------------------------------- |
| `--clean`, `-c`      | boolean | `false` | Delete all userdata, paired devices, and settings before installing. |
| `--skip-build`, `-s` | boolean | `false` | Skip the build step.                                                 |

### Open your app in Homey Developer Tools

```bash
homey app manage
```

Opens `https://tools.developer.homey.app/apps/app/<app-id>` in your default browser.

### Publish a Homey app to the Homey App Store

```bash
homey app publish [options]
```

Validates, builds, and uploads your app to the Homey App Store. You will be prompted to bump the version and add a changelog if you have not already. Read the [publishing guide](/app-store/publishing.md) for the full submission flow.

| Option                 | Type   | Description                                                     |
| ---------------------- | ------ | --------------------------------------------------------------- |
| `--docker-socket-path` | string | Path to the Docker socket.                                      |
| `--find-links`         | string | Additional location to search for Python package distributions. |

Both options are passed through to the internal build step (see [`homey app build`](#build-a-homey-app-for-publishing)). Most developers can ignore them.

### Update a Homey app's version

```bash
homey app version <next> [--changelog.<lang> "..."] [--commit]
```

Bumps `version` in `app.json`. Homey apps use [semver](https://semver.org/).

| Argument / Option    | Type              | Description                                                                                     |
| -------------------- | ----------------- | ----------------------------------------------------------------------------------------------- |
| `<next>`             | string (required) | `patch`, `minor`, `major`, or an explicit semver like `2.0.0`.                                  |
| `--changelog.<lang>` | string            | Changelog text for a specific language. Repeat to translate. Written to `.homeychangelog.json`. |
| `--commit`           | boolean           | Create a git commit and matching tag for the new version.                                       |

**Examples**

```bash
homey app version patch
homey app version minor --commit
homey app version 2.0.0 \
  --changelog.en "Added support for the Awesome Widget" \
  --changelog.nl "Ondersteuning voor de Awesome Widget toegevoegd"
```

### Translate your app with OpenAI

```bash
homey app translate [options]
```

Uses the OpenAI API to translate your app's `.json` fields and `README.txt` into every language your app targets. Requires `OPENAI_API_KEY` to be set (or passed with `--api-key`).

| Option        | Type   | Default            | Description                                                                          |
| ------------- | ------ | ------------------ | ------------------------------------------------------------------------------------ |
| `--languages` | string | app's target langs | Comma-separated list of target language codes (e.g. `nl,de,fr`).                     |
| `--api-key`   | string | `$OPENAI_API_KEY`  | OpenAI API key. Prefer setting the environment variable.                             |
| `--model`     | string | `gpt-4o`           | OpenAI model to use.                                                                 |
| `--file`      | string | —                  | Absolute path to a single file to translate. Useful when you only edited one string. |

{% hint style="warning" %}
AI translations vary in quality. Always review the diff before committing.
{% endhint %}

### Review your app with AI

```bash
homey app review [options]
```

Runs an AI review of your app against the [Homey App Store Guidelines](/app-store/guidelines.md) before you submit for certification. The reviewer analyzes `app.json`, driver metadata, and every image (app icon, driver images, widget previews). Returns a verdict of `approve`, `request_changes`, or `reject`, plus findings grouped by severity (`blocker`, `warning`, `suggestion`).

| Option            | Type    | Default         | Description                                                                                                             |
| ----------------- | ------- | --------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `--type`          | string  | `new`           | `new` for a first submission, `update` if the app is already live.                                                      |
| `--model`         | string  | Athom's default | Model in `<provider>/<model>` form. Supported providers: `openai`, `anthropic`. Any non-default model prints a warning. |
| `--json`          | boolean | `false`         | Emit machine-readable JSON instead of pretty output.                                                                    |
| `--verbose`, `-v` | boolean | `false`         | Print token counts, model info, and duration.                                                                           |

The command reads optional app-specific instructions from a `.homeyreview.md` file at the app root. Requires `OPENAI_API_KEY` (for OpenAI models) or `ANTHROPIC_API_KEY` (for Anthropic models). Exits with code 1 if the verdict is `reject`.

**Examples**

```bash
export OPENAI_API_KEY="sk-..."
homey app review
homey app review --type update
homey app review --json > review.json
homey app review --model anthropic/claude-opus-4-7 --verbose
```

### Open the App Store page of your app

```bash
homey app view
```

Opens `https://homey.app/a/<app-id>` in your default browser.

### Dependency utilities (Python apps)

```bash
homey app dependencies <install|add|remove|list>
```

Manages Python dependencies for [Python-based Homey apps](https://github.com/athombv/gitbook-apps/tree/master/guides/programming-languages/python.md). All subcommands accept `--find-links` and `--docker-socket-path`.

#### `homey app dependencies install`

```bash
homey app dependencies install
```

Installs libraries listed in the app's dependency file and pre-compiles them for distribution with the app.

#### `homey app dependencies add`

```bash
homey app dependencies add [dev] <package>[@<version>] [...]
```

Adds one or more libraries as a dependency. When run with the leading `dev` keyword, packages are added as development-only dependencies. Adding a package that is already installed updates its version constraint.

**Examples**

```bash
homey app dependencies add requests
homey app dependencies add "numpy>=1.26,<2.0"
homey app dependencies add dev pytest
```

#### `homey app dependencies remove`

```bash
homey app dependencies remove [dev] <package> [...]
```

Removes libraries. Use the leading `dev` keyword to remove from dev dependencies.

#### `homey app dependencies list`

```bash
homey app dependencies list
```

Prints all installed dependencies with their resolved versions.

## Top-level Commands

### Direct Homey API commands

```bash
homey api <subcommand>
```

Use `homey api` to inspect and call the Homey API directly. Subcommands:

* `homey api schema` — inspect available managers and operations.
* `homey api diagnose` — diagnose local discovery / connectivity.
* `homey api raw` — perform an arbitrary HTTP request against the Homey.
* `homey api <manager> <operation>` — call a manager method (e.g. `homey api devices open-device`). Manager commands are generated automatically from the Homey API schema.

#### `homey api schema`

```bash
homey api schema [--json] [--jq "<expr>"]
```

Prints a human-readable overview of every available API manager and its operations. With `--json` you get the raw schema, which you can filter with `--jq`.

**Examples**

```bash
homey api schema
homey api schema --json --jq '.managers | keys'
```

#### `homey api diagnose`

```bash
homey api diagnose [--homey-id <id>] [--json] [--jq "<expr>"]
```

Tries every discovery strategy (local address, mDNS, cloud tunnel, WebSocket relay) against the selected Homey and prints which ones work, how long they take to respond, and which one is used. Exits with code 0 if at least one strategy is available, 1 otherwise. Great when `homey app run` cannot reach your Homey.

| Option       | Description                                                  |
| ------------ | ------------------------------------------------------------ |
| `--homey-id` | Diagnose a cached Homey by ID instead of the selected Homey. |
| `--json`     | Output the diagnosis as JSON.                                |
| `--jq`       | Filter JSON output with a jq expression.                     |

#### `homey api raw`

```bash
homey api raw --path <api-path> [--method GET|POST|PUT|...] [options]
```

Aliases: `homey api call`, `homey api request`. Perform an arbitrary Homey API request. Useful for quick debugging, scripting, or exploring the API.

| Option           | Type    | Default | Description                                                                                            |
| ---------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------ |
| `--path`         | string  | —       | Required. Homey API path, must start with `/` (e.g. `/api/manager/system/`).                           |
| `--method`, `-X` | string  | `GET`   | HTTP method. Case-insensitive.                                                                         |
| `--header`, `-H` | string  | —       | Request header in `"name:value"` form. Repeatable.                                                     |
| `--body`         | string  | —       | Request body. Inline JSON, or `@path/to/file.json` to load from disk.                                  |
| `--request-json` | boolean | `true`  | Encode the request body as JSON. Disable for raw bodies.                                               |
| `--include`      | boolean | `false` | Print status line and response headers in addition to the body.                                        |
| `--verbose`      | boolean | `false` | Print the resolved request URL, method, headers, and timing to stderr. Sensitive headers are redacted. |
| `--token`        | string  | —       | Use a session token instead of the selected Homey. Requires `--address` or `--homey-id`.               |
| `--address`      | string  | —       | Homey base URL for token mode (e.g. `http://192.168.1.100`).                                           |
| `--homey-id`     | string  | —       | Target a cached Homey by ID.                                                                           |
| `--timeout`      | number  | `30000` | Request timeout in milliseconds.                                                                       |
| `--json`         | boolean | `false` | Force JSON output even when the response is a plain string.                                            |
| `--jq`           | string  | —       | Filter JSON output with a jq expression.                                                               |

**Examples**

```bash
homey api raw --path /api/manager/system/
homey api raw --path /api/manager/system/ --jq '.value.homeyVersion'

homey api raw \
  -X POST \
  --path /api/manager/flow/flow \
  --body '{"name":"Test flow"}'

homey api raw \
  -X POST \
  --path /api/manager/flow/flow \
  --body @./flow.json --verbose
```

#### `homey api <manager> <operation>`

Every manager in the Homey API is exposed as its own subcommand. For example:

```bash
homey api devices open-device --id <device-id>
```

Run `homey api --help` for the list of available managers, or `homey api schema` to inspect operations. Each manager command inherits `--homey-id`.

## Additional Commands

### Login with an Athom account

```bash
homey login
```

Opens the OAuth2 dialog in your default browser and stores the resulting session in `~/.homey/`. Required before `homey app run`, `install`, or `publish`. For CI/CD, set `HOMEY_PAT` instead of running `homey login`.

### Logout the current user

```bash
homey logout
```

Clears the stored session from `~/.homey/`.

### Show the current logged-in user

```bash
homey whoami [--json] [--jq "<expr>"]
```

Prints the first name, last name, and email of the authenticated Athom user. Verified developers are marked as such.

### List your Homeys

```bash
homey list [--json] [--jq "<expr>"]
```

Lists every Homey linked to the authenticated account with ID, name, platform, version, region, and role. Sorted by state (online Homeys first).

**Example**

```bash
homey list --json --jq '.[].name'
```

### Select a Homey

```bash
homey select [--id <id> | --name <name>]
```

Sets the active Homey for `homey app run`, `homey app install`, and every `homey api` command. Without arguments, an interactive picker is shown. Provide `--id` or `--name` to select non-interactively (useful in scripts).

#### `homey select current`

```bash
homey select current [--json] [--jq "<expr>"]
```

Prints the currently selected Homey. Exits with a helpful message when nothing is selected.

### Unselect the active Homey

```bash
homey unselect
```

Clears the currently selected Homey so subsequent commands will prompt for one.

### Open Homey Developer Tools

```bash
homey tools
```

Opens `https://tools.developer.homey.app` in your default browser.

### Open the Homey Apps SDK documentation

```bash
homey docs
```

Opens `https://apps.developer.homey.app` in your default browser.

## Global options

Every command supports these:

| Option            | Description                                                                               |
| ----------------- | ----------------------------------------------------------------------------------------- |
| `--help`          | Show help for the current command, including all options and subcommands.                 |
| `--version`, `-v` | Print the installed CLI version.                                                          |
| `--path`, `-p`    | Available on every `homey app …` command. Points at the app directory. Defaults to `cwd`. |

Commands that produce structured output additionally support:

| Option          | Description                                                                         |
| --------------- | ----------------------------------------------------------------------------------- |
| `--json`        | Emit machine-readable JSON. Combine with your own parsing or with `--jq`.           |
| `--jq "<expr>"` | Filter the JSON output with a [jq](https://jqlang.org/) expression before printing. |

Commands that currently support `--json`/`--jq`: `homey whoami`, `homey list`, `homey select current`, `homey api schema`, `homey api diagnose`, `homey api raw`, and (partially) `homey app review`.

## Shell completion

The CLI ships tab-completion for `bash`, `zsh`, and `fish` via yargs.

```bash
# Print the completion script for your current shell
homey completion
```

Add the output to your shell startup file:

{% tabs %}
{% tab title="zsh" %}

```bash
homey completion >> ~/.zshrc
source ~/.zshrc
```

{% endtab %}

{% tab title="bash" %}

```bash
homey completion >> ~/.bashrc
source ~/.bashrc
```

{% endtab %}

{% tab title="fish" %}

```bash
homey completion > ~/.config/fish/completions/homey.fish
```

{% endtab %}
{% endtabs %}

After sourcing, `homey <TAB>` completes commands, subcommands, and options. `homey api <TAB>` additionally completes manager names discovered from the Homey API.

## Environment variables

| Variable            | Used by                                   | Description                                                                        |
| ------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------- |
| `HOMEY_PAT`         | Every command that talks to Athom Cloud   | Personal Access Token. Bypasses the interactive login flow. Recommended for CI/CD. |
| `OPENAI_API_KEY`    | `homey app translate`, `homey app review` | OpenAI API key. Required unless you pass `--api-key`.                              |
| `ANTHROPIC_API_KEY` | `homey app review`                        | Anthropic API key. Required when `--model anthropic/…` is used.                    |

Persistent state (session tokens, cached Homeys, selected Homey) lives in `~/.homey/`. Delete this directory to fully reset the CLI.

## Troubleshooting

**"No Homey is currently selected."**\
Run `homey select` (interactive) or `homey select --name "<homey>"`. Check the current selection with `homey select current`.

**"Cannot connect to the Docker daemon."**\
`homey app run`, `build`, `validate`, and `publish` require Docker to be running on Homey Pro (Early 2023) and later. Start Docker Desktop / Colima / Rancher Desktop. If Docker is running on a non-default socket, pass `--docker-socket-path <path>`.

**Cannot reach the Homey from Docker.**\
Try `homey api diagnose` to see which discovery strategies work. Running with `homey app run --network host` (macOS/Linux) often helps when local mDNS discovery is required.

**Homey Pro (2016—2019) cannot use Docker.**\
Pass `--remote` (or let the CLI do it automatically) to upload and run the app directly on the Homey. Console output still streams to your terminal but rebuilds are slower than in Docker mode.

**Login flow doesn't open a browser.**\
Copy the URL from the terminal into your browser manually.

**`homey app publish` rejects the app because of validation errors.**\
Run `homey app validate --level publish` (or `--level verified` for verified developers) locally and fix each error. See the [publishing guide](/app-store/publishing.md#requirements) for the full requirements matrix.

**`homey app review` fails with a missing-key error.**\
Set `OPENAI_API_KEY` (for OpenAI models) or `ANTHROPIC_API_KEY` (for Anthropic models) in your shell before running the command.

**Reset the CLI to a clean state.**\
Remove `~/.homey/` to clear all sessions, cached Homeys, and the current selection.