File Operations

Complete guide to file system operations in NikCLI

File Operations Overview

NikCLI provides secure, powerful file system operations with built-in safety measures and intelligent context awareness. All file operations respect security policies and provide approval workflows when needed.

Read Operations

View file contents and directory listings

Write Operations

Create and modify files with approval workflows

Search Operations

Find files and search content across your project

Batch Operations

Perform operations on multiple files efficiently

Read Operations

/read - Read File Contents

Basic File Reading

# Read entire file
/read src/components/Button.tsx

# Read specific lines (useful for large files)
/read src/utils/helpers.ts 1-50
/read package.json 10-20

# Read with syntax highlighting
/read src/api/auth.js --highlight

Output Example:

📁 src/components/Button.tsx (45 lines)
───────────────────────────────────────────
  1│ import React from 'react';
  2│ import { ButtonProps } from '../types/components';
  3│ import styles from './Button.module.css';
  4│ 
  5│ export const Button: React.FC<ButtonProps> = ({
  6│   children,
  7│   variant = 'primary',
  8│   size = 'medium',
  9│   disabled = false,
 10│   onClick,
 11│   ...props
 12│ }) => {
 13│   return (
 14│     <button
 15│       className={`${styles.button} ${styles[variant]} ${styles[size]}`}
 16│       disabled={disabled}
 17│       onClick={onClick}
 18│       {...props}
 19│     >
 20│       {children}
 21│     </button>
 22│   );
 23│ };
───────────────────────────────────────────

Advanced Reading Options

# Read multiple files
/read src/components/*.tsx
/read "src/**/*.ts" --recursive

# Read with filters
/read src/api/auth.js --functions-only
/read src/types/index.ts --exports-only
/read src/components/Form.tsx --comments-only

# Read file metadata
/read src/main.ts --info

Metadata Output:

📋 File Information: src/main.ts
───────────────────────────────────────
Size: 2.3 KB (2,345 bytes)
Lines: 87 (72 code, 12 comments, 3 blank)
Created: 2024-03-15 10:30:22
Modified: 2024-03-20 14:45:33
Type: TypeScript
Encoding: UTF-8
Dependencies: 8 imports
Exports: 3 functions, 1 interface
───────────────────────────────────────

Binary and Image Files

# View image files (shows file info + opens in viewer)
/read assets/logo.png
/read public/images/hero.jpg

# View binary file information
/read dist/app.js --binary-info

# View package contents
/read package-lock.json --summary

/ls - List Directory Contents

Basic Listing

# List current directory
/ls

# List specific directory
/ls src/
/ls src/components/

# List with details
/ls src/ --details
/ls --all  # Include hidden files

Output Example:

📁 src/ (12 items)
┌─────────────────────────────────────────────────────────┐
│ Name                Type        Size      Modified       │
├─────────────────────────────────────────────────────────┤
│ 📁 components/      Directory   -         2 hours ago    │
│ 📁 hooks/          Directory   -         1 day ago      │
│ 📁 pages/          Directory   -         3 hours ago    │
│ 📁 services/       Directory   -         2 days ago     │
│ 📁 types/          Directory   -         1 day ago      │
│ 📁 utils/          Directory   -         5 hours ago    │
│ 📄 App.tsx         TypeScript  3.2 KB    30 min ago     │
│ 📄 index.tsx       TypeScript  1.8 KB    2 hours ago    │
│ 📄 main.css        CSS         2.1 KB    1 day ago      │
│ 📄 vite-env.d.ts   TypeScript  158 B     1 week ago     │
└─────────────────────────────────────────────────────────┘

Write Operations

/write - Create/Modify Files

File Creation

# Create new file with content
/write src/utils/logger.ts "export const logger = console;"

# Create file with multi-line content
/write src/components/Header.tsx """
import React from 'react';

export const Header: React.FC = () => {
  return (
    <header>
      <h1>My App</h1>
    </header>
  );
};
"""

# Create from template
/write src/pages/NewPage.tsx --template react-page

Approval Workflow:

📝 File Creation Request
───────────────────────────────────────
Operation: Create new file
Path: src/utils/logger.ts
Size: 145 bytes
Type: TypeScript

Content Preview:
┌─────────────────────────────────────┐
│ export const logger = {             │
│   info: (msg: string) => console.  │
│   error: (msg: string) => console. │
│   warn: (msg: string) => console.  │
│ };                                  │
└─────────────────────────────────────┘

Impact Assessment:
├── New dependency: None
├── Breaking changes: None
├── Security risk: Low
└── Test coverage: Manual testing required

Approve file creation? (y/n/edit)

File Modification

# Overwrite entire file
/write src/config/api.ts "export const API_URL = 'https://api.example.com';"

# Append to file
/write src/types/user.ts --append "export interface Admin extends User { role: 'admin' }"

# Insert at specific line
/write src/main.ts --insert-at 5 "import './styles/global.css';"

# Replace specific content
/write src/config/database.ts --replace "localhost" "production-db.example.com"

