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

Getting Started

CLI Reference

Agent System

Planning System

Context & RAG

Architecture

Troubleshooting

Documentation Index

​File Operations

​Core File Commands

​/read [file]

​/write [file] [content]

​/edit [file]

​/ls [path]

​Search Commands

​/search [pattern]

​/grep [pattern]

​Advanced File Operations

​File Analysis

​Batch Operations

​File Templates

​File System Integration

​Git Integration

​Project Structure Analysis

​Workspace Context

​File Watching and Monitoring

​Real-time File Monitoring

​Change Notifications

​Security and Permissions

​File Permissions

​Safe Operations

​Performance Optimization

​Large File Handling

​Caching

​Integration Examples

​Development Workflow

​Code Review Workflow

​Documentation Workflow

​Troubleshooting

​Common Issues

​Debug Commands

​Best Practices

​File Organization

​Content Management

​Security

​Performance

File Operations

Core File Commands

`/read [file]`

`/write [file] [content]`

`/edit [file]`

`/ls [path]`

Search Commands

`/search [pattern]`

`/grep [pattern]`

Advanced File Operations

File Analysis

Batch Operations

File Templates

File System Integration

Git Integration

Project Structure Analysis

Workspace Context

File Watching and Monitoring

Real-time File Monitoring

Change Notifications

Security and Permissions

File Permissions

Safe Operations

Performance Optimization

Large File Handling

Caching

Integration Examples

Development Workflow

Code Review Workflow

Documentation Workflow

Troubleshooting

Common Issues

Debug Commands

Best Practices

File Organization

Content Management

Security

Performance