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:

/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:

# 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:

/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:

# 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:

/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:

# 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:

/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:

# 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:

/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:

# 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:

# 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:

/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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# Enable file caching
/cache files enable

# Clear file cache
/cache files clear

# Show cache statistics
/cache files stats

Integration Examples

Development Workflow

# 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

# 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

# 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:

# Check file existence
/ls path/to/file

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

# Check current directory
/ls

Permission denied:

# 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:

# 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

# 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