From c10be0e06ebdc631578f9d69eea6c59ea12ef584 Mon Sep 17 00:00:00 2001 From: theCyberTech Date: Sun, 28 Jun 2026 12:16:40 +0800 Subject: [PATCH] docs(file-writer): fix accuracy of FileWriterTool page The Edge MDX for FileWriterTool had several accuracy issues against the actual tool source (crewai_tools/tools/file_writer_tool/file_writer_tool.py): - Claimed 'supports UTF-8 encoding' but open() is called without an encoding= argument, so behavior follows locale.getpreferredencoding() (UTF-8 on Linux/macOS, cp1252 on stock Windows). Replaced the claim with an accurate note + PYTHONUTF8 guidance. - Did not state the tool is text-only. Added a warning that binary files (images, PDFs, archives, executables) are not supported. - The overwrite argument (overwrite: str | bool = False) was missing entirely from the Arguments list, even though it controls exclusive vs write mode and the already-exists error. Documented it. - The auto-mkdir behavior is conditional on directory being explicitly passed; the docs implied unconditional creation. Clarified. - The example used positional args against _run(self, **kwargs), which would KeyError. Switched to keyword arguments. --- .../en/tools/file-document/filewritetool.mdx | 21 ++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/docs/edge/en/tools/file-document/filewritetool.mdx b/docs/edge/en/tools/file-document/filewritetool.mdx index f8bc464ce..16c645513 100644 --- a/docs/edge/en/tools/file-document/filewritetool.mdx +++ b/docs/edge/en/tools/file-document/filewritetool.mdx @@ -11,7 +11,13 @@ mode: "wide" The `FileWriterTool` is a component of the crewai_tools package, designed to simplify the process of writing content to files with cross-platform compatibility (Windows, Linux, macOS). It is particularly useful in scenarios such as generating reports, saving logs, creating configuration files, and more. -This tool handles path differences across operating systems, supports UTF-8 encoding, and automatically creates directories if they don't exist, making it easier to organize your output reliably across different platforms. +This tool handles path differences across operating systems, guards against path-traversal and symlink escapes, and creates parent directories (when a `directory` is explicitly provided) if they don't exist, making it easier to organize your output reliably across different platforms. + + +The tool writes `content` in **text mode** — it is intended for plain-text files only (`.txt`, `.md`, `.json`, `.yaml`, `.csv`, `.log`, `.py`, config files, generated source, reports, etc.). It is **not** suitable for binary files such as images, PDFs, archives, or executables; writing binary data through it will raise or corrupt the output. + +No explicit `encoding` is passed to `open()`, so the byte encoding follows `locale.getpreferredencoding()` — UTF-8 on Linux/macOS, but typically cp1252 on stock Windows. Set `PYTHONUTF8=1` (or otherwise configure the locale) if you need guaranteed UTF-8 on Windows. + ## Installation @@ -31,16 +37,21 @@ from crewai_tools import FileWriterTool # Initialize the tool file_writer_tool = FileWriterTool() -# Write content to a file in a specified directory -result = file_writer_tool._run('example.txt', 'This is a test content.', 'test_directory') +# Write content to a file in a specified directory (keyword arguments) +result = file_writer_tool._run( + filename='example.txt', + content='This is a test content.', + directory='test_directory', +) print(result) ``` ## Arguments - `filename`: The name of the file you want to create or overwrite. -- `content`: The content to write into the file. -- `directory` (optional): The path to the directory where the file will be created. Defaults to the current directory (`.`). If the directory does not exist, it will be created. +- `content`: The text content to write into the file (string). +- `directory` (optional): The path to the directory where the file will be created. Defaults to the current directory (`./`). Parent directories are created **only when `directory` is explicitly provided**; the default `./` does not trigger directory creation. +- `overwrite` (optional, default `False`): Whether to overwrite an existing file. Accepts a bool or a string (`"true"`/`"false"`, `"yes"`/`"no"`, `"1"`/`"0"`, etc.). When `False`, the tool opens in exclusive-create mode (`"x"`) and returns an error if the file already exists; when truthy, it opens in write mode (`"w"`) and replaces the file. ## Conclusion