# Home Assistant Command-Line Arguments: Complete Guide to CLI Options > Explore Home Assistant command-line arguments to customize your setup. Learn about options like config recovery mode debug and skip pip for advanced control. - Repository: [Home Assistant/core](https://github.com/home-assistant/core) - Tags: how-to-guide - Published: 2026-02-28 --- **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`](https://github.com/home-assistant/core/blob/main/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`](https://github.com/home-assistant/core/blob/main/configuration.yaml) and other runtime files. According to the source in [`homeassistant/__main__.py`](https://github.com/home-assistant/core/blob/main/homeassistant/__main__.py), this path resolves relative to the current working directory and passes through `ensure_config_path()` for validation. ```bash 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`](https://github.com/home-assistant/core/blob/main/__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: ```bash 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: ```bash 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: ```bash 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`](https://github.com/home-assistant/core/blob/main/homeassistant/__main__.py): ```bash # 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`](https://github.com/home-assistant/core/blob/main/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.