# ShellJS — Portable Unix Shell Commands for Node.js

> A portable implementation of Unix shell commands on top of the Node.js API, enabling cross-platform shell scripting without external dependencies.

## Install

Save in your project root:

# ShellJS — Portable Unix Shell Commands for Node.js

## Quick Use
```bash
npm install shelljs
```
```javascript
const shell = require('shelljs');
shell.echo('Starting deploy...');
shell.cd('project');
shell.exec('git pull');
shell.cp('-R', 'dist/*', '/srv/www');
```

## Introduction
ShellJS is a portable implementation of Unix shell commands written entirely in JavaScript for Node.js. It allows developers to write cross-platform shell scripts without relying on platform-specific shells, making build scripts and automation work identically on Linux, macOS, and Windows.

## What ShellJS Does
- Implements common Unix commands like cp, rm, mv, mkdir, cat, grep, and sed in JavaScript
- Provides a synchronous API that mirrors traditional shell scripting patterns
- Runs identically on Windows, macOS, and Linux without shell dependencies
- Offers glob pattern matching for file operations
- Supports command chaining and piping between operations

## Architecture Overview
ShellJS re-implements each Unix command as a pure JavaScript function using Node.js built-in modules like fs, path, and child_process. The synchronous design keeps scripts readable and sequential. File operations use Node.js fs APIs directly, while exec() wraps child_process.execSync for external commands.

## Self-Hosting & Configuration
- Install with `npm install shelljs` in any Node.js project
- Require with `const shell = require('shelljs')` or use ES module import
- Enable silent mode with `shell.config.silent = true` to suppress output
- Set `shell.config.fatal = true` to throw errors on command failure
- Use `shell.which('git')` to check if external tools are available before use

## Key Features
- No external dependencies: every command is pure JavaScript
- Familiar Unix syntax reduces the learning curve for shell scripters
- Synchronous execution model simplifies scripting logic
- Built-in glob support for file matching patterns
- Pipe support via `.to()` and `.toEnd()` for output redirection

## Comparison with Similar Tools
- **zx** — async-first with modern syntax; ShellJS is synchronous and CommonJS-based
- **Execa** — focuses on process spawning; ShellJS reimplements shell built-ins natively
- **Bash scripts** — platform-dependent; ShellJS works on any OS with Node.js
- **cross-env** — only handles environment variables; ShellJS covers the full shell command set
- **Node.js fs module** — low-level API; ShellJS provides high-level shell-like abstractions

## FAQ
**Q: Does ShellJS require Bash or any system shell?**
A: No. All commands except `exec()` are implemented in pure JavaScript and require no system shell.

**Q: Can I use ShellJS with ES modules?**
A: Yes. ShellJS supports both CommonJS require and ES module import syntax.

**Q: Is ShellJS suitable for production build scripts?**
A: Yes. It is widely used in CI/CD pipelines and npm scripts for cross-platform build automation.

**Q: How does error handling work?**
A: Each command returns an object with a `code` property. Set `config.fatal = true` to throw on non-zero exit codes.

## Sources
- https://github.com/shelljs/shelljs
- https://www.npmjs.com/package/shelljs

---
Source: https://tokrepo.com/en/workflows/asset-049266ef
Author: AI Open Source