Modification Approval:

📝 File Modification Request
───────────────────────────────────────
Operation: Modify existing file
Path: src/config/api.ts

Changes:
┌─────────────────────────────────────┐
│ - export const API_URL = 'http://lo │
│ + export const API_URL = 'https://a │
│                                     │
│ + export const API_TIMEOUT = 5000;  │
└─────────────────────────────────────┘

Impact: Production configuration change
Risk Level: MEDIUM

Backup created: .nikcli/backups/api.ts.20240320-143022

Approve changes? (y/n/review)

Batch File Operations

# Create multiple files from template
/write-batch src/components/ --template component --names "Modal,Tooltip,Spinner"

# Update multiple files with same change
/write-batch "src/**/*.ts" --replace "old-import" "new-import"

# Create file structure
/write-structure """
src/
  components/
    Button.tsx: [react-component template]
    Input.tsx: [react-component template]
  hooks/
    useAuth.ts: [custom-hook template]
  types/
    index.ts: [type-definitions template]
"""

/edit - Interactive File Editing

In-place Editing

# Open file in system editor
/edit src/components/App.tsx

# Edit specific lines
/edit src/config/settings.ts --lines 10-20

# Edit with specific editor
/edit src/styles/main.css --editor code
/edit README.md --editor vim

Interactive Editing Session:

📝 Interactive Edit: src/components/App.tsx
───────────────────────────────────────
Opening in VS Code...

⏳ Waiting for editor to close...

✅ File modified (3 changes detected)

Changes Summary:
├── Line 15: Added import statement
├── Line 23: Modified component props
└── Line 31: Added new method

Review changes? (y/n/diff)

Search Operations

/search or /grep - Content Search

Basic Search

# Search for text in files
/search "function handleLogin"
/grep "interface User"

# Search in specific directories
/search "useState" src/components/
/grep "TODO" src/ --recursive

# Case-insensitive search
/search "react" --ignore-case
/grep "API_KEY" --case-insensitive

Search Results:

🔍 Search Results: "useState"
───────────────────────────────────────
Found 12 matches in 8 files

📄 src/components/LoginForm.tsx (3 matches)
├── Line 8:   const [email, setEmail] = useState('');
├── Line 9:   const [password, setPassword] = useState('');
└── Line 10:  const [loading, setLoading] = useState(false);

📄 src/components/UserProfile.tsx (2 matches)
├── Line 15:  const [user, setUser] = useState<User | null>(null);
└── Line 16:  const [editing, setEditing] = useState(false);

📄 src/hooks/useAuth.ts (4 matches)
├── Line 5:   const [token, setToken] = useState<string | null>(null);
├── Line 6:   const [user, setUser] = useState<User | null>(null);
├── Line 7:   const [loading, setLoading] = useState(true);
└── Line 8:   const [error, setError] = useState<string | null>(null);

Show more results? (y/n/open)

Advanced Search Patterns

# Regular expression search
/search "function\s+\w+\(" --regex
/grep "export\s+(const|function)\s+\w+" --regex

# Search by file type
/search "console.log" --type typescript
/grep "margin:" --type css

# Exclude patterns
/search "debug" --exclude "*.test.ts" --exclude "node_modules"

# Search with context
/search "error" --context 3  # 3 lines before and after
/grep "TODO" --before 2 --after 1

Structured Search

# Search for specific code patterns
/search --pattern "react-component-definition"
/search --pattern "function-with-async"
/search --pattern "import-statement"

# Search for dependencies
/search --dependencies "react"
/search --unused-imports
/search --unused-variables

# Search for security issues
/search --security-patterns
/search --potential-vulnerabilities

Pattern Search Results:

🔍 Pattern Search: "react-component-definition"
───────────────────────────────────────
Found 15 React components

📄 src/components/Button.tsx
├── Component: Button (Functional Component)
├── Props: ButtonProps interface
├── Exports: Named export
└── Uses: React.FC pattern

📄 src/components/Modal.tsx
├── Component: Modal (Functional Component)
├── Props: ModalProps interface  
├── Exports: Default export
└── Uses: forwardRef pattern

📄 src/pages/Dashboard.tsx
├── Component: Dashboard (Functional Component)
├── Props: No props interface
├── Exports: Default export
└── Uses: Basic function declaration

Analysis Summary:
├── Functional Components: 15 (100%)
├── Class Components: 0 (0%)
├── Components with Props: 12 (80%)
└── Components with TypeScript: 15 (100%)

/find - Find Files by Name

Basic File Finding

# Find files by name
/find "Button.tsx"
/find "*.css"
/find "test.*"

# Find in specific directories
/find "*.ts" src/
/find "package.json" --recursive

# Find by partial name
/find "*component*" --ignore-case

Find Results:

📁 Find Results: "*.tsx"
───────────────────────────────────────
Found 23 files

