Edit File Functions

Safely edit files with find-and-replace operations

Edit File functions provide a safe way to modify existing files using find-and-replace operations. Unlike Write File, Edit File ensures that only intended changes are made and prevents accidental overwrites.

Configuration

function:
  type: edit_file
  path: "{{ filename }}"
  old_text: "{{ text_to_find }}"
  new_text: "{{ replacement_text }}"

path · template · required

Path to the file to edit. Can be absolute or relative to the working directory (config/extended_openai_conversation/).

old_text · template · required

Exact text to find and replace. Must appear exactly once in the file.

new_text · template · required

Text to replace the old text with.

allow_dir · array

Optional list of additional allowed directories (as templates). By default, only the working directory is allowed.

Working Directory

The default working directory is config/extended_openai_conversation/.

Relative Path

# Edits /config/extended_openai_conversation/notes.txt
function:
  type: edit_file
  path: "notes.txt"
  old_text: "old content"
  new_text: "new content"

Subdirectory

# Edits /config/extended_openai_conversation/data/config.json
function:
  type: edit_file
  path: "data/config.json"
  old_text: "{{ old_value }}"
  new_text: "{{ new_value }}"

Absolute Path

# Edits /config/configuration.yaml (must be in allowed directories)
function:
  type: edit_file
  path: "/config/configuration.yaml"
  old_text: "{{ old_setting }}"
  new_text: "{{ new_setting }}"

Examples

Edit File

- spec:
    name: edit_file
    description: Edit a file with find-and-replace in workspace.
    parameters:
      type: object
      properties:
        filename:
          type: string
          description: Name of the file to edit
        old_text:
          type: string
          description: Text to find
        new_text:
          type: string
          description: Text to replace with
      required:
      - filename
      - old_text
      - new_text
  function:
    type: edit_file
    path: "{{ filename }}"
    old_text: "{{ old_text }}"
    new_text: "{{ new_text }}"

Custom Allowed Directories

Extend allowed directories beyond the default workspace. The allow_dir parameter adds additional directories where files can be edited.

- spec:
    name: edit_file_with_allow_dir
    description: Edit a file with custom allowed directories.
    parameters:
      type: object
      properties:
        filename:
          type: string
          description: Name of the file to edit
        old_text:
          type: string
          description: Text to find
        new_text:
          type: string
          description: Text to replace with
      required:
      - filename
      - old_text
      - new_text
  function:
    type: edit_file
    path: "{{ filename }}"
    old_text: "{{ old_text }}"
    new_text: "{{ new_text }}"
    allow_dir:
      - "/backup"
      - "/media"

How It Works

Edit File is safer than Write File because it:

1. Reads the current file to verify it exists
2. Searches for exact match of old_text
3. Validates single occurrence - fails if text appears 0 or 2+ times
4. Performs replacement - replaces only the one matched occurrence
5. Writes back to the same file

1. File is read

   The entire file is read into memory

2. Text is searched

   Searches for exact string match of old_text

3. Occurrence check

   • If found 0 times → Error: “Text not found in file”
   • If found 1 time → Proceed with replacement
   • If found 2+ times → Error: “Text appears N times in file”
4. Replacement performed

   Replaces the single occurrence with new_text

5. File is written

   The modified content is written back to the file

Return Value

On success:

{
  "success": true,
  "path": "/config/extended_openai_conversation/config.yaml",
  "replacements": 1
}

On error:

{
  "error": "Text not found in file: old text here..."
}

or

{
  "error": "Text appears 3 times in file. Please provide more specific text to ensure single replacement."
}

Safety Features

Exact Match Required

old_text must match exactly, including:

• Whitespace (spaces, tabs, newlines)
• Case sensitivity
• Special characters

This prevents accidental matches.

Single Occurrence Validation

If text appears multiple times, the edit is rejected. This prevents unintended changes to multiple locations.

To edit when text appears multiple times, make old_text more specific by including surrounding context.

File Must Exist

Unlike Write File, Edit File requires the file to already exist. This prevents accidental file creation.

Atomic Operation

The entire read-modify-write operation is atomic. If any step fails, the file remains unchanged.

Common Patterns

Update YAML Configuration Value

- spec:
    name: update_yaml_config
    description: Update a YAML configuration value
    parameters:
      type: object
      properties:
        key:
          type: string
        old_value:
          type: string
        new_value:
          type: string
  function:
    type: edit_file
    path: "/config/configuration.yaml"
    old_text: "{{ key }}: {{ old_value }}"
    new_text: "{{ key }}: {{ new_value }}"

Update Python Variable

- spec:
    name: update_python_variable
    description: Update a variable in Python script
    parameters:
      type: object
      properties:
        script_name:
          type: string
        variable_name:
          type: string
        new_value:
          type: string
  function:
    type: edit_file
    path: "python_scripts/{{ script_name }}.py"
    old_text: "{{ variable_name }} = "
    new_text: "{{ variable_name }} = {{ new_value }}"

Comment Out a Line

- spec:
    name: comment_out_line
    description: Comment out a configuration line
    parameters:
      type: object
      properties:
        filename:
          type: string
        line_content:
          type: string
  function:
    type: edit_file
    path: "{{ filename }}"
    old_text: "{{ line_content }}"
    new_text: "# {{ line_content }}"

Update Automation Trigger

- spec:
    name: update_automation_trigger
    description: Update automation trigger entity
    parameters:
      type: object
      properties:
        automation_file:
          type: string
        old_entity:
          type: string
        new_entity:
          type: string
  function:
    type: edit_file
    path: "automations/{{ automation_file }}"
    old_text: |
      trigger:
        - platform: state
          entity_id: {{ old_entity }}
    new_text: |
      trigger:
        - platform: state
          entity_id: {{ new_entity }}

