Support

• NodeJS v22.5.0 and above
• Linux

Prerequisites

The package has node-pty as a dependency. That is nodejs module written in C++. When installed via npm it is actually compiled. So, we need all required tools for that.

• gcc
• g++
• make
• python

Python is used by node-gyp tool. Make sure to those those dependencies on your system. You can just use your system package manager to install those.

FNM

Best way to manage your nodejs version is to use FNM:

• https://github.com/Schniz/fnm

curl -fsSL https://fnm.vercel.app/install | bash

fnm install 22
fnm use 22
fnm default 22
fnm list

node --version

Deno/Bun Status

• Currently unsupported
• As we can't use node-pty there

Run Process

• once
• multiple times
• infinitely
• on fs changes
• with specified pause between runs
• with specified env file
• with output logging

Overview

Run a Process with specified ENV vars loaded. By default, it tries to load .env file from the current directory. Another env file can be specified with -e option. If another file specified - it must exist.

You can run command multiple times by specifying -r option. For example, -r 4. You can repeat running command infitely by specifying -r 0. Pauses between command runs can be specified via -p seconds. Like: run -r 4 -p 1 ls

Another way to run commands, is filesystem events based. You can specify monitored path, file extensions and event types.

When running by fs events, you can use %path variable among command args. It would be replaced with actual path. Like: run --monpath . --monevents change echo %path

Caution

Command that you run might have options contradicting with run command itself. In this case, you -- separator between options for run and the command.

Logs Location

• $HOME/.local/state/ngm/logs
• You can use --logs option to print actual logs directory

Example:

run -r 2 -- lsd -l

View Logs

The package includes logview utility to view logs

Example:

logview

Install

npm install -g @aibulat/run
run --version

Help

Usage: run [options] [exe] [args...]

Run programs with environment variables preloaded from file

Arguments:
  exe                    executable to run
  args                   arguments for the executable

Options:
  -V, --version          output the version number
  -l, --logs             show log dir and exit
  -d, --debug            output extra debugging
  -e, --env-file <path>  path to .env file
  -c, --clean            before loading .env file, clean all environment variables except PATH, HOME, SHELL
  -r, --runs <count>     run the command multiple times
  -p, --pause <seconds>  pause between runs
  --monpath <path>       monitor path, run on fs change. --runs and --pause are ignored
  --monext <ext>         file extensions to monitor
  --monevents <events>   event list: create,change,delete,all
  -h, --help             display help for command

Run command repeatedly/infitely, with a 1 second pause between runs

run -r 0 -p 1 ls -la

Run command 5 times, with a 2 seconds pause between runs

run -r 5 -p 2 ls -la

File Monitoring

run --monpath . --monext ts,js,css --monevents create lsd -l
run --monpath . --monext ts,js,css --monevents all lsd -l
run --monpath ./src ls -l

Use as CLI with npx

1. npx @aibulat/run --version
2. npx @aibulat/run --help
3. npx @aibulat/run <cmd>
4. npx @aibulat/run -e some-env-file <cmd>

CLI samples:

run env
run ls -la
run cat package.json
run bash
run node somescript.js
run -e file.env mysql -uroot -p

Use API

import { run } from "@aibulat/run";

const program = "ls";
const args = ["-l", "-a"];
const cmd = run(program, args);

Function Signature

run(cmd: string, args: string[], clean: boolean, envfile: string)

• cmd: program to run
• args: program arguments
• clean: flag to cleanup all ENV, except PATH, HOME, SHELL - before loading envfile
• envfile: env file to load. If not specified, we try to load .env in current directory