0
# File System Commands
1

2
Core file and directory manipulation commands providing cross-platform file operations with Unix-style syntax and options.
3

4
## Capabilities
5

6
### cat - Concatenate Files
7

8
Concatenates and displays file contents, similar to Unix cat command.
9

10
```javascript { .api }
11
/**
12
 * Concatenate and display file contents
13
 * @param options - Command options
14
 * @param files - Files to concatenate
15
 * @returns ShellString containing concatenated file contents
16
 */
17
function cat(options?: string, ...files: string[]): ShellString;
18
function cat(files: string[]): ShellString;
19
```
20

21
**Options:**
22
- `-n`: Number all output lines
23

24
**Usage Examples:**
25

26
```javascript
27
// Read single file
28
const content = shell.cat('file.txt');
29

30
// Concatenate multiple files
31
const combined = shell.cat('file1.txt', 'file2.txt');
32

33
// Number lines in output
34
const numbered = shell.cat('-n', 'file.txt');
35

36
// From array of files
37
const fromArray = shell.cat(['file1.txt', 'file2.txt']);
38
```
39

40
### cd - Change Directory
41

42
Changes the current working directory.
43

44
```javascript { .api }
45
/**
46
 * Change current working directory
47
 * @param dir - Directory path to change to (defaults to home directory)
48
 * @returns ShellString with directory change result
49
 */
50
function cd(dir?: string): ShellString;
51
```
52

53
**Usage Examples:**
54

55
```javascript
56
// Change to specific directory
57
shell.cd('/path/to/directory');
58

59
// Change to home directory
60
shell.cd();
61

62
// Relative path navigation
63
shell.cd('../..');
64
shell.cd('./subdirectory');
65
```
66

67
### chmod - Change File Permissions
68

69
Changes file permissions using octal or symbolic notation.
70

71
```javascript { .api }
72
/**
73
 * Change file permissions
74
 * @param options - Command options
75
 * @param mode - Permission mode (octal number, octal string, or symbolic)
76
 * @param file - File or directory to modify
77
 * @returns ShellString with operation result
78
 */
79
function chmod(options: string, mode: string | number, file: string): ShellString;
80
function chmod(mode: string | number, file: string): ShellString;
81
```
82

83
**Options:**
84
- `-v`: Verbose output showing changes made
85
- `-c`: Report only changes made
86
- `-R`: Recursive operation on directories
87

88
**Usage Examples:**
89

90
```javascript
91
// Octal notation
92
shell.chmod(755, 'script.sh');
93
shell.chmod('755', 'script.sh');
94

95
// Recursive permission change
96
shell.chmod('-R', 755, 'directory/');
97

98
// Symbolic notation
99
shell.chmod('u+x', 'script.sh');
100
shell.chmod('go-w', 'file.txt');
101
```
102

103
### cp - Copy Files
104

105
Copies files and directories with various options for different copy behaviors.
106

107
```javascript { .api }
108
/**
109
 * Copy files and directories
110
 * @param options - Command options
111
 * @param source - Source file(s) or directory
112
 * @param dest - Destination path
113
 * @returns ShellString with operation result
114
 */
115
function cp(options: string, source: string | string[], dest: string): ShellString;
116
function cp(source: string | string[], dest: string): ShellString;
117
```
118

119
**Options:**
120
- `-f`: Force copy, overwrite existing files
121
- `-n`: No-clobber, don't overwrite existing files
122
- `-u`: Update, copy only if source is newer than destination
123
- `-r`, `-R`: Recursive copy for directories
124
- `-L`: Follow symbolic links
125
- `-P`: Don't follow symbolic links (default)
126

127
**Usage Examples:**
128

129
```javascript
130
// Simple file copy
131
shell.cp('source.txt', 'destination.txt');
132

133
// Recursive directory copy
134
shell.cp('-R', 'source_dir/', 'dest_dir/');
135

136
// Force overwrite
137
shell.cp('-f', 'file.txt', 'existing_file.txt');
138

139
// Copy multiple files to directory
140
shell.cp(['file1.txt', 'file2.txt'], 'target_dir/');
141
```
142

143
### find - Find Files
144

145
Finds files and directories recursively from specified paths.
146

147
```javascript { .api }
148
/**
149
 * Find files and directories recursively
150
 * @param path - Path(s) to search
151
 * @returns ShellString containing array of found file paths
152
 */
153
function find(path: string | string[]): ShellString;
154
```
155

156
**Usage Examples:**
157

158
```javascript
159
// Find all files in current directory
160
const files = shell.find('.');
161

162
// Find in multiple directories
163
const allFiles = shell.find(['dir1', 'dir2']);
164

165
// Combine with grep for filtering
166
const jsFiles = shell.find('.').grep('\\.js$');
167
```
168

169
### ls - List Directory Contents
170

171
Lists directory contents with various formatting and filtering options.
172

