0
# ShellJS
1

2
ShellJS is a portable Unix shell command implementation for Node.js that provides cross-platform compatibility across Windows, Linux, and macOS. It offers a comprehensive set of synchronous shell commands through a JavaScript API, eliminating the need for platform-specific shell scripts while maintaining familiar Unix command syntax.
3

4
## Package Information
5

6
- **Package Name**: shelljs
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install shelljs`
10

11
## Core Imports
12

13
```javascript
14
const shell = require('shelljs');
15
```
16

17
ES6 modules:
18

19
```javascript
20
import shell from 'shelljs';
21
```
22

23
Global import (not recommended for production):
24

25
```javascript
26
require('shelljs/global');
27
// Now all commands are available globally: ls(), cd(), etc.
28
```
29

30
## Basic Usage
31

32
```javascript
33
const shell = require('shelljs');
34

35
if (!shell.which('git')) {
36
  shell.echo('Sorry, this script requires git');
37
  shell.exit(1);
38
}
39

40
// Copy files to release dir
41
shell.rm('-rf', 'out/Release');
42
shell.cp('-R', 'stuff/', 'out/Release');
43

44
// Replace macros in each .js file
45
shell.cd('lib');
46
shell.ls('*.js').forEach(function (file) {
47
  shell.sed('-i', 'BUILD_VERSION', 'v0.1.2', file);
48
  shell.sed('-i', /^.*REMOVE_THIS_LINE.*$/, '', file);
49
});
50
shell.cd('..');
51

52
// Run external tool synchronously
53
if (shell.exec('git commit -am "Auto-commit"').code !== 0) {
54
  shell.echo('Error: Git commit failed');
55
  shell.exit(1);
56
}
57
```
58

59
## Architecture
60

61
ShellJS is built around several key components:
62

63
- **Command Registration System**: All commands are registered via a plugin architecture using `common.register()`
64
- **ShellString Class**: Return type that wraps command output and enables method chaining and piping
65
- **Configuration System**: Global configuration object controlling command behavior (silent, fatal, verbose modes)
66
- **Cross-Platform Compatibility**: Unified API that abstracts platform differences for file operations
67
- **Piping and Chaining**: Commands can be chained together using method calls or piped for complex operations
68
- **Plugin System**: Extensible architecture allowing third-party commands via the plugin API
69

70
## Capabilities
71

72
### File System Operations
73

74
Core file and directory manipulation commands including copy, move, remove, list, and permission changes. Essential for build scripts and file management automation.
75

76
```javascript { .api }
77
function cat(options?: string, ...files: string[]): ShellString;
78
function cd(dir?: string): ShellString;
79
function chmod(options: string, mode: string | number, file: string): ShellString;
80
function cp(options: string, source: string | string[], dest: string): ShellString;
81
function find(path: string | string[]): ShellString;
82
function ln(options?: string, source: string, dest: string): ShellString;
83
function ls(options?: string, ...paths: string[]): ShellString;
84
function mkdir(options?: string, ...dirs: string[]): ShellString;
85
function mv(options?: string, source: string | string[], dest: string): ShellString;
86
function pwd(): ShellString;
87
function rm(options?: string, ...files: string[]): ShellString;
88
function tempdir(): ShellString;
89
function test(expression: string): boolean;
90
function touch(options?: string, ...files: string[]): ShellString;
91
function which(command: string): ShellString;
92
```
93

94
[File System Commands](./file-system.md)
95

96
### Text Processing
97

98
Text manipulation and filtering commands for processing file contents, searching patterns, and transforming text data.
99

100
```javascript { .api }
101
function echo(options?: string, ...text: string[]): ShellString;
102
function grep(options: string, regex: RegExp | string, ...files: string[]): ShellString;
103
function head(options?: object, ...files: string[]): ShellString;
104
function sed(options: string, searchRegex: RegExp | string, replacement: string, ...files: string[]): ShellString;
105
function sort(options?: string, ...files: string[]): ShellString;
106
function tail(options?: object, ...files: string[]): ShellString;
107
function uniq(options?: string, input?: string, output?: string): ShellString;
108
```
109

110
[Text Processing Commands](./text-processing.md)
111

112
### Process Management
113

114
Commands for executing external processes, managing directories, and controlling the shell environment.
115

116
```javascript { .api }
117
function exec(command: string, options?: ExecOptions, callback?: ExecCallback): ShellString;
118
function exit(code?: number): void;
119
function pushd(options?: string, dir?: string): ShellString;
120
function popd(options?: string, dir?: string): ShellString;
121
function dirs(options?: string): ShellString;
122
```
123

124
[Process Management](./process-management.md)
125

126
### Configuration and Utilities
127

128
Configuration system, error handling, environment variables, and utility functions for controlling ShellJS behavior.
129

130
```javascript { .api }
131
const config: {
132
  silent: boolean;
133
  fatal: boolean;
134
  verbose: boolean;
135
  globOptions: object;
136
  execPath: string | null;
137
  reset(): void;
138
};
139

140
const env: NodeJS.ProcessEnv;
141

142
function error(): string | null;
143
function errorCode(): number;
144
function set(options: string): ShellString;
145

146
class ShellString extends String {
147
  stdout: string;
148
  stderr: string;
149
  code: number;
150
  to(file: string): ShellString;
151
  toEnd(file: string): ShellString;
152
}
153
```
154

155
[Configuration and Utilities](./configuration.md)
156

157
## Types
158

159
```javascript { .api }
160
interface ExecOptions {
161
  encoding?: string;
162
  silent?: boolean;
163
  async?: boolean;
164
  fatal?: boolean;
165
  cwd?: string;
166
  env?: object;
167
  maxBuffer?: number;
168
}
169

170
type ExecCallback = (code: number, stdout: string, stderr: string) => void;
171

172
class ShellString extends String {
173
  stdout: string;
174
  stderr: string;
175
  code: number;
176
  
177
  constructor(stdout: string | string[], stderr?: string, code?: number);
178
  
179
  to(file: string): ShellString;
180
  toEnd(file: string): ShellString;
181
}
182
```
183

184
## Error Handling
185

186
ShellJS provides multiple ways to handle command errors:
187

188
- **Error State**: Use `error()` to check if the last command failed
189
- **Error Codes**: Use `errorCode()` to get the numeric exit code
190
- **Fatal Mode**: Set `config.fatal = true` to throw JavaScript errors on command failures
191
- **Return Values**: Check the `code` property of ShellString return values
192

193
## Piping and Chaining
194

195
Commands return ShellString objects that support method chaining and piping:
196

197
```javascript
198
// Method chaining
199
grep('foo', 'file1.txt', 'file2.txt').sed(/o/g, 'a').to('output.txt');
200

201
// Piping with other commands
202
echo("files with o's in the name:\n" + ls().grep('o'));
203

204
// Pipe to exec
205
cat('test.js').exec('node');
206
```
207

208
## Plugin System
209

210
ShellJS supports third-party plugins via the plugin API:
211

212
```javascript
213
const shell = require('shelljs');
214
const plugin = require('shelljs/plugin');
215

216
// Register a custom command
217
plugin.register('customCommand', customCommandFunction, {
218
  // Plugin options
219
});
220
```