> ## Documentation Index
> Fetch the complete documentation index at: https://nikcli.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# File Operations

> Complete reference for file system operations and content management commands

# File Operations

NikCLI provides comprehensive file system operations for reading, writing, editing, and searching files. These commands integrate with AI capabilities for intelligent file management.

## Core File Commands

### `/read [file]`

Read and display file contents with syntax highlighting and AI analysis.

**Syntax:**

```bash theme={null}
/read <file-path> [options]
```

**Parameters:**

* `file-path` - Path to the file (relative or absolute)

**Features:**

* Syntax highlighting for code files
* AI-powered content analysis
* Large file handling with pagination
* Binary file detection
* Encoding detection and conversion

**Examples:**

```bash theme={null}
# Read a configuration file
/read package.json

# Read source code with analysis
/read src/components/UserProfile.tsx

# Read documentation
/read README.md

# Read with relative path
/read ./config/database.js

# Read with absolute path
/read /etc/nginx/nginx.conf
```

**Output Features:**

* Line numbers for code files
* File metadata (size, modified date, permissions)
* Content summary for large files
* Syntax errors detection
* Security issue highlighting

### `/write [file] [content]`

Write content to a file with AI assistance and validation.

**Syntax:**

```bash theme={null}
/write <file-path> "<content>"
```

**Parameters:**

* `file-path` - Target file path
* `content` - Content to write (use quotes for multi-line)

**Features:**

* Automatic backup creation
* Syntax validation
* Format detection and formatting
* Permission checking
* Directory creation if needed

**Examples:**

```bash theme={null}
# Write simple configuration
/write .env "NODE_ENV=production
DATABASE_URL=postgresql://..."

# Write code with proper formatting
/write src/utils/helpers.js "
export const formatDate = (date) => {
  return new Intl.DateTimeFormat('en-US').format(date);
};
"

# Write JSON configuration
/write config/app.json '{
  "name": "my-app",
  "version": "1.6.0",
  "environment": "production"
}'

# Write documentation
/write docs/api.md "# API Documentation

## Authentication
All API endpoints require authentication..."
```

**Safety Features:**

* Automatic backup before overwriting
* Confirmation for important files
* Syntax validation before writing
* Permission verification

### `/edit [file]`

Interactive file editing with AI assistance.

**Syntax:**

```bash theme={null}
/edit <file-path> [instructions]
```

**Parameters:**

* `file-path` - File to edit
* `instructions` - Optional editing instructions

**Features:**

* AI-powered editing suggestions
* Syntax-aware modifications
* Undo/redo capabilities
* Real-time validation
* Collaborative editing mode

**Examples:**

```bash theme={null}
# Open file for interactive editing
/edit src/app.js

# Edit with specific instructions
/edit package.json "add lodash dependency"

# Edit with complex instructions
/edit src/components/Button.tsx "add TypeScript props interface and make the component more accessible"

# Edit configuration files
/edit .eslintrc.js "add React hooks rules"

# Edit documentation
/edit README.md "add installation instructions and usage examples"
```

**Interactive Features:**

* Line-by-line editing mode
* AI suggestions for improvements
* Syntax error detection
* Code formatting
* Import/export management

### `/ls [path]`

List directory contents with enhanced information.

**Syntax:**

```bash theme={null}
/ls [directory-path] [options]
```

**Parameters:**

* `directory-path` - Directory to list (default: current directory)

**Features:**

* File type detection and icons
* Size and date information
* Permission display
* Git status integration
* Project structure analysis

**Examples:**

```bash theme={null}
# List current directory
/ls

# List specific directory
/ls src/components

# List with detailed information
/ls -l

# List hidden files
/ls -a

# List recursively
/ls -R src/

# List with file types
/ls --classify
```

**Output Format:**

```
📁 src/
├── 📁 components/
│   ├── 🔵 Button.tsx (2.1KB, modified 2h ago)
│   ├── 🔵 Modal.tsx (3.4KB, modified 1d ago)
│   └── 🔵 Form.tsx (1.8KB, modified 3h ago)
├── 📁 utils/
│   ├── 🟡 helpers.js (1.2KB, modified 1h ago)
│   └── 🟡 api.js (2.8KB, modified 2d ago)
└── 📄 index.ts (0.5KB, modified 30m ago)

Total: 8 files, 3 directories (11.8KB)
```

