Skip to main content

​
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.0.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