Overwrite a config file
files_write_config_fileWrite or overwrite a file under Home Assistant's /config, validating YAML and creating parent directories; no backup or reload.
Instructions
Overwrite or create one config file under /config with new content.
Resolves relative_path via _safe_path, YAML-checks content first
unless validate_yaml=False or the extension isn't .yaml/.yml, then
creates parent directories as needed and writes the file, replacing any
previous content at that path.
Use when: no rollback point for the previous content is needed.
Not for: keeping a rollback point — use git_safe_write_with_checkpoint,
which commits the pre-write state first; ESPHome device YAML — use
esphome_write_config.
Returns: dict {"success": True, "path": ...} on success, or
{"success": False, "error": ...} when validate_yaml catches invalid
YAML before writing.
Errors: raises PermissionError (from _safe_path) for a path outside
the config directory, a disallowed extension, or secrets.yaml/.storage;
returns {"success": False, "error": ...} instead of raising for
invalid YAML.
Limits: no backup is taken — the previous content is permanently lost.
Does not reload Home Assistant.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | Full text to write as the file's new content, replacing whatever was there before. | |
| relative_path | Yes | Path to the file relative to the HA config directory (HA_CONFIG_PATH), e.g. 'automations.yaml' or 'packages/lights.yaml'. Parent directories are created if missing. Must use an allowed extension (.yaml/.yml/.json/.txt) and not touch secrets.yaml or .storage/. | |
| validate_yaml | No | If True (default) and the extension is .yaml/.yml, `content` is parsed with a HA-tolerant YAML loader before writing; a parse error aborts the write. Set False to skip that check for non-YAML or intentionally unusual content. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||