## Search Commands

### `/search [pattern]`

Search for files by name pattern with intelligent matching.

**Syntax:**

```bash theme={null}
/search <pattern> [options]
```

**Parameters:**

* `pattern` - Search pattern (supports wildcards and regex)

**Features:**

* Fuzzy matching
* Multiple search modes
* File type filtering
* Size and date filtering
* Content preview

**Search Modes:**

* `name` - Search by filename (default)
* `content` - Search file contents
* `type` - Search by file type
* `modified` - Search by modification date

**Examples:**

```bash theme={null}
# Search by filename
/search "*.tsx"

# Search for specific files
/search "config"

# Search with fuzzy matching
/search "usr-prof"  # Finds UserProfile.tsx

# Search by file type
/search --type javascript

# Search by content
/search --content "useState"

# Search recently modified files
/search --modified "1d"

# Complex search
/search "*.js" --content "export" --modified "1w"
```

**Advanced Patterns:**

```bash theme={null}
# Regex patterns
/search "test.*\.spec\.js$"

# Multiple extensions
/search "*.{js,ts,jsx,tsx}"

# Exclude patterns
/search "*.js" --exclude "node_modules"

# Size filters
/search --size ">1MB"

# Git status filters
/search --git modified
```

### `/grep [pattern]`

Search file contents with powerful pattern matching.

**Syntax:**

```bash theme={null}
/grep <pattern> [files] [options]
```

**Parameters:**

* `pattern` - Search pattern (regex supported)
* `files` - Files to search (optional, defaults to all files)

**Features:**

* Regular expression support
* Context lines display
* Case-sensitive/insensitive search
* Multiple file search
* Syntax highlighting in results

**Examples:**

```bash theme={null}
# Search for function definitions
/grep "function.*export"

# Search for React hooks
/grep "use[A-Z][a-zA-Z]*"

# Search in specific files
/grep "TODO" src/**/*.js

# Case-insensitive search
/grep -i "error"

# Search with context
/grep -C 3 "import.*react"

# Search for exact matches
/grep -w "user"

# Search excluding files
/grep "console.log" --exclude "*.min.js"
```

**Output Format:**

```
src/components/Button.tsx:15:  const handleClick = () => {
src/components/Button.tsx:16:    console.log('Button clicked');
src/components/Button.tsx:17:  };
--
src/utils/api.js:23:    console.error('API Error:', error);
src/utils/api.js:24:    throw error;

Found 2 matches in 2 files
```

## Advanced File Operations

### File Analysis

Automatic file analysis and insights:

```bash theme={null}
# Analyze code quality
/read src/app.js
# AI provides analysis: "This file has 3 potential issues..."

# Analyze configuration
/read package.json
# AI suggests: "Consider updating these dependencies..."

# Analyze documentation
/read README.md
# AI suggests: "Add installation instructions and examples"
```

### Batch Operations

Perform operations on multiple files:

```bash theme={null}
# Read multiple files
/read src/components/*.tsx

# Edit multiple files with same change
/edit src/**/*.js "add strict mode directive"

# Search and replace across files
/grep -l "oldFunction" src/**/*.js | /edit "replace oldFunction with newFunction"
```

### File Templates

Create files from templates:

```bash theme={null}
# Create React component
/write src/components/NewComponent.tsx "$(template react-component NewComponent)"

# Create API endpoint
/write src/api/users.js "$(template express-route users)"

# Create test file
/write src/components/NewComponent.test.tsx "$(template jest-test NewComponent)"
```

## File System Integration

### Git Integration

File operations integrate with Git status:

```bash theme={null}
# List with Git status
/ls --git

# Search modified files
/search --git modified

# Read staged files
/read $(git diff --cached --name-only)
```

### Project Structure Analysis

Understand project organization:

