Homey CLI
Complete reference of every Homey CLI command, option, and workflow.
The Homey command-line interface (CLI) 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 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 — everything under
homey app …, for building and shipping apps.Top-level Commands — direct access to the Homey API via
homey api ….Additional Commands — authentication, Homey selection, and other utilities.
At the bottom you will find a section on global options, shell completion, environment variables and a troubleshooting checklist.
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
homey app createInteractive 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 for a walkthrough of your first app.
Adding a new Driver
homey app driver createAdds 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
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
Register a device firmware update against a driver. Supported for Zigbee and Z-Wave drivers.
--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
Adding a new Flow card for a Driver
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
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
Interactive wizard that scaffolds a new dashboard widget, including the HTML/CSS/JS files, widget.compose.json, and the light/dark preview images.
Adding a new Discovery Strategy
Interactive wizard that adds a discovery strategy (mDNS-SD, SSDP, or MAC) to .homeycompose/discovery/.
Install TypeScript utilities
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 for details.
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.
Build a Homey app for publishing
Create a production build of your app. Compiles TypeScript (if applicable), runs Homey Compose, and produces the tarball that install and publish use.
--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
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
Validates the app manifest, assets, and compose files. run, install, and publish call this automatically.
--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.
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
Run a Homey app in development mode
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.
--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
Install a Homey app
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.
--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
Opens https://tools.developer.homey.app/apps/app/<app-id> in your default browser.
Publish a Homey app to the Homey App Store
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 for the full submission flow.
--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). Most developers can ignore them.
Update a Homey app's version
Bumps version in app.json. Homey apps use semver.
<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
Translate your app with OpenAI
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).
--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.
AI translations vary in quality. Always review the diff before committing.
Review your app with AI
Runs an AI review of your app against the Homey App Store Guidelines before you submit for certification. The reviewer analyzes app.json, driver metadata, and every image (app icon, driver images, and widget previews). It also checks your app’s code for obvious bugs and security issues. Returns a verdict of approve, request_changes, or reject, plus findings grouped by severity (blocker, warning, suggestion).
--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
Open the App Store page of your app
Opens https://homey.app/a/<app-id> in your default browser.
Dependency utilities (Python apps)
Manages Python dependencies for Python-based Homey apps. All subcommands accept --find-links and --docker-socket-path.
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
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
homey app dependencies remove
Removes libraries. Use the leading dev keyword to remove from dev dependencies.
homey app dependencies list
Prints all installed dependencies with their resolved versions.
Top-level Commands
Direct Homey API commands
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
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
homey api diagnose
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.
--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
Aliases: homey api call, homey api request. Perform an arbitrary Homey API request. Useful for quick debugging, scripting, or exploring the API.
--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
homey api <manager> <operation>
Every manager in the Homey API is exposed as its own subcommand. For example:
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
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
Clears the stored session from ~/.homey/.
Show the current logged-in user
Prints the first name, last name, and email of the authenticated Athom user. Verified developers are marked as such.
List your Homeys
Lists every Homey linked to the authenticated account with ID, name, platform, version, region, and role. Sorted by state (online Homeys first).
Example
Select a Homey
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
Prints the currently selected Homey. Exits with a helpful message when nothing is selected.
Unselect the active Homey
Clears the currently selected Homey so subsequent commands will prompt for one.
Open Homey Developer Tools
Opens https://tools.developer.homey.app in your default browser.
Open the Homey Apps SDK documentation
Opens https://apps.developer.homey.app in your default browser.
Global options
Every command supports these:
--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:
--json
Emit machine-readable JSON. Combine with your own parsing or with --jq.
--jq "<expr>"
Filter the JSON output with a jq 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.
Add the output to your shell startup file:
After sourcing, homey <TAB> completes commands, subcommands, and options. homey api <TAB> additionally completes manager names discovered from the Homey API.
Environment variables
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 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.
Last updated
Was this helpful?