Skip to Content
gnux

Getting started

This guide takes you from nothing to a working gnux installation: installing the binary with go install, make, install.sh or Docker, turning each of the 108 tools into a command of its own by linking its name to the binary, and running your first commands in both invocation forms. It also covers the GNU-name aliases that let scripts written for the GNU tools run unchanged, the --help, --version and --list options every installation has, and how to check that everything is wired up correctly.

What you are installing

gnux is one statically linked executable called gnux. It contains every tool: basenamex, catx, cpx, dirnamex, echox, envx, falsex, headx, lnx, lsx, mkdirx, mvx, pwdx, realpathx, rmx, rmdirx, sleepx, tailx, touchx, truex, wcx and yesx. Each is named after its GNU counterpart with an x appended, and mirrors its flags, diagnostics and exit statuses.

The binary decides which tool to be by looking at the name it was started under. That is why installation has two parts:

  1. Put gnux on your PATH.
  2. Optionally, create one link (or copy) per tool name pointing at it, so that rmx, cpx and the rest are commands of their own.

Without step 2 everything still works, through the subcommand form: gnux rmx -rf build.

Requirements

To...You need
Run gnuxNothing but the binary: Linux or macOS (amd64, arm64) or Windows (amd64). No cgo, no runtime dependencies
Use the per-tool commandsA filesystem with symbolic links (or copies of the binary) and the install directory on PATH
Install with go install or build from sourceGo 1.26 or newer, and git
Use the optional helpersmake for the Makefile, bash for install.sh, Docker for the image

Install with go install

The quickest route, on any platform with Go:

go install github.com/braswelljr/gnux@latest

The binary lands in $(go env GOBIN), or $(go env GOPATH)/bin when GOBIN is unset. Make sure that directory is on your PATH:

export PATH="$(go env GOPATH)/bin:$PATH"   # add to ~/.bashrc or ~/.zshrc
gnux --version
$env:Path = "$(go env GOPATH)\bin;$env:Path"   # add to your $PROFILE
gnux --version

To pin a version, name a tag instead of latest: go install github.com/braswelljr/gnux@v0.0.2. gnux --version then reports that tag.

Install with a package manager

From v0.0.2 on, every release is published to the package managers below. Each installs the gnux binary (and, except on Windows, shell completion); link the tool names afterwards, as the next section shows.

PlatformPackage managerInstallA particular version
macOS, LinuxHomebrewbrew tap braswelljr/gnux https://github.com/braswelljr/gnux, then brew install --cask braswelljr/gnux/gnuxThe newest only
Windowswingetwinget install braswelljr.gnuxwinget install braswelljr.gnux --version 0.0.2
WindowsScoopscoop bucket add gnux https://github.com/braswelljr/gnux, then scoop install gnux/gnuxscoop install gnux/gnux@0.0.2
LinuxSnapsudo snap install gnux--channel=edge for the newest prerelease
Arch LinuxAURyay -S gnux-binThe newest only
Any, in a Node projectnpmnpm install --save-dev gnux (every tool is then on the PATH of package scripts; see Node and npm)npm install --save-dev gnux@1.3.0
Debian, Ubuntu.deb from the releasesudo dpkg -i gnux-v0.0.2-linux-amd64.debDownload that version's file
Fedora, RHEL, openSUSE.rpm from the releasesudo rpm -i gnux-v0.0.2-linux-amd64.rpmDownload that version's file
Alpine.apk from the releasesudo apk add --allow-untrusted gnux-v0.0.2-linux-amd64.apkDownload that version's file

The packages are on the releases page, for amd64, arm64 and riscv64, beside the plain archives (gnux-<version>-<os>-<arch>.tar.gz, .zip for Windows) and a checksums.txt that covers them all:

v=v0.0.2
curl -LO "https://github.com/braswelljr/gnux/releases/download/$v/gnux-$v-linux-amd64.deb"
curl -LO "https://github.com/braswelljr/gnux/releases/download/$v/checksums.txt"
sha256sum --check --ignore-missing checksums.txt
sudo dpkg -i "gnux-$v-linux-amd64.deb"

Three things to know:

  • The snap is strictly confined. The tools see your home directory and, after sudo snap connect gnux:removable-media, removable media; they do not see the rest of the system. The snap provides the gnux command only, so run tools as gnux rmx .... For anything system-wide, use another install.
  • winget lags a release by the time its review takes, from hours to a few days.
  • Whichever way gnux arrived, gnux --version says which version it is, and every tool answers the same way (rmx --version).