173
```javascript { .api }
174
/**
175
 * List directory contents
176
 * @param options - Command options
177
 * @param paths - Paths to list (defaults to current directory)
178
 * @returns ShellString containing array of file/directory names
179
 */
180
function ls(options?: string, ...paths: string[]): ShellString;
181
function ls(paths: string[]): ShellString;
182
```
183

184
**Options:**
185
- `-R`: Recursive listing
186
- `-A`: Show all files except . and ..
187
- `-L`: Follow symbolic links
188
- `-d`: List directories themselves, not their contents
189
- `-l`: Long format with detailed information
190
- `-a`: Show all files including hidden (deprecated, use -A)
191

192
**Usage Examples:**
193

194
```javascript
195
// List current directory
196
const files = shell.ls();
197

198
// List specific directory
199
const dirFiles = shell.ls('/path/to/dir');
200

201
// Recursive listing
202
const allFiles = shell.ls('-R');
203

204
// Long format with details
205
const detailed = shell.ls('-l');
206

207
// Show hidden files
208
const hidden = shell.ls('-A');
209
```
210

211
### ln - Create Links
212

213
Creates hard or symbolic links between files and directories.
214

215
```javascript { .api }
216
/**
217
 * Create hard or symbolic links
218
 * @param options - Command options
219
 * @param source - Source file or directory path
220
 * @param dest - Destination link path
221
 * @returns ShellString indicating success or failure
222
 */
223
function ln(options?: string, source: string, dest: string): ShellString;
224
```
225

226
**Options:**
227
- `-s`: Create symbolic link instead of hard link
228
- `-f`: Force link creation, removing existing destination if it exists
229

230
**Usage Examples:**
231

232
```javascript
233
// Create hard link
234
shell.ln('original.txt', 'hardlink.txt');
235

236
// Create symbolic link
237
shell.ln('-s', 'original.txt', 'symlink.txt');
238

239
// Force link creation (overwrite existing)
240
shell.ln('-sf', 'target.txt', 'existing_link.txt');
241

242
// Create directory symlink (Unix/macOS)
243
shell.ln('-s', '/path/to/original/dir', 'link_to_dir');
244
```
245

246
**Notes:**
247
- Hard links share the same inode, so changes to either file affect both
248
- Symbolic links are shortcuts that point to the original file path
249
- On Windows, directory symbolic links are created as junctions
250
- The source file must exist when creating hard links
251
- Symbolic links can point to non-existent files (broken links)
252

253
### mkdir - Create Directories
254

255
Creates directories with support for creating parent directories.
256

257
```javascript { .api }
258
/**
259
 * Create directories
260
 * @param options - Command options
261
 * @param dirs - Directory names to create
262
 * @returns ShellString with operation result
263
 */
264
function mkdir(options?: string, ...dirs: string[]): ShellString;
265
function mkdir(dirs: string[]): ShellString;
266
```
267

268
**Options:**
269
- `-p`: Create parent directories as needed
270

271
**Usage Examples:**
272

273
```javascript
274
// Create single directory
275
shell.mkdir('new_directory');
276

277
// Create multiple directories
278
shell.mkdir('dir1', 'dir2', 'dir3');
279

280
// Create nested directory structure
281
shell.mkdir('-p', 'path/to/nested/directory');
282

283
// From array
284
shell.mkdir(['dir1', 'dir2']);
285
```
286

287
### mv - Move/Rename Files
288

289
Moves or renames files and directories.
290

291
```javascript { .api }
292
/**
293
 * Move or rename files and directories
294
 * @param options - Command options
295
 * @param source - Source file(s) or directory
296
 * @param dest - Destination path
297
 * @returns ShellString with operation result
298
 */
299
function mv(options?: string, source: string | string[], dest: string): ShellString;
300
```
301

302
**Options:**
303
- `-f`: Force move, overwrite existing files
304
- `-n`: No-clobber, don't overwrite existing files
305

306
**Usage Examples:**
307

308
```javascript
309
// Rename file
310
shell.mv('oldname.txt', 'newname.txt');
311

312
// Move file to directory
313
shell.mv('file.txt', 'target_directory/');
314

315
// Move multiple files
316
shell.mv(['file1.txt', 'file2.txt'], 'target_directory/');
317

318
// Force overwrite
319
shell.mv('-f', 'source.txt', 'existing_target.txt');
320
```
321

322
### pwd - Print Working Directory
323

324
Returns the current working directory path.
325

326
```javascript { .api }
327
/**
328
 * Get current working directory
329
 * @returns ShellString containing current directory path
330
 */
331
function pwd(): ShellString;
332
```
333

334
**Usage Examples:**
335

336
```javascript
337
// Get current directory
338
const currentDir = shell.pwd();
339
console.log('Current directory:', currentDir.toString());
340

341
// Use in path operations
342
const fullPath = shell.pwd() + '/relative/path';
343
```
344

