write_file

Write, modify, or delete file content.

Usage 

@write_file filepath="<path>" [action="<action>"] [content="<content>"]

Examples

  • @write_file filepath="./src/main.lua" action="create" content="print('hello')" - Create new file
  • @write_file filepath="./src/main.lua" action="overwrite" content="new content" - Overwrite file
  • @write_file filepath="./src/main.lua" action="append" content="\n-- added" - Append content
  • @write_file filepath="./src/main.lua" action="insert" line_start=5 content="-- comment" - Insert at line
  • @write_file filepath="./src/main.lua" action="delete" line_start=5 line_to=10 - Delete lines
  • @write_file filepath="./src/main.lua" action="replace" line_start=5 line_to=10 content="new lines" - Replace lines
  • @write_file filepath="./src/main.lua" action="str_replace" old_str="local x = 1" new_str="local x = 2" - Replace string
  • @write_file filepath="./src/main.lua" action="str_replace" old_str="TODO" new_str="DONE" replace_all=true - Replace all occurrences
  • @write_file filepath="./src/main.lua" action="overwrite" content="x=1" fileformat="dos" - Overwrite with CRLF (Windows) line endings
  • @write_file filepath="./src/main.lua" action="remove" - Delete entire file
  • @write_file filepath="./scripts/deploy.sh" action="chmod" mode="755" - Change file permissions to 755
  • @write_file filepath="./docs" action="chmod" mode="0755" - Change directory permissions

Parameters

Parameter Type Description
filepath string Required. File path (relative to cwd or absolute)
action string Action to perform (default: create)
content string Content to write (required for create/overwrite/append/insert/replace)
line_start integer Starting line number, 1-indexed (for insert/delete/replace)
line_to integer Ending line number, 1-indexed (for delete/replace)
old_str string String to find (for str_replace, literal matching, no regex)
new_str string Replacement string (for str_replace, can be empty to delete text)
replace_all boolean Replace all occurrences of old_str (default: false, requires exactly one match)
backup boolean Create backup before modification (default: false)
validate boolean Validate syntax after modification for code files (default: false)
fileformat string Line-ending format: unix (LF), dos (CRLF), mac (CR)
mode string Octal permission mode (for chmod): 3-4 digits 0-7, e.g., 644, 755, 0755

Actions

Action Description
create Create new file (fails if exists)
overwrite Overwrite entire file content
append Append content to end of file
insert Insert content at specific line
delete Delete specific line range
replace Replace specific line range with new content
str_replace Replace string by matching old_str (no line numbers needed)
remove Delete entire file
chmod Change file permissions (octal mode, e.g., "755")

Notes

  • Line numbers are 1-indexed (first line is line 1)
  • line_start and line_to are both inclusive (e.g., line_start=5 line_to=10 deletes lines 5-10, including both)
  • Filepath must be within working directory (cwd) and allowed_path config
  • For insert: line_start can be #lines+1 to append at end
  • For str_replace: old_str uses literal string matching (no regex/patterns), supports multi-line matching
  • For str_replace: by default, old_str must match exactly once; use replace_all=true to replace all occurrences
  • For str_replace: new_str can be empty to delete the matched text
  • For chmod: mode is an octal string (3 or 4 digits 0-7, e.g., "644", "755", "0755"); works on files and directories; implemented via vim.uv.fs_chmod (on Windows only the read-only bit is honored)
  • Use validate=true for code files to catch syntax errors (supports Lua and Python)
  • Use backup=true to create backup before modification (format: <filepath>.backup.<timestamp>)
  • Line endings: fileformat accepts unix (LF), dos (CRLF) or mac (CR); if omitted, the existing file’s line endings are preserved automatically (modifying a CRLF file keeps CRLF), new files default to unix. Use @file_info to check a file’s detected fileformat.