Cash - Cross-platform Linux commands in ES6

Prerequisites

Node.js (version 6.0.0 or higher)
npm (version 3.0.0 or higher)
Operating System: Windows, macOS, or Linux

Installation

Installing Cash globally

npm install cash -g

Using Cash interactively

cash

Installing individual commands globally

npm install cash-ls -g
npm install cash-grep -g

Making all commands global on your system

npm install cash-global -g

Configuration

.cashrc configuration file

Create a .cashrc file in your home directory to configure Cash:

# Example .cashrc content
export PATH=$PATH:/custom/bin
alias ll='ls -la'

For Windows users, use _cashrc instead of .cashrc.

Environment variables

Cash respects standard Unix environment variables:

PATH - System path
HOME - Home directory
PWD - Current working directory

Build & Run

Running Cash locally

# Clone the repository
git clone https://github.com/dthree/cash.git
cd cash

# Install dependencies
npm install

# Run Cash interactively
npm start

Running individual commands

# Execute a specific command
node src/commands/ls.js

# Test a command
npm test -- --grep "ls command"

Programmatic usage

// Require Cash as a module
const $ = require('cash');

// Execute commands
const out = $.ls('.', {l: true});
console.log(out);

// Tagged template literal
require('cash') `
  cp -R ./src ./dest
  ls | grep *-spec.js | cat
  rm ./specResults.html 
`;

Deployment

For development

Cash is primarily a command-line tool and doesn't require traditional deployment. For development:

Clone the repository
Install dependencies with npm install
Run tests with npm test
Use npm link to test local changes globally

For production use

Since Cash is installed globally via npm, deployment is straightforward:

# Install on production server
npm install cash -g

Suggested platforms

Linux servers: Direct npm installation
Windows servers: npm installation with Windows compatibility
Docker: Create a Dockerfile with Node.js and install Cash globally

Troubleshooting

Common issues and solutions

Command not found after installation

Issue: cash: command not found

Solution: Ensure npm's global bin directory is in your PATH. Add this to your shell profile:

# For npm 5.x and earlier
export PATH=$PATH:$(npm config get prefix)/bin

# For npm 6.x and later
export PATH=$PATH:$(npm config get prefix)/lib/node_modules/cash/bin

Permission denied on macOS/Linux

Issue: Permission errors when installing globally

Solution: Use sudo or change npm's global installation directory:

# Option 1: Use sudo
sudo npm install cash -g

# Option 2: Change global directory
npm config set prefix ~/.npm-global
export PATH=$PATH:~/.npm-global/bin

Commands not working as expected

Issue: Commands behave differently than expected

Solution: Check the .cashrc configuration and ensure no conflicting aliases or environment variables are set.

Unicode/character encoding issues

Issue: Special characters display incorrectly

Solution: Ensure your terminal is set to UTF-8 encoding:

export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8

Performance issues with large directories

Issue: ls or other commands are slow on large directories

Solution: Use the --color=never option to disable color output, or limit recursion depth:

ls -R --max-depth=2

Interactive mode not working

Issue: Interactive mode doesn't start properly

Solution: Ensure you're running the latest version and that Node.js is properly installed:

npm update -g cash
node --version

Getting help

Documentation: https://github.com/dthree/cash/wiki
Issues: https://github.com/dthree/cash/issues
Gitter chat: https://gitter.im/dthree/cash
Test coverage: Check the coverage reports after running tests with npm test

How to Deploy & Use dthree/cash