```bash theme={null}
# Analyze project structure
/ls --analyze

# Find entry points
/search "main\|index\|app" --type "js,ts"

# Find configuration files
/search "config\|.*rc\|.*config.*"
```

### Workspace Context

File operations maintain workspace context:

```bash theme={null}
# Set workspace root
/context workspace /path/to/project

# All file operations use workspace context
/read package.json  # Reads from workspace root
/ls src/           # Lists from workspace/src/
```

## File Watching and Monitoring

### Real-time File Monitoring

Monitor file changes in real-time:

```bash theme={null}
# Watch specific files
/watch src/app.js

# Watch directory
/watch src/components/

# Watch with pattern
/watch "src/**/*.tsx"
```

### Change Notifications

Get notified of file system changes:

```bash theme={null}
# Enable change notifications
/notify file-changes on

# File change events trigger AI analysis
# "Button.tsx was modified - analyzing changes..."
```

## Security and Permissions

### File Permissions

Check and manage file permissions:

```bash theme={null}
# Check permissions
/ls -l src/

# Verify write access
/write test.txt "test" --dry-run

# Check file security
/security scan-files
```

### Safe Operations

Protect important files:

```bash theme={null}
# Backup before editing
/edit package.json --backup

# Confirm destructive operations
/write important-config.json "..." --confirm

# Read-only mode for sensitive files
/read /etc/passwd --readonly
```

## Performance Optimization

### Large File Handling

Efficiently handle large files:

```bash theme={null}
# Read large files with pagination
/read large-file.log --page 1 --size 100

# Search large files efficiently
/grep "error" large-file.log --max-results 50

# Stream large file content
/read large-file.log --stream
```

### Caching

File content caching for performance:

```bash theme={null}
# Enable file caching
/cache files enable

# Clear file cache
/cache files clear

# Show cache statistics
/cache files stats
```

## Integration Examples

### Development Workflow

```bash theme={null}
# 1. Explore project structure
/ls --analyze

# 2. Find relevant files
/search "user.*component"

# 3. Read and understand code
/read src/components/UserProfile.tsx

# 4. Make changes
/edit src/components/UserProfile.tsx "add loading state"

# 5. Verify changes
/grep "loading" src/components/UserProfile.tsx
```

### Code Review Workflow

```bash theme={null}
# 1. Find modified files
/search --git modified

# 2. Review changes
/read $(git diff --name-only)

# 3. Check for issues
/grep "TODO\|FIXME\|console.log" src/

# 4. Analyze code quality
/read src/components/NewFeature.tsx
```

### Documentation Workflow

```bash theme={null}
# 1. Find documentation files
/search "*.md"

# 2. Read existing docs
/read README.md

# 3. Update documentation
/edit README.md "add new feature documentation"

# 4. Verify completeness
/grep -L "example\|usage" docs/*.md
```

## Troubleshooting

### Common Issues

**File not found:**

```bash theme={null}
# Check file existence
/ls path/to/file

# Search for similar files
/search "similar-name"

# Check current directory
/ls
```

**Permission denied:**

```bash theme={null}
# Check permissions
/ls -l file-path

# Check current user
/system user

# Use sudo if needed (with caution)
/run sudo chmod 644 file-path
```

**Large file performance:**

```bash theme={null}
# Use pagination
/read large-file.txt --page 1

# Use streaming
/read large-file.txt --stream

# Search efficiently
/grep "pattern" large-file.txt --max-results 10
```

### Debug Commands

```bash theme={null}
# Show file operation debug info
/debug file-ops

# Show file system statistics
/stats filesystem

# Test file operations
/diagnostic files
```

## Best Practices

### File Organization

* Use consistent naming conventions
* Organize files in logical directories
* Keep related files together
* Use descriptive file names

### Content Management

* Write clear, well-documented code
* Use consistent formatting
* Include appropriate comments
* Maintain up-to-date documentation

### Security

* Verify file permissions regularly
* Backup important files before editing
* Use version control for all changes
* Avoid storing sensitive data in plain text

### Performance

* Use appropriate search patterns
* Cache frequently accessed files
* Monitor file system usage
* Clean up temporary files regularly