DOCSEARCHbyAlgolia
Submit Docs

Home Assistant CLI

repository·master·Indexed 42 days ago

https://github.com/home-assistant/cli

A command-line tool (`ha`) used to interact with the Home Assistant Supervisor. It allows users to manage core services, hardware, backups, and apps, providing subcommands for system control, network configuration, and OS management.

Tokens
29.8K
Snippets
255
Records
268
Agent score
52%

What's inside Home Assistant CLI

  1. Set up the CLI for development

    master

    To develop the CLI, you must be able to interact remotely with the Home Assistant Supervisor using the remote_api app from the developer app repository.

    1. Install and start the remote_api app.
    2. Retrieve the token from the remote_api app log.
    3. Set the SUPERVISOR_ENDPOINT and SUPERVISOR_API_TOKEN environment variables to point to your instance.

    Example:

    export SUPERVISOR_ENDPOINT=http://192.168.1.2
export SUPERVISOR_API_TOKEN=replace_this_with_remote_api_token
go run main.go info

    Note: Replace 192.168.1.2 with your actual Home Assistant instance IP address.

    export SUPERVISOR_ENDPOINT=http://192.168.1.2
export SUPERVISOR_API_TOKEN=replace_this_with_remote_api_token
go run main.go info

  2. Use the Home Assistant CLI

    master

    The Home Assistant CLI (ha) is used to interact with the Home Assistant Supervisor. The general command structure is:

    ha <subcommand> <action> [<options>]

    You can use ha help to see available commands or ha <subcommand> help for specific subcommand details.

    Example: To get raw JSON information about the Home Assistant Core:

    ha core info --raw-json
    ha core info --raw-json

  4. Install the Home Assistant CLI

    master

    The CLI is typically pre-installed on Home Assistant systems via the CLI container and is available in the device terminal when using the Home Assistant Operating System. It is automatically updated on those systems.

    Users can also access the CLI via the SSH app (available in the app store) or through community apps like the Visual Studio Code app.

  5. Guidelines for using AI when contributing to Open Home Foundation projects

    master

    The Open Home Foundation (OHF) allows the use of AI (LLMs) as tools for contributing to projects, provided there is a human in the loop. You are responsible for any content you submit.

    Key Requirements:

    • Personal Review: You must personally review and understand all AI-generated code, documentation, and text before submission. You must be able to explain every change in a pull request in your own words.
    • No Autonomous Agents: The use of autonomous agents to create pull requests or issues is strictly prohibited. Contributions that bypass issue or pull request templates or appear to be created autonomously will be closed.
    • Communication:
      • Do not use AI to generate answers to questions from maintainers. While using AI to improve grammar or clarity is permitted, the substance of your responses must be your own.
      • If you use AI to generate a pull request summary, you must verify it for technical accuracy.
      • If you include AI interaction context in comments, you must use a quote block (e.g., >) and disclose it, accompanied by your own commentary.
    • Non-native English Speakers: Using AI to improve grammar or translate comments is permitted. It is recommended to include your original text in a <details> block to help maintainers verify intent and show your effort.

  6. Use the `os` command group for Home Assistant OS management

    master

    The os command group (aliased as hassos) is specifically designed for the Home Assistant Operating System (HAOS). These commands only function on HAOS systems and are used for retrieving system information, upgrading the operating system or the OS CLI, and importing configurations from a USB stick.

    Note: The alias hassos is deprecated. You should use os instead.

    # Examples of usage
ha os info
ha os update

  7. How to handle AI-generated comments from project tools

    master

    Some OHF projects use AI tools for code reviews, issue triaging, and project management. These tools may leave automated comments on your pull requests or issues.

    How to respond:

    • Treat AI comments like any other human review comment.
    • If you believe an AI comment is incorrect, state so with a brief explanation.
    • Maintainers have the final authority on all contributions.

  8. Reference: `ha network vlan` flags

    master

    The following flags are available for the ha network vlan command to configure IP addressing and discovery protocols.

    IPv4 Configuration

    • --ipv4-address: IPv4 address in CIDR notation (e.g., 192.168.1.5/24). Can be used multiple times.
    • --ipv4-gateway: The IPv4 gateway for the interface.
    • --ipv4-method: Method for IPv4. Options: static, auto, or disabled.
    • --ipv4-nameserver: Upstream DNS server address. Use multiple times for multiple servers.
    • --ipv4-route-metric: IPv4 route metric. Lower values have higher priority.

    IPv6 Configuration

    • --ipv6-address: IPv6 address in CIDR notation (e.g., 2001:db8:85a3::8a2e:370:7334/64). Can be used multiple times.
    • --ipv6-gateway: The IPv6 gateway for the interface.
    • --ipv6-method: Method for IPv6. Options: static, auto, or disabled.
    • --ipv6-addr-gen-mode: IPv6 address generation mode. Options: eui64, stable-privacy, default-or-eui64, or default.
    • --ipv6-privacy: IPv6 privacy extensions. Options: disabled, enabled-prefer-public, enabled, or default.
    • --ipv6-nameserver: Upstream DNS server address. Use multiple times for multiple servers.
    • --ipv6-route-metric: IPv6 route metric. Lower values have higher priority. Note: The kernel accepts 0, but coerces it to 1024.

    Discovery Protocols

    • --mdns: mDNS mode. Options: default, off, resolve, or announce.
    • --llmnr: LLMNR mode. Options: default, off, resolve, or announce.
    # Example: Setting up a static IPv4 VLAN
