ha-integration-scaffold

Home Assistant Integration Scaffold

Generate boilerplate files for a new Home Assistant custom integration.

Arguments: $ARGUMENTS

Important:

• First argument: domain (kebab-case identifier, e.g., my-integration)
• Optional flags:
  • --with-config-flow: Include config_flow.py for UI-based configuration
  • --platforms: Comma-separated list of platforms (e.g., sensor,switch,light)

Your Task

Follow these steps to scaffold the Home Assistant integration:

Step 1: Parse Arguments

Extract from $ARGUMENTS:

• Domain: The first argument (kebab-case identifier, e.g., my-integration)
• Config Flow Flag: Check for --with-config-flow (optional)
• Platforms: Extract from --platforms sensor,switch,... (optional)

Examples:

• /ha-integration-scaffold my-device
• /ha-integration-scaffold weather-api --with-config-flow
• /ha-integration-scaffold smart-lights --platforms sensor,switch,light
• /ha-integration-scaffold iot-hub --with-config-flow --platforms sensor,binary_sensor

Step 2: Validate Domain

• Must be kebab-case (lowercase letters and hyphens only)
• Convert underscores to hyphens if needed
• Store as both kebab-case (domain) and snake_case (for Python module name)
  • Domain: my-integration
  • Python module: my_integration

Step 3: Generate manifest.json

Create custom_components/<domain>/manifest.json with:

{
  "domain": "domain-name",
  "name": "Domain Name",
  "codeowners": ["@username"],
  "config_entries_only": true,
  "documentation": "https://github.com/username/ha-domain-name",
  "homeassistant": "2024.1.0",
  "iot_class": "cloud_polling",
  "issue_tracker": "https://github.com/username/ha-domain-name/issues",
  "requirements": [],
  "version": "1.0.0"
}

Key points:

• domain: Use the kebab-case version (e.g., my-integration)
• name: Title-case version (e.g., My Integration)
• homeassistant: Set to a recent stable version (e.g., 2024.1.0)
• iot_class: Choose appropriate class:
  • local_polling: Local network, polling
  • cloud_polling: Cloud API, polling
  • local_push: Local network, push updates
  • cloud_push: Cloud API, push updates
• config_entries_only: Set to true (required for modern integrations)
• requirements: Empty array initially (add dependencies as needed)