345
### rm - Remove Files
346

347
Removes files and directories with options for recursive and forced deletion.
348

349
```javascript { .api }
350
/**
351
 * Remove files and directories
352
 * @param options - Command options
353
 * @param files - Files or directories to remove
354
 * @returns ShellString with operation result
355
 */
356
function rm(options?: string, ...files: string[]): ShellString;
357
function rm(files: string[]): ShellString;
358
```
359

360
**Options:**
361
- `-f`: Force removal, ignore nonexistent files
362
- `-r`, `-R`: Recursive removal for directories
363

364
**Usage Examples:**
365

366
```javascript
367
// Remove single file
368
shell.rm('file.txt');
369

370
// Remove multiple files
371
shell.rm('file1.txt', 'file2.txt');
372

373
// Recursive directory removal
374
shell.rm('-rf', 'directory_to_remove/');
375

376
// Force removal
377
shell.rm('-f', 'might_not_exist.txt');
378

379
// From array
380
shell.rm(['file1.txt', 'file2.txt']);
381
```
382

383
### tempdir - Get Temporary Directory
384

385
Returns the system temporary directory path.
386

387
```javascript { .api }
388
/**
389
 * Get system temporary directory path
390
 * @returns ShellString containing temporary directory path
391
 */
392
function tempdir(): ShellString;
393
```
394

395
**Usage Examples:**
396

397
```javascript
398
// Get temp directory
399
const tmpDir = shell.tempdir();
400

401
// Create temporary file path
402
const tmpFile = shell.tempdir() + '/mytemp.txt';
403
```
404

405
### test - Test File Attributes
406

407
Tests file existence and attributes using Unix test expressions.
408

409
```javascript { .api }
410
/**
411
 * Test file attributes and existence
412
 * @param expression - Test expression (e.g., '-e', '-f', '-d')
413
 * @returns Boolean result of the test
414
 */
415
function test(expression: string): boolean;
416
```
417

418
**Test Expressions:**
419
- `-e`: File exists
420
- `-f`: File exists and is a regular file
421
- `-d`: File exists and is a directory
422
- `-L`: File exists and is a symbolic link
423
- `-r`: File exists and is readable
424
- `-w`: File exists and is writable
425
- `-x`: File exists and is executable
426
- `-S`: File exists and is a socket
427
- `-p`: File exists and is a pipe
428
- `-c`: File exists and is a character device
429
- `-b`: File exists and is a block device
430

431
**Usage Examples:**
432

433
```javascript
434
// Check if file exists
435
if (shell.test('-e', 'file.txt')) {
436
  console.log('File exists');
437
}
438

439
// Check if directory
440
if (shell.test('-d', 'my_directory')) {
441
  console.log('Is a directory');
442
}
443

444
// Check if executable
445
if (shell.test('-x', 'script.sh')) {
446
  shell.exec('./script.sh');
447
}
448
```
449

450
### touch - Create/Update Files
451

452
Creates empty files or updates timestamps of existing files.
453

454
```javascript { .api }
455
/**
456
 * Create files or update timestamps
457
 * @param options - Command options
458
 * @param files - Files to create or update
459
 * @returns ShellString with operation result
460
 */
461
function touch(options?: string, ...files: string[]): ShellString;
462
function touch(files: string[]): ShellString;
463
```
464

465
**Options:**
466
- `-a`: Change only access time
467
- `-c`: Don't create files that don't exist
468
- `-m`: Change only modification time
469
- `-d <date>`: Use specified date instead of current time
470
- `-r <file>`: Use timestamp from reference file
471

472
**Usage Examples:**
473

474
```javascript
475
// Create empty file
476
shell.touch('newfile.txt');
477

478
// Create multiple files
479
shell.touch('file1.txt', 'file2.txt');
480

481
// Update only access time
482
shell.touch('-a', 'existing_file.txt');
483

484
// Don't create if doesn't exist
485
shell.touch('-c', 'might_exist.txt');
486

487
// From array
488
shell.touch(['file1.txt', 'file2.txt']);
489
```
490

491
### which - Locate Command
492

493
Locates executable programs in the system PATH.
494

495
```javascript { .api }
496
/**
497
 * Locate executable programs in PATH
498
 * @param command - Command name to locate
499
 * @returns ShellString containing path to executable, or null if not found
500
 */
501
function which(command: string): ShellString | null;
502
```
503

504
**Usage Examples:**
505

506
```javascript
507
// Check if command exists
508
const gitPath = shell.which('git');
509
if (gitPath) {
510
  console.log('Git is installed at:', gitPath.toString());
511
} else {
512
  console.log('Git is not installed');
513
}
514

515
// Use in conditional logic
516
if (!shell.which('node')) {
517
  shell.echo('Node.js is required but not installed');
518
  shell.exit(1);
519
}
520
```