Home Assistant Command-Line Arguments: Complete Guide to CLI Options

Home Assistant supports over 15 command-line arguments including --config for custom configuration paths, --recovery-mode for safe startup, --debug for verbose logging, and --skip-pip to bypass package installation.

Home Assistant, the popular open-source home automation platform hosted at home-assistant/core, provides a flexible command-line interface defined in homeassistant/__main__.py. The get_arguments() function constructs an argparse.ArgumentParser that processes all startup options before the core event loop begins. Understanding these CLI flags allows administrators to customize configuration directories, control logging behavior, manage Python dependencies, and execute maintenance scripts without modifying core files.

Core Configuration Arguments

The foundational arguments control where Home Assistant looks for configuration files and basic runtime information.

Configuration Path and Version

The -c or --config argument specifies the directory containing configuration.yaml and other runtime files. According to the source in homeassistant/__main__.py, this path resolves relative to the current working directory and passes through ensure_config_path() for validation.

hass -c /srv/hass/config

The --version flag triggers an immediate version print using action="version" and exits without starting the server, referencing __version__ from the core constants.

Runtime Mode Arguments

These flags alter how Home Assistant initializes its services and integrations.

Recovery and Debug Modes

The --recovery-mode flag starts Home Assistant in a minimal safe mode that skips most integrations, allowing administrators to fix broken configurations without loading problematic components. This boolean flag stores in the RuntimeConfig object (lines 196-208 in __main__.py).

The --debug flag enables comprehensive debug logging and runs the event loop in diagnostic mode, providing detailed stack traces and async operation visibility.

Automatic UI Launch

When using --open-ui, Home Assistant automatically opens the web interface in the default browser after the server finishes initialization, eliminating the need to manually navigate to localhost:8123.

Package Management Arguments

Home Assistant automatically installs required Python packages on startup, but these arguments provide granular control over this behavior.

Skipping Pip Installation

The --skip-pip boolean flag prevents Home Assistant from running pip install for any required packages during startup. This proves useful in containerized environments where dependencies are pre-installed or when running offline.

Alternatively, --skip-pip-packages accepts a comma-separated list of specific package names to exclude from automatic installation while allowing others to update normally:

hass --skip-pip-packages psutil,pyjwt

These values populate the skip_pip and skip_pip_packages fields in RuntimeConfig, which the runner module evaluates before importing integrations.

Logging and Output Arguments

The logging subsystem offers extensive customization through CLI flags processed by the runner module before the event loop starts.

Verbosity and File Output

The -v or --verbose flag enables extra verbose logging, adding timestamps, thread information, and detailed tracebacks to the log output. This differs from --debug by focusing on log formatting rather than runtime behavior.

The --log-file argument redirects logs from the default home-assistant.log to a custom path:

hass --log-file /var/log/hass.log

Rotation and Color Control

For long-running instances, --log-rotate-days enables daily log rotation, maintaining only the specified number of days of history. This prevents disk space exhaustion from growing log files.

The --log-no-color flag disables ANSI color codes in terminal output, essential when piping logs to files or systems that don't support color formatting.

Script Execution and Advanced Options

Home Assistant embeds several maintenance utilities accessible via the CLI.

Running Embedded Scripts

The --script argument followed by a script name and its arguments executes one of the embedded utilities in homeassistant/scripts/ without starting the full Home Assistant server:

hass --script check_config --config /srv/hass/config

Common scripts include check_config for validating YAML configurations and ensure_config for initializing configuration directories. The argparse.REMAINDER action captures all subsequent arguments and passes them unchanged to the script.

OS Validation Bypass

The --ignore-os-check flag bypasses the operating system validation that normally restricts Home Assistant to Linux, macOS, or Windows Subsystem for Linux (WSL). This allows execution on unsupported platforms for development or testing purposes.

Practical Usage Examples

These combinations demonstrate common administrative tasks using the CLI arguments defined in homeassistant/__main__.py:

# Start with custom config and debug logging

hass -c /srv/hass/config --debug

# Recovery mode for fixing broken configurations

hass --recovery-mode

# Skip specific packages and use custom log location

hass --skip-pip-packages psutil,pyjwt --log-file /var/log/hass.log

# Validate configuration without starting server

hass --script check_config -c /srv/hass/config

# Verbose logging with rotation and no color codes

hass -v --log-rotate-days 7 --log-no-color

Summary

• Configuration control: Use -c or --config to specify custom configuration directories, with paths resolved relative to the working directory.
• Safe startup options: --recovery-mode skips integrations for configuration repair, while --debug enables diagnostic logging.
• Package management: --skip-pip prevents all automatic installations, and --skip-pip-packages excludes specific dependencies.
• Logging flexibility: Control output destinations with --log-file, rotation with --log-rotate-days, and formatting with --verbose and --log-no-color.
• Utility scripts: Execute maintenance tasks via --script without starting the full application server.

Frequently Asked Questions

How do I run Home Assistant with a custom configuration directory?

Use the -c or --config argument followed by the absolute or relative path to your configuration folder. Home Assistant resolves this path in homeassistant/__main__.py and validates it through ensure_config_path(). For example: hass -c /srv/homeassistant/config.

What is the difference between --debug and --verbose flags?

The --debug flag enables debug-level logging and runs the event loop in diagnostic mode, affecting runtime behavior and integration loading. The --verbose or -v flag specifically enhances log formatting by adding timestamps, thread information, and detailed tracebacks without changing the core runtime debug level.

How can I prevent Home Assistant from installing specific Python packages on startup?

Use the --skip-pip-packages argument followed by a comma-separated list of package names. This populates the skip_pip_packages field in RuntimeConfig, causing the runner to skip installation for only those specific packages while allowing others to install normally. Alternatively, use --skip-pip to disable all automatic package installation.

What does the --recovery-mode flag do and when should I use it?

The --recovery-mode flag starts Home Assistant in a minimal safe mode that skips loading most integrations and custom components. You should use this when your configuration contains errors that prevent normal startup, allowing you to access the UI to fix configuration issues or remove problematic integrations without the system failing to load entirely.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}