📄 src/components/
├── Button.tsx (2.3 KB)
├── Modal.tsx (4.1 KB)
├── Form.tsx (5.2 KB)
├── Header.tsx (1.8 KB)
└── Navigation.tsx (3.4 KB)

📄 src/pages/
├── Home.tsx (6.7 KB)
├── Login.tsx (3.9 KB)
├── Dashboard.tsx (8.2 KB)
└── Profile.tsx (4.5 KB)

📄 src/
├── App.tsx (2.1 KB)
└── main.tsx (0.8 KB)

Total: 23 files, 52.9 KB

Security and Permissions

File Access Control

Permission Levels

# Check current permissions
/permissions

# View file-specific permissions
/permissions src/config/secrets.ts

# Request elevated permissions
/request-permission write-config
/request-permission read-sensitive

Permission Status:

🔒 File Operation Permissions
───────────────────────────────────────
Current Security Level: 🛡️ Default

Read Permissions:
├── ✅ Source code files (src/*)
├── ✅ Configuration files (*.json, *.yaml)
├── ✅ Documentation (*.md, docs/*)
├── ⚠️  Environment files (.env.*) - Approval required
└── ❌ System files (/etc, /usr) - Blocked

Write Permissions:
├── ✅ Source code files (src/*)
├── ⚠️  Configuration files - Approval required
├── ⚠️  Package files (package.json) - Approval required
├── ❌ Environment files - Blocked in default mode
└── ❌ System files - Always blocked

Special Operations:
├── ✅ File backups - Automatic
├── ✅ Syntax validation - Automatic
├── ⚠️  Bulk operations - Approval required
└── ⚠️  Destructive operations - Approval required

Approval Workflows

🛡️ Security Approval Required
───────────────────────────────────────
Operation: Modify configuration file
File: package.json
Risk Level: MEDIUM

Requested Changes:
┌─────────────────────────────────────┐
│ + "express": "^4.18.2",            │
│ + "cors": "^2.8.5",                │
│ + "dotenv": "^16.0.3"              │
└─────────────────────────────────────┘

Impact Analysis:
├── New dependencies: 3 packages
├── Security scan: ✅ No vulnerabilities
├── Bundle size impact: +245 KB
├── Breaking changes: None detected
└── Backup created: ✅

Options:
[A] Approve and continue
[R] Reject operation
[M] Modify request
[I] Show detailed impact analysis

Choice: _

Backup and Recovery

# Manual backup
/backup src/components/
/backup package.json

# List backups
/backups list
/backups list --recent

# Restore from backup
/restore package.json
/restore src/components/Button.tsx --version 2024-03-20-14:30

# Compare with backup
/diff-backup src/config/api.ts

Backup Management:

📦 Backup Management
───────────────────────────────────────
Auto-backup: ✅ Enabled (before destructive operations)
Backup Location: .nikcli/backups/
Retention: 30 days (configurable)

Recent Backups:
├── 2024-03-20 14:30 - package.json (dependency update)
├── 2024-03-20 13:45 - src/api/auth.ts (refactoring)
├── 2024-03-20 12:15 - src/components/ (batch update)
├── 2024-03-20 10:30 - .env.example (configuration)
└── 2024-03-19 16:20 - src/types/user.ts (type changes)

Storage Used: 2.3 MB / 100 MB limit

Commands:
[L] List all backups
[R] Restore specific backup
[C] Clean old backups
[S] Show backup settings

Performance and Optimization

Efficient File Operations

Batch Operations

Process multiple files efficiently

# Batch read
/read src/components/*.tsx --batch

# Batch search
/search "useState" src/ --batch --parallel

# Batch write with template
/write-batch --template component --count 5

Streaming Operations

Handle large files efficiently

# Stream large file content
/read logs/app.log --stream

# Tail file content
/tail logs/error.log --follow

# Process in chunks
/search "error" logs/ --chunk-size 1MB

Caching and Optimization

File Caching

# Enable file content caching
nikcli config set file-cache.enabled true
nikcli config set file-cache.max-size 100MB

# Clear file cache
/cache clear --files
/cache clear --search-results

# Cache statistics
/cache stats

Best Practices

Safety First

Always prioritize data safety

• Review changes before approval
• Use backups for important files
• Test in development first
• Understand permission implications

Efficiency

Optimize your file operations

• Use batch operations for multiple files
• Leverage caching for repeated operations
• Use specific paths to reduce search scope
• Enable indexing for frequent searches

Organization

Maintain clean file structure

• Use consistent naming conventions
• Organize files logically
• Regular cleanup of temporary files
• Document file organization patterns

Collaboration

Team-friendly practices

• Document file changes clearly
• Use meaningful commit messages
• Coordinate on file modifications
• Share file operation patterns

Next Steps

Terminal Operations

Learn command execution and terminal integration

Project Operations

Master project-level operations and management

Advanced Configuration

Configure file operation security and preferences

Workflow Patterns

Integrate file operations into development workflows

File operations in NikCLI respect security policies and may require approval for sensitive files. Always review changes before approving destructive operations.