ha network vlan eth0 10 \
  --ipv4-method static \
  --ipv4-address 192.168.10.5/24 \
  --ipv4-gateway 192.168.10.1 \
  --ipv4-nameserver 8.8.8.8 \
  --ipv4-nameserver 1.1.1.1

  9. Reference: `ha backups new` flags

    master

    The following flags are available for the ha backups new command to customize the backup process:

    FlagShorthandDescription
    --nameName of the backup
    --passwordPassword for the backup
    --uncompressedUse uncompressed archives
    --app-aApp to backup, triggers a partial backup. Use multiple times for multiple apps.
    --addons(Deprecated) Use --app instead.
    --folders-fFolders to backup, triggers a partial backup.
    --location-lWhere to put backup file (backup mount or local). Use multiple times for multiple locations. Default: .local
    --homeassistant-exclude-databaseExclude the Home Assistant database file from backup. Default: false
    --filenameName to use for the backup file
    --name string
--password string
--uncompressed
--app stringArray
--addons stringArray
--folders stringArray
--location stringArray
--homeassistant-exclude-database
--filename string

  10. Available Home Assistant CLI subcommands

    master

    The CLI provides several subcommands to manage different aspects of the Home Assistant ecosystem:

    • apps: Install, update, remove and configure Home Assistant apps
    • audio: Audio device handling
    • authentication: Authentication for Home Assistant users
    • cli: Get information, update or configure the Home Assistant cli backend
    • core: Provides control of the Home Assistant Core
    • dns: Get information, update or configure the Home Assistant DNS server
    • docker: Docker backend specific for info and OCI configuration
    • hardware: Provides hardware information about your system
    • help: Help about any command
    • host: Control the host/system that Home Assistant is running on
    • info: Provides a general Home Assistant information overview
    • multicast: Get information, update or configure the Home Assistant Multicast
    • network: Network specific for updating, info and configuration imports
    • observer: Get information, update or configure the Home Assistant observer
    • os: Operating System specific for updating, info and configuration imports
    • resolution: Resolution center of Supervisor, show issues and suggest solutions
    • backups: Create, restore and remove backups
    • supervisor: Monitor, control and configure the Home Assistant Supervisor
    apps
audio
authentication
cli
core
dns
docker
hardware
help
host
info
multicast
network
observer
os
resolution
backups
supervisor

  11. Configure Home Assistant CLI global options

    master

    Global modifiers can be passed as CLI flags or via environment variables prefixed with SUPERVISOR_.

    FlagEnvironment VariableDescription
    --api-tokenSUPERVISOR_API_TOKENHome Assistant Supervisor API token
    --configSUPERVISOR_CONFIGOptional config file (default is $HOME/.homeassistant.yaml)
    --endpointSUPERVISOR_ENDPOINTEndpoint for Home Assistant Supervisor (default is supervisor)
    --log-levelSUPERVISOR_LOG_LEVELLog level (defaults to Warn)
    --no-progressSUPERVISOR_NO_PROGRESSDisable the progress spinner
    --raw-jsonSUPERVISOR_RAW_JSONOutput raw JSON from the API
    -h, --helpN/AHelp for the ha command
    --api-token string   Home Assistant Supervisor API token
--config string      Optional config file (default is $HOME/.homeassistant.yaml)
--endpoint string    Endpoint for Home Assistant Supervisor (default is 'supervisor')
-h, --help               help for ha
--log-level string   Log level (defaults to Warn)
--no-progress        Disable the progress spinner
--raw-json           Output raw JSON from the API