tessl/npm-shelljs

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

—

Pending

Overview

Eval results

Files

File System Commands

Name: tessl/npm-shelljs
Author: tessl

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

Capabilities

cat - Concatenate Files

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

/**
 * Concatenate and display file contents
 * @param options - Command options
 * @param files - Files to concatenate
 * @returns ShellString containing concatenated file contents
 */
function cat(options?: string, ...files: string[]): ShellString;
function cat(files: string[]): ShellString;

Options:

-n: Number all output lines

Usage Examples:

// Read single file
const content = shell.cat('file.txt');

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

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

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

cd - Change Directory

Changes the current working directory.

/**
 * Change current working directory
 * @param dir - Directory path to change to (defaults to home directory)
 * @returns ShellString with directory change result
 */
function cd(dir?: string): ShellString;

Usage Examples:

// Change to specific directory
shell.cd('/path/to/directory');

// Change to home directory
shell.cd();

// Relative path navigation
shell.cd('../..');
shell.cd('./subdirectory');

chmod - Change File Permissions

Changes file permissions using octal or symbolic notation.

/**
 * Change file permissions
 * @param options - Command options
 * @param mode - Permission mode (octal number, octal string, or symbolic)
 * @param file - File or directory to modify
 * @returns ShellString with operation result
 */
function chmod(options: string, mode: string | number, file: string): ShellString;
function chmod(mode: string | number, file: string): ShellString;

Options:

-v: Verbose output showing changes made
-c: Report only changes made
-R: Recursive operation on directories

Usage Examples:

// Octal notation
shell.chmod(755, 'script.sh');
shell.chmod('755', 'script.sh');

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

// Symbolic notation
shell.chmod('u+x', 'script.sh');
shell.chmod('go-w', 'file.txt');

cp - Copy Files

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

/**
 * Copy files and directories
 * @param options - Command options
 * @param source - Source file(s) or directory
 * @param dest - Destination path
 * @returns ShellString with operation result
 */
function cp(options: string, source: string | string[], dest: string): ShellString;
function cp(source: string | string[], dest: string): ShellString;

Options:

-f: Force copy, overwrite existing files
-n: No-clobber, don't overwrite existing files
-u: Update, copy only if source is newer than destination
-r, -R: Recursive copy for directories
-L: Follow symbolic links
-P: Don't follow symbolic links (default)

Usage Examples:

// Simple file copy
shell.cp('source.txt', 'destination.txt');

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

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

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

find - Find Files

Finds files and directories recursively from specified paths.

/**
 * Find files and directories recursively
 * @param path - Path(s) to search
 * @returns ShellString containing array of found file paths
 */
function find(path: string | string[]): ShellString;

Usage Examples:

// Find all files in current directory
const files = shell.find('.');

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

// Combine with grep for filtering
const jsFiles = shell.find('.').grep('\\.js$');

ls - List Directory Contents

Lists directory contents with various formatting and filtering options.

/**
 * List directory contents
 * @param options - Command options
 * @param paths - Paths to list (defaults to current directory)
 * @returns ShellString containing array of file/directory names
 */
function ls(options?: string, ...paths: string[]): ShellString;
function ls(paths: string[]): ShellString;

Options:

-R: Recursive listing
-A: Show all files except . and ..
-L: Follow symbolic links
-d: List directories themselves, not their contents
-l: Long format with detailed information
-a: Show all files including hidden (deprecated, use -A)

Usage Examples:

// List current directory
const files = shell.ls();

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

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

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

// Show hidden files
const hidden = shell.ls('-A');

ln - Create Links

Creates hard or symbolic links between files and directories.

/**
 * Create hard or symbolic links
 * @param options - Command options
 * @param source - Source file or directory path
 * @param dest - Destination link path
 * @returns ShellString indicating success or failure
 */
function ln(options?: string, source: string, dest: string): ShellString;

Options:

-s: Create symbolic link instead of hard link
-f: Force link creation, removing existing destination if it exists

Usage Examples:

// Create hard link
shell.ln('original.txt', 'hardlink.txt');

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

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

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

Notes:

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

mkdir - Create Directories

Creates directories with support for creating parent directories.

/**
 * Create directories
 * @param options - Command options
 * @param dirs - Directory names to create
 * @returns ShellString with operation result
 */
