File Management Operations

ScryCLI provides powerful file management capabilities through natural language. The AI engine interprets your commands and executes file operations automatically.

Available File Operations

ScryCLI supports five core file operations:

read_file: Read and display file contents
write_file: Overwrite an existing file
create_file: Create a new file with content
delete_file: Remove a file from the filesystem

While the AI’s system prompt mentions an update_file action, it is processed the same as write_file by the tool executor - both overwrite the entire file content.

All operations use absolute paths resolved from your current working directory.

Reading Files

Request File Read

Ask ScryCLI to read a file using natural language:

> Read the auth.ts file

Or be more specific:

> Show me the contents of src/lib/auth.ts

AI Generates Action

The AI returns a structured JSON response:

{
  "action": "read_file",
  "file": "src/lib/auth.ts"
}

Automatic Execution

The useToolExecutor hook automatically executes the read:

case 'read_file':
  console.log(readFile(instruction.file));
  break;

The file contents are displayed in your terminal.

Read Examples

# Read a specific file
> Read src/config/configManage.ts

# Read configuration
> Show me the package.json file

# Read multiple files (requires multiple commands)
> Read src/tools/readFile.ts
> Read src/tools/writeFile.ts

The readFile tool uses Node.js fs.readFileSync() to read files synchronously. File paths are resolved using path.resolve() to ensure absolute paths.

Creating Files

Create new files with content in a single command:

> Create a new file src/utils/logger.ts with a simple console logger

AI Response:

{
  "action": "create_file",
  "file": "src/utils/logger.ts",
  "content": "export const logger = {\n  log: (msg: string) => console.log(msg),\n  error: (msg: string) => console.error(msg)\n};"
}

Execution:

// From src/tools/createFile.ts
export const createFile = (filePath: string, content: string) => {
  const absPath = path.resolve(filePath);
  ensureDir(absPath);  // Creates parent directories if needed
  fs.writeFileSync(absPath, content, 'utf-8');
};

Create Examples

# Create a new component
> Create src/components/Button.tsx with a basic React button component

# Create a config file
> Create .env with default environment variables for development

# Create documentation
> Create docs/API.md with API documentation structure

# Create with specific content
> Create public/index.html with a basic HTML5 template

The createFile tool automatically creates parent directories if they don’t exist using fs.mkdirSync() with the recursive: true option.

Writing Files

Overwrite existing files completely:

> Rewrite src/model/systemPrompt.ts with an improved prompt

AI Response:

{
  "action": "write_file",
  "file": "src/model/systemPrompt.ts",
  "content": "export const systemPrompt = `Improved system prompt...`;"
}

Execution:

// From src/tools/writeFile.ts
export const writeFile = (filePath: string, content: string) => {
  const absPath = path.resolve(filePath);
  fs.writeFileSync(absPath, content, 'utf-8');
};

Write vs. Create

Use create_file when:

The file doesn’t exist yet
You need parent directories created
Starting a new feature or component

Use write_file when:

Completely replacing existing content
Resetting a file to defaults
The file already exists

# Create (file doesn't exist)
> Create src/hooks/useAuth.ts

# Write (file exists, replace it)
> Rewrite src/hooks/useAuth.ts with a simplified version

Updating Files

Modify existing files with new content:

> Update src/lib/auth.ts to add support for refresh tokens

AI Response:

{
  "action": "write_file",
  "file": "src/lib/auth.ts",
  "content": "// Complete updated file content"
}

The AI may respond with update_file in the action field, but ScryCLI processes it the same as write_file - the entire file is overwritten with the new content.

Update Examples

# Add functionality
> Update src/hooks/useChat.ts to add streaming support

# Fix bugs
> Update src/tools/getFileTree.ts to ignore .env files

# Improve code
> Update src/config/configManage.ts to add config validation

# Add error handling
> Update src/hooks/useToolExecutor.ts to handle file operation errors

