README.md

🐚 cross-platform library to execute commands in new shells

Sometimes a certain development environment requires more than a single terminal window, so you open a new one, or even better, split into multiple panes. This happens because nowadays, we have many interactive CLI apps that take the whole terminal window. In those cases, we'll see an explanation in the README that instructs us which commands should we run.

The main problem with this approach is that the developer is now required to understand multiple commands. Another problem is that we can't make sure that the developer will get the desired developer experience if it requires manual actions. For example, run a command, split panes in the terminal and then run another command.

newsh is here to solve these problems, it lets you configure how many terminal windows, tabs or splits you need and what commands to run in each one. It does its best effort to use features that your own terminal provides, like splitting panes. But worry not, in case a feature is not available, a regular terminal window is guaranteed to be opened.

Features

• 🌏 Cross-platform
• 🗃 Opens the new shell in current working directory
• 🎛 Supports splitting (iterm2/tmux/ConEmu/Cmder)
• 📄 Runs js files with node
• 🌴 Pass environment parameters to the new shell instance

Installation

You can choose to install using yarn or npm

yarn add --dev newsh

npm install -D newsh

In case you want the newsh command to be available globally:

yarn global add newsh

npm install newsh --global

CLI

Run a command in a new shell

prints "hello world" in a new shell window

newsh "echo 'hello world'"

The new shell will run in the same working directory.

# See for yourself 👀

newsh pwd

You can run multiple shells

newsh "tsc --watch" "jest --watch"

Note that you can use tsc, jest and any other local bin just like in npm/yarn scripts

--split-horizontally

Attempts to split the screen horizontally instead of opening a new tab/window

newsh --split-horizontally "say down"

--split-vertically

Attempts to split the screen vertically instead of opening a new tab/window

newsh --split-vertically "say right"

--split

Alias for --split-vertically

--terminalApp

Choose a specific terminal app to use (e.g. iTerm.app)

--cd

Open the new shell in the specified directory

newsh pwd --cd "~"

--file

Executes a file in a new shell

newsh --file "./script.sh"

Supports running node for javascript files

newsh --file "./script.js"

Node API

possible options for the command and file methods

type Options = {
  env?: Record<string, string> = {}; // Environment parameters that would be passed to the new shell
  cwd?: string = process.cwd(); // Where the newsh command should run (use for joining relative paths of files))
  cd?: string = process.cwd(); // A path to a directory that the new shell will use
  split?: boolean = false; // Attempts to split the terminal window
  splitDirection?: "vertically" | "horizontally" = "vertically"; // The direction of splitting (only works when `split: true`)
  terminalApp?: string | undefined = $TERM_PROGRAM; // Use a specific terminal app
};

command

Run a command in a new shell

command(script: string, options: Options): void

file

Executes a file in a new shell

file(scriptPath: string, options: Options): void

Development

# install
yarn
# compile
yarn watch
# test
yarn test

Contributing

If you find a bug or want this project to provide better support for a certain terminal application, please open an issue. You are more than welcome to create pull requests as well.

Future

• Controll the focus of the terminal window
• Better split integration with other terminals