Include surrounding context in old_text to make it unique when the value appears multiple times in the file.

Use Cases

Configuration Updates

Update settings in YAML, JSON, or INI files

Version Updates

Change version numbers or identifiers

Entity ID Changes

Update entity references in automations

Text Corrections

Fix typos or update documentation

Advanced Examples

Multi-line Replacement

Edit File supports multi-line text:

- spec:
    name: update_yaml_block
    description: Update a multi-line YAML block
    parameters:
      type: object
      properties:
        service_name:
          type: string
  function:
    type: edit_file
    path: "/config/automations.yaml"
    old_text: |
      action:
        - service: light.turn_on
          target:
            entity_id: light.bedroom
    new_text: |
      action:
        - service: {{ service_name }}
          target:
            entity_id: light.bedroom

Replace with Empty String (Delete)

- spec:
    name: remove_config_line
    description: Remove a configuration line
    parameters:
      type: object
      properties:
        line_to_remove:
          type: string
  function:
    type: edit_file
    path: "config.yaml"
    old_text: "{{ line_to_remove }}\n"
    new_text: ""

To delete a line, include the newline character (\n) in old_text so the empty line is also removed.

Conditional Edit with Validation

- spec:
    name: safe_config_update
    description: Safely update config with validation
    parameters:
      type: object
      properties:
        old_value:
          type: string
        new_value:
          type: string
  function:
    type: composite
    sequence:
      - type: read_file
        path: "config.yaml"
        response_variable: file_content
      - type: template
        value_template: |
          {% if old_value in file_content.content %}
            {% if file_content.content.count(old_value) == 1 %}
              OK: Ready to replace
            {% else %}
              ERROR: Value appears multiple times
            {% endif %}
          {% else %}
            ERROR: Value not found
          {% endif %}
        response_variable: validation
      - type: edit_file
        path: "config.yaml"
        old_text: "{{ old_value }}"
        new_text: "{{ new_value }}"

Best Practices

1. Include context for uniqueness

   When the value appears multiple times, include surrounding text to make it unique:

   # Too broad - might match multiple times
   old_text: "entity_id: light.bedroom"
   
   # Better - includes context
   old_text: |
     trigger:
       - platform: state
         entity_id: light.bedroom
   
2. Preserve exact formatting

   Match indentation, spaces, and newlines exactly as they appear in the file:

   # Match the exact indentation (2 spaces)
   old_text: "  temperature: 20"
   new_text: "  temperature: {{ new_temp }}"
   
3. Read file first to verify content

   Use composite function to read file first and verify the content exists:

   type: composite
   sequence:
     - type: read_file
       path: "{{ filename }}"
       response_variable: content
     - type: edit_file
       path: "{{ filename }}"
       old_text: "{{ old_value }}"
       new_text: "{{ new_value }}"
   
4. Handle errors gracefully

   Expect and handle “not found” and “multiple occurrences” errors in your prompts or composite functions.

Troubleshooting

Text not found in file

The old_text doesn’t exist in the file. Common causes:

• Typo in old_text
• Whitespace mismatch (spaces vs tabs)
• Case sensitivity
• File has already been edited

Solution: Read the file first to verify exact content, then copy the exact text including whitespace.

Text appears N times in file

The old_text appears multiple times. This is blocked to prevent unintended changes.

Solution: Make old_text more specific by including surrounding context:

# Instead of:
old_text: "enabled: true"

# Use:
old_text: |
  feature_name:
    enabled: true

File not found

The file doesn’t exist at the specified path. Edit File requires existing files.

Solution: Use Write File to create new files, or verify the file path is correct.

Access denied

The file is outside allowed directories.

Solution: Add the directory to allow_dir or move the file to the workspace.

Comparison: Edit vs Write

When to use Edit File

✅ Use Edit File when:

• Modifying existing files
• You want to change specific values
• You need safety against accidental overwrites
• The file has other content you want to preserve

When to use Write File

✅ Use Write File when:

• Creating new files from scratch
• Generating complete file contents
• You want to overwrite the entire file
• The file is a generated output (logs, reports, exports)

FAQ

Can I replace multiple occurrences at once?

No. Edit File only replaces a single occurrence. This is a safety feature. To replace multiple occurrences, either:

• Make old_text more specific so it matches only once
• Use bash functions with sed:

type: bash
command: "sed -i 's/{{ old }}/{{ new }}/g' {{ filename }}"

What if I need to edit the same value multiple times?

Call the edit function multiple times, each time making old_text specific to one occurrence by including surrounding context.

Can I use regular expressions?

No. Edit File uses exact string matching. For regex replacements, use bash functions with sed.

Does it create backups?

No. The file is modified in place. If you need backups, use a composite function:

type: composite
sequence:
  - type: bash
    command: "cp {{ filename }} {{ filename }}.backup"
  - type: edit_file
    path: "{{ filename }}"
    old_text: "{{ old }}"
    new_text: "{{ new }}"

Security

Path Restriction

Files must be within allowed directories. By default:

• /config/extended_openai_conversation/ (working directory)

Additional directories can be added via allow_dir.

Exact Match Only

Only exact string matches are replaced. This prevents unintended changes through fuzzy matching or partial matches.

Single Occurrence

Only one occurrence can be replaced at a time. This prevents mass replacements that could corrupt the file.

File Must Exist

The file must already exist. This prevents accidental file creation.

Next Steps

Read File

Read file contents before editing

Write File

Create new files or overwrite completely

Bash Functions

Advanced text processing with sed/awk