or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdfile-system.mdindex.mdprocess-management.mdtext-processing.md
tile.json

tessl/npm-shelljs

Portable Unix shell commands for Node.js that provide cross-platform compatibility across Windows, Linux, and macOS.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/shelljs@0.10.x

To install, run

npx @tessl/cli install tessl/npm-shelljs@0.10.0

index.mddocs/

ShellJS

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.

Package Information

  • Package Name: shelljs
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install shelljs

Core Imports

const shell = require('shelljs');

ES6 modules:

import shell from 'shelljs';

Global import (not recommended for production):

require('shelljs/global');
// Now all commands are available globally: ls(), cd(), etc.

Basic Usage

const shell = require('shelljs');

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

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

// Replace macros in each .js file
shell.cd('lib');
shell.ls('*.js').forEach(function (file) {
  shell.sed('-i', 'BUILD_VERSION', 'v0.1.2', file);
  shell.sed('-i', /^.*REMOVE_THIS_LINE.*$/, '', file);
});
shell.cd('..');

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

Architecture

ShellJS is built around several key components:

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

Capabilities

File System Operations

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

function cat(options?: string, ...files: string[]): ShellString;
function cd(dir?: string): ShellString;
function chmod(options: string, mode: string | number, file: string): ShellString;
function cp(options: string, source: string | string[], dest: string): ShellString;
function find(path: string | string[]): ShellString;
function ln(options?: string, source: string, dest: string): ShellString;
function ls(options?: string, ...paths: string[]): ShellString;
function mkdir(options?: string, ...dirs: string[]): ShellString;
function mv(options?: string, source: string | string[], dest: string): ShellString;
function pwd(): ShellString;
function rm(options?: string, ...files: string[]): ShellString;
function tempdir(): ShellString;
function test(expression: string): boolean;
function touch(options?: string, ...files: string[]): ShellString;
function which(command: string): ShellString;

File System Commands

Text Processing

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

function echo(options?: string, ...text: string[]): ShellString;
function grep(options: string, regex: RegExp | string, ...files: string[]): ShellString;
function head(options?: object, ...files: string[]): ShellString;
function sed(options: string, searchRegex: RegExp | string, replacement: string, ...files: string[]): ShellString;
function sort(options?: string, ...files: string[]): ShellString;
function tail(options?: object, ...files: string[]): ShellString;
function uniq(options?: string, input?: string, output?: string): ShellString;

Text Processing Commands

Process Management

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

function exec(command: string, options?: ExecOptions, callback?: ExecCallback): ShellString;
function exit(code?: number): void;
function pushd(options?: string, dir?: string): ShellString;
function popd(options?: string, dir?: string): ShellString;
function dirs(options?: string): ShellString;

Process Management

Configuration and Utilities

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

const config: {
  silent: boolean;
  fatal: boolean;
  verbose: boolean;
  globOptions: object;
  execPath: string | null;
  reset(): void;
};

const env: NodeJS.ProcessEnv;

function error(): string | null;
function errorCode(): number;
function set(options: string): ShellString;

class ShellString extends String {
  stdout: string;
  stderr: string;
  code: number;
  to(file: string): ShellString;
  toEnd(file: string): ShellString;
}

Configuration and Utilities

Types

interface ExecOptions {
  encoding?: string;
  silent?: boolean;
  async?: boolean;
  fatal?: boolean;
  cwd?: string;
  env?: object;
  maxBuffer?: number;
}

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

class ShellString extends String {
  stdout: string;
  stderr: string;
  code: number;
  
  constructor(stdout: string | string[], stderr?: string, code?: number);
  
  to(file: string): ShellString;
  toEnd(file: string): ShellString;
}

Error Handling

ShellJS provides multiple ways to handle command errors:

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

Piping and Chaining

Commands return ShellString objects that support method chaining and piping:

// Method chaining
grep('foo', 'file1.txt', 'file2.txt').sed(/o/g, 'a').to('output.txt');

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

// Pipe to exec
cat('test.js').exec('node');

Plugin System

ShellJS supports third-party plugins via the plugin API:

const shell = require('shelljs');
const plugin = require('shelljs/plugin');

// Register a custom command
plugin.register('customCommand', customCommandFunction, {
  // Plugin options
});