tessl/npm-shelljs
Portable Unix shell commands for Node.js that provide cross-platform compatibility across Windows, Linux, and macOS.
—
Pending
text-processing.mddocs/
Text Processing Commands
Text manipulation and filtering commands for processing file contents, searching patterns, and transforming text data with Unix-style functionality.
Capabilities
echo - Display Text
Displays text to stdout with support for backslash escapes and newline control.
/**
* Display text to stdout
* @param options - Command options
* @param text - Text strings to display
* @returns ShellString containing the output text
*/
function echo(options?: string, ...text: string[]): ShellString;Options:
-e: Interpret backslash escapes (default behavior)-n: Remove trailing newline from output
Usage Examples:
// Simple text output
shell.echo('Hello world');
// Multiple arguments
shell.echo('Hello', 'world', '2023');
// No trailing newline
shell.echo('-n', 'No newline at end');
// Backslash escapes
shell.echo('Line 1\\nLine 2\\tTabbed');
// Capture output
const message = shell.echo('Status: OK');grep - Search Text
Searches for patterns in files using regular expressions, similar to Unix grep.
/**
* Search for patterns in files using regular expressions
* @param options - Command options
* @param regex - Regular expression or string pattern to search for
* @param files - Files to search in
* @returns ShellString containing matching lines or filenames
*/
function grep(options: string, regex: RegExp | string, ...files: string[]): ShellString;
function grep(regex: RegExp | string, ...files: string[]): ShellString;
function grep(options: string, regex: RegExp | string, files: string[]): ShellString;
function grep(regex: RegExp | string, files: string[]): ShellString;Options:
-v: Invert match (show non-matching lines)-l: Show only filenames with matches-i: Case-insensitive matching-n: Print line numbers with matches-B <num>: Show<num>lines before each result-A <num>: Show<num>lines after each result-C <num>: Show<num>lines before and after each result
Usage Examples:
// Search for pattern in file
const matches = shell.grep('error', 'logfile.txt');
// Case-insensitive search
const caseInsensitive = shell.grep('-i', 'ERROR', 'logfile.txt');
// Invert match (show lines without pattern)
const nonMatches = shell.grep('-v', 'debug', 'logfile.txt');
// Show only filenames with matches
const filesWithMatches = shell.grep('-l', 'TODO', '*.js');
// Show line numbers
const withLineNumbers = shell.grep('-n', 'function', 'script.js');
// Show context lines (3 before and after)
const withContext = shell.grep('-C', 3, 'error', 'log.txt');
// Show lines before match
const beforeContext = shell.grep('-B', 2, 'function', 'script.js');
// Show lines after match
const afterContext = shell.grep('-A', 5, 'TODO', 'notes.txt');
// Regular expression search
const regexMatches = shell.grep(/\\d{3}-\\d{3}-\\d{4}/, 'contacts.txt');
// Search multiple files
const multiFile = shell.grep('function', 'file1.js', 'file2.js');
// Chain with other commands
const jsErrors = shell.find('.').grep('\\.js$').grep('error');head - Display First Lines
Displays the first lines of files, useful for previewing file contents.
/**
* Display first lines of files
* @param options - Options object with line count
* @param files - Files to display
* @returns ShellString containing first lines of files
*/
function head(options?: { '-n': number }, ...files: string[]): ShellString;
function head(...files: string[]): ShellString;
function head(options: { '-n': number }, files: string[]): ShellString;
function head(files: string[]): ShellString;Options:
{'-n': number}: Number of lines to display (default: 10)
Usage Examples:
// Show first 10 lines (default)
const preview = shell.head('largefile.txt');
// Show first 5 lines
const first5 = shell.head({'-n': 5}, 'file.txt');
// Multiple files
const multiHead = shell.head({'-n': 3}, 'file1.txt', 'file2.txt');
// From array
const fromArray = shell.head({'-n': 20}, ['log1.txt', 'log2.txt']);sed - Stream Editor
Stream editor for filtering and transforming text using regular expressions and substitutions.
/**
* Stream editor for filtering and transforming text
* @param options - Command options
* @param searchRegex - Pattern to search for (RegExp or string)
* @param replacement - Replacement text
* @param files - Files to process
* @returns ShellString containing processed text
*/
function sed(options: string, searchRegex: RegExp | string, replacement: string, ...files: string[]): ShellString;
function sed(searchRegex: RegExp | string, replacement: string, ...files: string[]): ShellString;
function sed(options: string, searchRegex: RegExp | string, replacement: string, files: string[]): ShellString;
function sed(searchRegex: RegExp | string, replacement: string, files: string[]): ShellString;Options:
-i: Edit files in-place (modifies original files)
Usage Examples:
// Simple text substitution
const replaced = shell.sed('old_text', 'new_text', 'file.txt');
// Regular expression substitution
const regexReplace = shell.sed(/version_\\d+/, 'version_2', 'config.js');
// Global replacement (replace all occurrences)
const globalReplace = shell.sed(/old/g, 'new', 'file.txt');
// In-place editing
shell.sed('-i', 'BUILD_VERSION', 'v1.2.3', 'version.js');
// Remove lines (replace with empty string)
const removeLines = shell.sed(/^.*DEBUG.*$/gm, '', 'app.js');
// Multiple files
shell.sed('-i', /copyright 2022/g, 'copyright 2023', 'file1.js', 'file2.js');
// Chain with other commands
shell.cat('template.txt').sed('{{NAME}}', 'John').to('output.txt');sort - Sort Lines
Sorts lines in text files with various sorting options.
/**
* Sort lines in text files
* @param options - Command options
* @param files - Files to sort
* @returns ShellString containing sorted lines
*/
function sort(options?: string, ...files: string[]): ShellString;
function sort(...files: string[]): ShellString;
function sort(options: string, files: string[]): ShellString;
function sort(files: string[]): ShellString;Options:
-r: Reverse sort order-n: Numeric sort (compare as numbers, not strings)
Usage Examples:
// Basic alphabetical sort
const sorted = shell.sort('names.txt');
// Reverse sort
const reversed = shell.sort('-r', 'data.txt');
// Numeric sort
const numericSort = shell.sort('-n', 'numbers.txt');
// Sort multiple files
const multiSort = shell.sort('file1.txt', 'file2.txt');
// Chain with other commands
const sortedList = shell.ls().sort();
// Numeric reverse sort
const numReverse = shell.sort('-rn', 'scores.txt');tail - Display Last Lines
Displays the last lines of files, useful for monitoring log files and recent changes.
/**
* Display last lines of files
* @param options - Options object with line count
* @param files - Files to display
* @returns ShellString containing last lines of files
*/
function tail(options?: { '-n': number }, ...files: string[]): ShellString;
function tail(...files: string[]): ShellString;
function tail(options: { '-n': number }, files: string[]): ShellString;
function tail(files: string[]): ShellString;Options:
{'-n': number}: Number of lines to display (default: 10)
Usage Examples:
// Show last 10 lines (default)
const lastLines = shell.tail('logfile.txt');
// Show last 5 lines
const last5 = shell.tail({'-n': 5}, 'file.txt');
// Multiple files
const multiTail = shell.tail({'-n': 3}, 'log1.txt', 'log2.txt');
// Monitor recent log entries
const recentErrors = shell.tail({'-n': 50}, 'error.log');
// From array
const fromArray = shell.tail({'-n': 20}, ['access.log', 'error.log']);uniq - Remove Duplicate Lines
Removes duplicate consecutive lines from sorted input, with options for counting and filtering.
/**
* Remove duplicate consecutive lines from sorted input
* @param options - Command options
* @param input - Input file (optional, reads from stdin if not provided)
* @param output - Output file (optional, writes to stdout if not provided)
* @returns ShellString containing unique lines
*/
function uniq(options?: string, input?: string, output?: string): ShellString;Options:
-i: Case-insensitive comparison-c: Prefix lines with occurrence count-d: Only output duplicate lines-u: Only output unique lines (non-duplicated)
Usage Examples:
// Remove duplicates from file
const unique = shell.uniq('sorted_data.txt');
// Case-insensitive duplicate removal
const caseUnique = shell.uniq('-i', 'names.txt');
// Count occurrences
const counted = shell.uniq('-c', 'log_entries.txt');
// Show only duplicated lines
const duplicates = shell.uniq('-d', 'data.txt');
// Show only unique lines
const onlyUnique = shell.uniq('-u', 'data.txt');
// Process and save to file
shell.uniq('-c', 'input.txt', 'output.txt');
// Chain with sort for full deduplication
const fullyUnique = shell.sort('unsorted.txt').uniq();
// Case-insensitive count
const caseCount = shell.uniq('-ic', 'mixed_case.txt');Text Processing Patterns
Common Text Processing Workflows
// Log analysis workflow
const errorCount = shell.cat('application.log')
.grep('ERROR')
.uniq('-c')
.sort('-rn');
// File content transformation
shell.cat('template.html')
.sed('{{TITLE}}', 'My Page')
.sed('{{DATE}}', new Date().toDateString())
.to('index.html');
// Data extraction and cleaning
const cleanData = shell.grep('^[A-Z]', 'raw_data.txt')
.sort()
.uniq()
.head({'-n': 100});
// Search and replace across multiple files
shell.find('.')
.grep('\\.js$')
.forEach(file => {
shell.sed('-i', 'oldAPI', 'newAPI', file);
});Piping and Chaining
Text processing commands support method chaining and can be combined with file system operations:
// Chain text operations
const result = shell.cat('data.txt')
.grep('important')
.sort()
.uniq()
.head({'-n': 10});
// Output to file
shell.echo('Processing complete')
.toEnd('process.log');
// Complex pipeline
const report = shell.find('logs/')
.grep('\\.log$') // Find log files
.map(file => shell.grep('ERROR', file)) // Search each for errors
.filter(result => result.length > 0) // Keep only files with errors
.sort();Install with Tessl CLI
npx tessl i tessl/npm-shelljs