File Operations

Overview

Polaris provides a comprehensive set of file operation tools that enable AI agents to create, read, update, delete, rename, and list files and folders within projects. These tools are designed to work efficiently with the file system through Convex backend operations.

listFiles

List all files and folders in the project. Returns a structured representation of the project’s file system with IDs, names, types, and parent relationships.

Parameters

This tool takes no parameters.

Response

Returns a JSON array of file objects:

string

required

The unique identifier for the file or folder

name

string

required

The name of the file or folder

type

string

required

Either "file" or "folder"

parentId

string | null

required

The ID of the parent folder, or null for root-level items. Items with the same parentId are in the same folder.

Example

{
  "name": "listFiles",
  "parameters": {}
}

Files and folders are sorted with folders first, then alphabetically by name.

createFiles

Create multiple files at once in the same parent folder. This is the most efficient way to batch create files that share the same parent directory.

Parameters

parentId

string

required

The ID of the parent folder. Use an empty string "" for root level. Must be a valid folder ID from listFiles.

files

array

required

Array of file objects to create. Must contain at least one file.

files[].name

string

required

The file name including extension (e.g., "index.ts", "README.md")

files[].content

string

required

The file content as a string

Response

Returns a success message listing created files and any failures:

Created 2 file(s): index.ts, styles.css

Or with partial failures:

Created 1 file(s): index.ts. Failed: styles.css (File already exists)

Example

{
  "name": "createFiles",
  "parameters": {
    "parentId": "k17abc123",
    "files": [
      {
        "name": "index.ts",
        "content": "export const greeting = 'Hello, Polaris!';"
      },
      {
        "name": "types.ts",
        "content": "export type User = { id: string; name: string; };"
      }
    ]
  }
}

Error Handling

Common Errors

Parent folder not found: Error: Parent folder with ID "xyz" not found. Use listFiles to get valid folder IDs.
Parent is a file: Error: The ID "xyz" is a file, not a folder. Use a folder ID as parentId.
Invalid parent ID: Error: Invalid parentId "xyz". Use listFiles to get valid folder IDs, or use empty string for root level.
Empty file name: Error: File name cannot be empty
Empty array: Error: Provide at least one file to create

createFolder

Create a new folder in the project.

Parameters

name

string

required

The name of the folder to create

parentId

string

required

The ID (not name!) of the parent folder from listFiles, or empty string "" for root level

Response

Returns the ID of the created folder:

Folder created with ID: k17xyz789

Example

{
  "name": "createFolder",
  "parameters": {
    "name": "components",
    "parentId": "k17abc123"
  }
}

Error Handling

Common Errors

Folder name required: Error: Folder name is required
Parent folder not found: Error: Parent folder with ID "xyz" not found. Use listFiles to get valid folder IDs.
Parent is a file: Error: The ID "xyz" is a file, not a folder. Use a folder ID as parentId.
Invalid parent ID: Error: Invalid parentId "xyz". Use listFiles to get valid folder IDs, or use empty string for root level.

readFiles

Read the content of one or more files from the project.

Parameters

fileIds

array

required

Array of file IDs to read. Must contain at least one file ID.

Response

Returns a JSON array of file objects with their contents:

string

required

The file ID

name

string

required

The file name

content

string

required

The file content

Example

{
  "name": "readFiles",
  "parameters": {
    "fileIds": ["k17def456", "k17ghi789"]
  }
}

Error Handling

Common Errors

No files found: Error: No files found with provided IDs. Use listFiles to get valid fileIDs.
Empty file ID: Error: File ID cannot be empty
Empty array: Error: Provide at least one file ID

Files without content or that don’t exist are silently skipped. If all provided IDs are invalid, you’ll receive the “No files found” error.

updateFile

Update the content of an existing file.

Parameters

fileId

string

required

The ID of the file to update

content

string

required

The new content for the file

Response

Returns a success message with the file name:

File "index.ts" updated successfully

Example

{
  "name": "updateFile",
  "parameters": {
    "fileId": "k17def456",
    "content": "export const greeting = 'Hello, World!';"
  }
}

Error Handling

Common Errors

File not found: Error: File with ID "xyz" not found. Use listFiles to get valid file IDs.
Target is a folder: Error: "xyz" is a folder, not a file. You can only update file contents.
File ID required: Error: File ID is required

renameFile

Rename a file or folder.

Parameters

fileId

string

required

The ID of the file or folder to rename

newName

string

required

The new name for the file or folder

Response

Returns a success message showing the old and new names:

Renamed "old-name.ts" to "new-name.ts" successfully

Example

{
  "name": "renameFile",
  "parameters": {
    "fileId": "k17def456",
    "newName": "main.ts"
  }
}

Error Handling

Common Errors

File not found: Error: File with ID "xyz" not found. Use listFiles to get valid file IDs.
File ID required: Error: File ID is required
New name required: Error: New name is required

deleteFiles

Delete one or more files or folders from the project. When deleting a folder, all contents are deleted recursively.

Parameters

fileIds

array

required

Array of file or folder IDs to delete. Must contain at least one ID.

Response

Returns a success message for each deleted item:

Deleted file "index.ts" successfully
Deleted folder "components" successfully

Example

{
  "name": "deleteFiles",
  "parameters": {
    "fileIds": ["k17def456", "k17xyz789"]
  }
}

Error Handling

Common Errors

File not found: Error: File with ID "xyz" not found. Use listFiles to get valid file IDs.
Empty file ID: Error: File ID cannot be empty
Empty array: Error: Provide at least one file ID

Deleting a folder will recursively delete all of its contents. This operation cannot be undone.

Best Practices

Efficient File Creation

Always use createFiles (plural) instead of creating files one by one when creating multiple files in the same folder:

{
  "name": "createFiles",
  "parameters": {
    "parentId": "k17abc123",
    "files": [
      { "name": "a.ts", "content": "..." },
      { "name": "b.ts", "content": "..." },
      { "name": "c.ts", "content": "..." }
    ]
  }
}

Understanding File Structure

Always call listFiles first to understand the project structure before performing operations:

Call listFiles to get all file and folder IDs
Use the parentId relationships to understand the folder hierarchy
Use the correct IDs in subsequent operations

File IDs vs Names

Most tools require file IDs, not file names. Always use listFiles to get the correct IDs before operating on files.

Endpoints

Convex Schema

Tools

​Overview

​listFiles

​Parameters

​Response

​Example

​createFiles

​Parameters

​Response

​Example

​Error Handling

​createFolder

​Parameters

​Response

​Example

​Error Handling

​readFiles

​Parameters

​Response

​Example

​Error Handling

​updateFile

​Parameters

​Response

​Example

​Error Handling

​renameFile

​Parameters

​Response

​Example

​Error Handling

​deleteFiles

​Parameters

​Response

​Example

​Error Handling

​Best Practices

​Efficient File Creation

​Understanding File Structure

​File IDs vs Names

Build docs developers (and LLMs) love

Overview

listFiles

Parameters

Response

Example

createFiles

Parameters

Response

Example

Error Handling

createFolder

Parameters

Response

Example

Error Handling

readFiles

Parameters

Response

Example

Error Handling

updateFile

Parameters

Response

Example

Error Handling

renameFile

Parameters

Response

Example

Error Handling

deleteFiles

Parameters

Response

Example

Error Handling

Best Practices

Efficient File Creation

Understanding File Structure

File IDs vs Names