function mkdir(options?: string, ...dirs: string[]): ShellString;
function mkdir(dirs: string[]): ShellString;

Options:

-p: Create parent directories as needed

Usage Examples:

// Create single directory
shell.mkdir('new_directory');

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

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

// From array
shell.mkdir(['dir1', 'dir2']);

mv - Move/Rename Files

Moves or renames files and directories.

/**
 * Move or rename files and directories
 * @param options - Command options
 * @param source - Source file(s) or directory
 * @param dest - Destination path
 * @returns ShellString with operation result
 */
function mv(options?: string, source: string | string[], dest: string): ShellString;

Options:

-f: Force move, overwrite existing files
-n: No-clobber, don't overwrite existing files

Usage Examples:

// Rename file
shell.mv('oldname.txt', 'newname.txt');

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

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

// Force overwrite
shell.mv('-f', 'source.txt', 'existing_target.txt');

pwd - Print Working Directory

Returns the current working directory path.

/**
 * Get current working directory
 * @returns ShellString containing current directory path
 */
function pwd(): ShellString;

Usage Examples:

// Get current directory
const currentDir = shell.pwd();
console.log('Current directory:', currentDir.toString());

// Use in path operations
const fullPath = shell.pwd() + '/relative/path';

rm - Remove Files

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

/**
 * Remove files and directories
 * @param options - Command options
 * @param files - Files or directories to remove
 * @returns ShellString with operation result
 */
function rm(options?: string, ...files: string[]): ShellString;
function rm(files: string[]): ShellString;

Options:

-f: Force removal, ignore nonexistent files
-r, -R: Recursive removal for directories

Usage Examples:

// Remove single file
shell.rm('file.txt');

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

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

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

// From array
shell.rm(['file1.txt', 'file2.txt']);

tempdir - Get Temporary Directory

Returns the system temporary directory path.

/**
 * Get system temporary directory path
 * @returns ShellString containing temporary directory path
 */
function tempdir(): ShellString;

Usage Examples:

// Get temp directory
const tmpDir = shell.tempdir();

// Create temporary file path
const tmpFile = shell.tempdir() + '/mytemp.txt';

test - Test File Attributes

Tests file existence and attributes using Unix test expressions.

/**
 * Test file attributes and existence
 * @param expression - Test expression (e.g., '-e', '-f', '-d')
 * @returns Boolean result of the test
 */
function test(expression: string): boolean;

Test Expressions:

-e: File exists
-f: File exists and is a regular file
-d: File exists and is a directory
-L: File exists and is a symbolic link
-r: File exists and is readable
-w: File exists and is writable
-x: File exists and is executable
-S: File exists and is a socket
-p: File exists and is a pipe
-c: File exists and is a character device
-b: File exists and is a block device

Usage Examples:

// Check if file exists
if (shell.test('-e', 'file.txt')) {
  console.log('File exists');
}

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

// Check if executable
if (shell.test('-x', 'script.sh')) {
  shell.exec('./script.sh');
}

touch - Create/Update Files

Creates empty files or updates timestamps of existing files.

/**
 * Create files or update timestamps
 * @param options - Command options
 * @param files - Files to create or update
 * @returns ShellString with operation result
 */
function touch(options?: string, ...files: string[]): ShellString;
function touch(files: string[]): ShellString;

Options:

-a: Change only access time
-c: Don't create files that don't exist
-m: Change only modification time
-d <date>: Use specified date instead of current time
-r <file>: Use timestamp from reference file

Usage Examples:

// Create empty file
shell.touch('newfile.txt');

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

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

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

// From array
shell.touch(['file1.txt', 'file2.txt']);

which - Locate Command

Locates executable programs in the system PATH.

/**
 * Locate executable programs in PATH
 * @param command - Command name to locate
 * @returns ShellString containing path to executable, or null if not found
 */
function which(command: string): ShellString | null;

Usage Examples:

// Check if command exists
const gitPath = shell.which('git');
if (gitPath) {
  console.log('Git is installed at:', gitPath.toString());
} else {
  console.log('Git is not installed');
}

// Use in conditional logic
if (!shell.which('node')) {
  shell.echo('Node.js is required but not installed');
  shell.exit(1);
}

Install with Tessl CLI