Skip to Content
gnux

Node and npm

gnux on npm: one development dependency that puts rmx, cpx, mkdirx, lsx and every other tool on the PATH of your package scripts, with GNU's flags and messages on Linux, macOS and Windows alike. It replaces rimraf, mkdirp, cpy-cli, del-cli, shx and cross-env with the commands you already know, and runs the native binary, not JavaScript.

Install

npm install --save-dev gnux
pnpm add -D gnux
yarn add -D gnux
bun add -d gnux

The gnux package is a few kilobytes of JavaScript. The binary comes in a package of its own for each platform, listed as optional dependencies and limited to their operating system and CPU, so the package manager downloads only the one your machine needs and runs no install script:

PlatformPackage
Linux on x64, arm64, riscv64gnux-linux-x64, gnux-linux-arm64, gnux-linux-riscv64
macOS on Intel and Apple silicongnux-darwin-x64, gnux-darwin-arm64
Windows on x64 and arm64gnux-win32-x64, gnux-win32-arm64
FreeBSD on x64 and arm64gnux-freebsd-x64, gnux-freebsd-arm64

Every package of a release has the same version, the release's own, so gnux@1.3.0 always runs gnux 1.3.0.

In package scripts

Each tool is installed under its gnux name, the GNU name with an x added, and never under the GNU name: rm in a script is still the system's rm, and rmx is gnux's, the same on every operating system.

{
  "scripts": {
    "clean": "rmx -rf dist coverage .cache",
    "prebuild": "mkdirx -p dist/assets",
    "build": "tsc && cpx -r public/. dist/",
    "postbuild": "lsx -l dist",
    "size": "dux -sh dist",
    "dev": "envx NODE_ENV=development node server.js"
  }
}
Instead ofWrite
rimraf distrmx -rf dist
del-cli "dist/**"rmx -rf dist
mkdirp dist/a/bmkdirx -p dist/a/b
make-dir dist/a/bmkdirx -p dist/a/b
cpy-cli src/index.html distcpx src/index.html dist
copyfiles -u 1 "src/**/*.css" distgnux shell -c 'cd src && cpx --parents */*.css ../dist'
shx cp -r a bcpx -r a b
shx mv a bmvx a b
shx cat a b > ccatx a b > c
cross-env NODE_ENV=production node build.jsenvx NODE_ENV=production node build.js
touch-cli .envtouchx .env

gnux --list prints every tool, and gnux help rmx shows one's manual.

Globs and other shell features

npm runs a script through sh on Linux and macOS but through cmd.exe on Windows, and cmd.exe does not expand *: cpx src/*.css dist copies a file literally named src/*.css there, or fails. When a script needs a glob, && chains that differ between shells, a loop or a redirection that must mean the same everywhere, run it with gnux shell, which expands globs itself:

{
  "scripts": {
    "copy:css": "gnux shell -c 'cpx src/*.css dist/'",
    "clean:logs": "gnux shell -c 'for f in logs/*.log; do rmx -f \"$f\"; done'",
    "release": "gnux shell -e scripts/release.gnux"
  }
}

The portable scripting guide covers the language.

From JavaScript

const gnux = require('gnux');

// Run a tool with the parent's output streams; returns its exit status.
const status = gnux.run('rmx', ['-rf', 'dist']);

// Capture the output instead (any child_process.spawnSync option works).
const listing = gnux.run('lsx', ['-1', 'src'], { stdio: 'pipe' });

// The binary itself, to run with your own spawn, execa or zx.
const binary = gnux.binaryPath();

run with null as the tool runs gnux itself (gnux.run(null, ['--version'])). Type definitions ship with the package.

When the binary is missing

  • Optional dependencies left out. npm install --omit=optional (or --no-optional, or a .npmrc with optional=false) skips the platform package, and each tool then says gnux: the package gnux-linux-x64 is not installed and exits 127. Install with optional dependencies, or add the platform package yourself.
  • A platform without a package. gnux names the platform and suggests building it with go install github.com/braswelljr/gnux@latest.
  • A gnux of your own. Set GNUX_BINARY to its path, and every launcher runs that binary instead: a build from source, the Homebrew one, or the one a CI image already has.

In CI

The binary comes from the npm registry with the rest of node_modules, so a cached install has it too, and nothing else needs installing on the runner. A matrix over operating systems runs the same scripts unchanged:

jobs:
  build:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run clean && npm run build

Outside a Node project, the setup-gnux action installs the binary directly.

Each package's provenance

Every package is published from the release workflow with npm's provenance statement, which ties it to the commit and the workflow run that built it. npm audit signatures checks it.

Go library

How to embed gnux in a Go program: every tool's engine is an importable package under core/ that removes, copies, lists, counts or tails files with GNU semantics in your own process, without spawning anything. This guide covers building an engine from its Options (whose zero value keeps every safeguard on), wiring it to core.Streams to capture output in a bytes.Buffer or silence it, injecting prompts, removals, clocks and the environment, telling the three kinds of error apart with errors.Is and errors.As, running any tool by name with cmd.RunTool, running whole portable scripts with cmd.NewShell, and embedding the entire command line with cmd.Main. It ends with seventeen complete programs, each of which was compiled and run against the module.

Portable scripting

How to write scripts with gnux shell, the small interpreter whose commands are the gnux tools run inside the gnux process: the language subset it understands (variables, script arguments, quoting, globbing, command substitution, redirection, pipelines, the &&, || and ; connectors, and if, for, while and case), running scripts with -e, -u, -c, files and standard input, exit statuses, cd, the deliberate differences from POSIX sh, and reaching external programs through envx. It ends with complete, tested scripts (a project scaffold, a build-output cleanup, log rotation, release staging and a source tree check) that run unchanged on Linux, macOS and Windows, because nothing in them depends on the machine's own shell or utilities.

On this page