gnux looks at the name it was started under, so a link called rmx that points to gnux behaves as rmx. gnux --list prints every tool name, one per line, which makes the loop short:

bin="$(dirname "$(command -v gnux)")"
for t in $(gnux --list); do ln -sf gnux "$bin/$t"; done
# Symbolic links need Developer Mode or an elevated prompt on Windows.
# Copies work everywhere and dispatch exactly the same way.
$bin = Split-Path (Get-Command gnux).Source
foreach ($t in gnux --list) { Copy-Item "$bin\gnux.exe" "$bin\$t.exe" -Force }

Check the result:

rmx --version
lsx --version
rmx (gnux) dev
lsx (gnux) dev

The Windows guide covers links versus copies in detail.

Install with install.sh

install.sh in the repository root does both parts at once: it installs the binary with go install and links every tool name next to it.

./install.sh                    # latest version, plus the per-tool links
VERSION=v0.1.0 ./install.sh     # a specific tag
./install.sh --from-source      # build the current checkout, with the version stamped in
./install.sh --no-links         # the gnux binary only

A typical run prints:

Installing github.com/braswelljr/gnux@latest...
Installed gnux to /home/you/go/bin/gnux
Linked 108 tools (rmx, cpx, lsx, ...) in /home/you/go/bin
Ensure /home/you/go/bin is on your PATH, then run: gnux --help

It stops with error: the Go toolchain is required if Go is missing, and with error: unknown option (exit status 2) for any argument other than --from-source or --no-links.

Build from source with make

git clone https://github.com/braswelljr/gnux.git
cd gnux

make build            # ./bin/gnux, with the version from git describe
make links            # build, then link every tool name inside ./bin
./bin/lsx -la         # try a tool straight from the build directory

make install          # go install, with the version stamped in
make install/links    # install, then link every tool name next to the installed binary

make build/all cross-compiles for Linux, macOS and Windows on amd64 and arm64 into ./bin. To build by hand with the version injected:

go build -ldflags "-X github.com/braswelljr/gnux/internal/common.Version=$(git describe --tags --always)" -o bin/gnux .

Run in Docker

Every release publishes two images to the GitHub Container Registry, for linux/amd64 and linux/arm64:

ImageWhat is in it
ghcr.io/braswelljr/gnux:v1 (also :latest and the exact version)Alpine, with gnux and every tool name in /usr/local/bin
ghcr.io/braswelljr/gnux:v1-scratch (also :scratch)Nothing but gnux, its x-names, the GNU names and [ in /bin, and an empty /tmp: a base image for a container that needs file tools and no distribution

Both run as an unprivileged user (uid 10001) in /work, with gnux as the entry point.

docker run --rm ghcr.io/braswelljr/gnux:v1 --list
docker run --rm -v "$(pwd):/work" ghcr.io/braswelljr/gnux:v1-scratch lsx -la

In a Dockerfile of your own, the scratch image is a stage to copy the tools from:

FROM ghcr.io/braswelljr/gnux:v1-scratch AS gnux
FROM gcr.io/distroless/static
COPY --from=gnux /bin/ /usr/local/bin/

The repository's Dockerfile builds the same images: a golang:1.26-alpine stage compiles a static binary and links every tool name, then the default alpine:3.20 stage carries /usr/local/bin/gnux and its links, and --target scratch carries them alone.

docker build -t gnux .
docker build -t gnux:scratch --target scratch .
docker build -t gnux --build-arg VERSION=v0.1.0 .     # stamp a version

docker run --rm gnux --list
docker run --rm -v "$(pwd):/work" gnux lsx -la
docker run --rm -v "$(pwd):/work" gnux shell -c 'wcx -l *.go'
docker run --rm -v "$(pwd):/work" --entrypoint rmx gnux -rv build/
docker run --rm -v "${PWD}:/work" gnux lsx -la

Or through Compose, which builds the image and mounts the current directory at /work:

docker compose run --rm gnux --version
docker compose run --rm gnux lsx -la
docker compose run --rm gnux rmx -rv build/

These are real file tools working on the mounted directory: rmx in a container deletes your files just as it would on the host. More container patterns are in CI and containers.

Your first commands

Run a tool under its own name, exactly as you would its GNU counterpart:

mkdirx -pv demo/src demo/docs
echox 'hello, gnux' > demo/README.md
lsx -R demo
catx -n demo/README.md
wcx -c demo/README.md
mkdirx: created directory 'demo'
mkdirx: created directory 'demo/src'
mkdirx: created directory 'demo/docs'
demo:
README.md
docs
src

demo/docs:

demo/src:
     1	hello, gnux
12 demo/README.md

Clean up the same way:

rmx -rv demo

The two invocation forms

Every tool can be run two ways, with identical results:

rmx -rf build/          # as a command of its own (needs the link)
gnux rmx -rf build/     # as a subcommand of the one binary (always works)

The subcommand form is handy when the links are not installed, on a machine where you only copied gnux, or in a container whose entry point is gnux.

GNU-name aliases

Both forms also answer to the GNU name of each tool:

gnux rm -rf build/      # same as gnux rmx -rf build/
gnux ls -la             # same as gnux lsx -la

And a link named after the GNU tool selects it too, so scripts that call the GNU names work where GNU coreutils is not installed, such as a minimal container or a Windows machine:

ln -s "$(command -v gnux)" /usr/local/bin/rm
rm --version
rmx (gnux) dev

The program name is matched without its directory, without a .exe suffix and ignoring case, so RMX.EXE on Windows selects rmx.

Think before shadowing the system's own rm or ls: other programs and scripts on the machine may depend on GNU or BSD extensions gnux does not implement. The x names exist precisely so the two can live side by side.

Help, version and the tool list

Every tool, and gnux itself, accepts --help and --version:

gnux --help            # what gnux is, and every tool with its GNU name and summary
rmx --help             # usage, description, options, first examples, exit status
gnux rmx --help        # the same, through the subcommand form
rmx --version          # rmx (gnux) VERSION

--help has no short form, so -h stays free for the tools that use it (lsx -h is human-readable sizes, touchx -h acts on a symbolic link itself).

--help stays one screen, as GNU's does. For the full manual, the same content as the online reference, use gnux help:

gnux help rmx          # NAME, SYNOPSIS, DESCRIPTION, OPTIONS, PERMISSIONS, USE CASES,
                       # every EXAMPLE (bash and PowerShell), EXIT STATUS, SEE ALSO
gnux help rm           # the GNU name works too
gnux help rmx force    # one option in depth: --force, force, -f and f all work
gnux help lsx -l       # any option of any tool, with every example that uses it
gnux help shell        # the manual for gnux shell
$ gnux help cpx -v
OPTION
    -v, --verbose  (cpx)
        explain what is being done

EXAMPLES
  # Copy several files into a directory, reporting each one
  $ cpx -v a.txt b.txt backup/
  PS> cpx -v a.txt b.txt backup
...

Inside gnux shell and the playground, help rmx and gnux help rmx print the same manual. Help is colored on a terminal and plain when piped, or when NO_COLOR is set.

gnux --list prints the tool names, one per line, ready for a loop:

gnux --list | wcx -l
29

Options follow GNU conventions

rmx -rvf build/                 # short flags combine
lsx --sort=size                 # long flags take --name=value
lsx --sort size                 # ... or a separate argument
rmx -- -weird-file-name         # -- ends option parsing
cpx -t backup/ a.txt b.txt      # options may follow operands (except for envx)

An option gnux does not implement is refused, never silently ignored:

rmx --no-such-flag x
rmx: unrecognized option '--no-such-flag'
Try 'rmx --help' for more information.

Exit statuses at a glance

StatusMeaning
0Success
1Something failed (diagnostic on standard error), or a command-line mistake
2lsx: serious trouble, such as an operand that cannot be accessed
125, 126, 127envx: it failed itself, the command could not be run, the command was not found
2, 127gnux shell: a syntax error, an unknown command

Troubleshooting explains each one with examples.

Check your installation

command -v gnux rmx lsx         # all three should resolve
gnux --version
gnux --list | wcx -l            # 29
gnux shell -c 'echox shell works && pwdx'

If rmx is not found, the links were not created or their directory is not on PATH: rerun the linking loop. If gnux --version prints dev, the binary was built without the version flag, which is harmless.

Next steps

On this page