The update_file action returns the complete new file content, not just a diff. The AI reads the existing file, makes changes, and returns the full updated version.

Deleting Files

Remove files from your project:

> Delete the temporary test file src/temp.ts

AI Response:

{
  "action": "delete_file",
  "file": "src/temp.ts"
}

Execution:

// From src/tools/deleteFile.ts
export const deleteFile = (filePath: string) => {
  const absPath = path.resolve(filePath);
  fs.unlinkSync(absPath);
};

Delete Examples

# Remove old files
> Delete src/legacy/oldAuth.ts

# Clean up
> Delete all files in the temp directory

# Remove generated files
> Delete dist/bundle.js

Warning: Deletions are permanent. There’s no confirmation prompt.

File Path Resolution

All file operations resolve paths from your current working directory:

// From all tool files
const absPath = path.resolve(filePath);

Path Examples

# Relative path (recommended)
> Create src/utils/helper.ts
# Resolves to: /your/project/src/utils/helper.ts

# Current directory
> Create ./config.json
# Resolves to: /your/project/config.json

# Nested path
> Create src/components/ui/Button/index.tsx
# Parent directories created automatically

Smart File Naming

The AI engine intelligently determines file names and paths when you don’t specify:

# HTML files → public/index.html or public/game.html
> Create a landing page
# AI suggests: public/index.html

# React components → src/App.jsx
> Create a main React component
# AI suggests: src/App.jsx

# Styles → styles.css in same directory
> Create styles for the landing page
# AI suggests: public/styles.css

# JavaScript entry → main.js
> Create a JavaScript entry point
# AI suggests: src/main.js

From the system prompt:

4. If the user does not specify a file name, decide an appropriate 
   file name and directory based on:
   - HTML files → "public/index.html"
   - JavaScript entry → "src/App.jsx" if React, else "main.js"
   - CSS files → "styles.css" in the same directory as HTML

File Tree Context

ScryCLI automatically includes your project structure in every command:

// From src/model/openRouter.ts
const fileTreeString = getFileTree(process.cwd()).join('\n');

export async function llmCall({ prompt, systemPrompt }: llmCallParams) {
  const result = openRouterClient.callModel({
    model: `${getConfig().model.modelName}`,
    instructions: `${systemPrompt}`,
    input: `${prompt} \n\nFile Tree: ${fileTreeString}`,
  });
  return await result.getText();
}

This allows the AI to:

Suggest correct file paths
Understand existing structure
Avoid naming conflicts
Follow your project conventions

Ignored Directories

// From src/tools/getFileTree.ts
const IGNORED_DIRS = ['.git', 'node_modules', 'dist', 'build', '.next'];

These directories are excluded from the file tree to keep context focused on source code.

Batch File Operations

Perform multiple file operations in sequence:

# Create multiple related files
> Create src/types/user.ts with User interface
> Create src/services/userService.ts with user CRUD operations
> Create src/hooks/useUser.ts with a custom hook for user data

Each command is executed independently. If you need atomic operations (all succeed or all fail), handle it manually or use version control.

Advanced Patterns

Template Generation

> Create src/components/Card.tsx with a reusable card component using TypeScript and styled-components

The AI generates a complete component file:

{
  "action": "create_file",
  "file": "src/components/Card.tsx",
  "content": "import React from 'react';\nimport styled from 'styled-components';\n\n// Complete component code"
}

File Scaffolding

# Create a feature module structure
> Create src/features/auth/index.ts with exports
> Create src/features/auth/types.ts with TypeScript interfaces
> Create src/features/auth/hooks.ts with custom hooks
> Create src/features/auth/utils.ts with helper functions

Migration Scripts

# Update old API calls
> Update all files in src/api/ to use the new fetch wrapper

# Rename patterns
> Update src/hooks/useChat.ts to rename 'answer' to 'response'

Error Handling

File operations include basic error handling:

// From src/hooks/useToolExecutor.ts
try {
  const instruction = JSON.parse(clean);
  if (!instruction.action) return;

  switch (instruction.action) {
    case 'create_file':
      createFile(instruction.file, instruction.content);
      break;
    // ...
  }
} catch (e: any) {
  console.error(`Error executing tool: ${e.message}`);
}

Common Errors

File Not Found (read/write/delete):

Error: ENOENT: no such file or directory

Verify the file path is correct. Permission Denied:

Error: EACCES: permission denied

Check file permissions or run with appropriate privileges. Directory Doesn’t Exist (write/delete):

Error: ENOENT: no such file or directory

Use create_file instead (creates parent dirs).

Best Practices

1. Use Version Control

Always use git before making bulk file changes:

git add .
git commit -m "Before ScryCLI file operations"

2. Verify Before Deleting

# Check what you're deleting
> Read src/old/deprecated.ts

# Then delete
> Delete src/old/deprecated.ts

3. Be Specific with Paths

Good:

> Create src/components/ui/Button.tsx

Bad:

> Create a button component

4. Review Generated Content

# After creating
> Create src/utils/validator.ts with email validation

# Always read to verify
> Read src/utils/validator.ts

5. Understand File Tree Context

The AI knows your project structure:

# It will follow existing patterns
> Create a new hook like useChat
# AI creates: src/hooks/useNewFeature.ts (following convention)

Configuration File Location

ScryCLI stores its config in your home directory:

// From src/config/configManage.ts
const configPath = path.join(os.homedir(), ".scrycli", "config.json");

# View config
> Read ~/.scrycli/config.json

# Config structure:
{
  "model": {
    "modelName": "anthropic/claude-3-opus",
    "modelKey": "your-api-key"
  },
  "user": {
    "token": "jwt-token"
  }
}

Get Started

Core Concepts

Commands

Configuration

Guides

Advanced

File Management Operations

Available File Operations

Reading Files

Read Examples

Creating Files

Create Examples

Writing Files

Write vs. Create

Updating Files

Update Examples

Deleting Files

Delete Examples

File Path Resolution

Path Examples

Smart File Naming

File Tree Context

Ignored Directories

Batch File Operations

Advanced Patterns

Template Generation

File Scaffolding

Migration Scripts

Error Handling

Common Errors

Best Practices

1. Use Version Control

2. Verify Before Deleting

3. Be Specific with Paths

4. Review Generated Content

5. Understand File Tree Context

Configuration File Location

Next Steps

Authentication

Code Analysis

Get Started

Core Concepts

Commands

Configuration

Guides

Advanced

​Available File Operations

​Reading Files

​Read Examples

​Creating Files

​Create Examples

​Writing Files

​Write vs. Create

​Updating Files

​Update Examples

​Deleting Files

​Delete Examples

​File Path Resolution

​Path Examples

​Smart File Naming

​File Tree Context

​Ignored Directories

​Batch File Operations

​Advanced Patterns

​Template Generation

​File Scaffolding

​Migration Scripts

​Error Handling

​Common Errors

​Best Practices

​1. Use Version Control

​2. Verify Before Deleting

​3. Be Specific with Paths

​4. Review Generated Content

​5. Understand File Tree Context

​Configuration File Location

​Next Steps

Authentication

Code Analysis

Available File Operations

Reading Files

Read Examples

Creating Files

Create Examples

Writing Files

Write vs. Create

Updating Files

Update Examples

Deleting Files

Delete Examples

File Path Resolution

Path Examples

Smart File Naming

File Tree Context

Ignored Directories

Batch File Operations

Advanced Patterns

Template Generation

File Scaffolding

Migration Scripts

Error Handling

Common Errors

Best Practices

1. Use Version Control

2. Verify Before Deleting

3. Be Specific with Paths

4. Review Generated Content

5. Understand File Tree Context

Configuration File Location

Next Steps