gnux shell
Run a portable shell whose commands are the gnux tools.
Synopsis
gnux shell [OPTION]... [SCRIPT [ARG]...]Description
gnux shell is a small command interpreter whose commands are the gnux tools, run inside the gnux process. Because nothing in it depends on the system's own shell or utilities, the same script behaves identically on Linux, macOS and Windows. With no SCRIPT it reads commands from standard input, prompting when that is a terminal; with -c it runs the given string. The ARGs after SCRIPT are its arguments ($1, $2, ... and "$@"); after -c STRING, the first one is $0 and the rest are the arguments. Options are read only before SCRIPT, so everything after it reaches the script.
The language is a deliberately small subset of POSIX sh: pipelines (a | b), the &&, || and ; connectors, ! to invert a status, redirection (<, >, >>, 2> for standard error, and 2>&1 and >&2 to send one stream where the other goes; /dev/null discards on every platform), NAME=value variables with $NAME, ${NAME}, $? and $PWD expansion and the POSIX ${...} forms (${#NAME}, ${NAME:-w}, ${NAME:=w}, ${NAME:+w}, ${NAME:?msg} and the forms without the colon, ${NAME%suffix}, ${NAME%%suffix}, ${NAME#prefix}, ${NAME##prefix}; any other is a bad substitution), the arguments $1 to $9, ${10}, $#, $0, $@ and $, command substitution $(command), single and double quotes, globbing (, ?, [...]), ~ for the home directory and # comments. Control flow is if/then/elif/else/fi, for NAME in WORD...; do ...; done (over the arguments when 'in' is left out), while ...; do ...; done and case WORD in PATTERN | PATTERN) ... ;; esac, each over as many lines as it needs. The builtins are cd, exit, help, read ([-r] [NAME...]: one line, split at $IFS), set (-e, -u, +e, +u, -- ARG...), shift, break, continue and [ (the test tool, written [ EXPRESSION ]). Tools answer to both names, so rm and rmx are the same command. External programs are not looked up; run one through the env tool (envx PROGRAM ARG...).
It is not a full sh. There are no functions, no arithmetic (use exprx), no until, no here-documents, no backquotes, no ( ) or { } grouping and no background jobs. A quoted string does not span lines, a backslash does not join lines, and a line that ends in |, && or || is an error. A pipeline can hold one if, for, while or case, which runs as a subshell there.
Two things differ from sh on purpose. A variable's value is never re-split or re-globbed, so a path with spaces needs no quoting once stored; for the same reason an unquoted $(command) becomes one word per line of output, never one per space, and a quoted one a single word. And NAME=value before a command sets the variable for the rest of the script, not just for that command. A $(command) runs as a subshell: what it sets, and a cd it makes, end with it.
The exit status is that of the last command run, 2 for a syntax error, and 127 for an unknown command. With -e the script stops at the first failing command, except one whose status is tested: by &&, || or !, or as the condition of an if or a while. With -u, expanding a variable that is not set is an error that stops the script with status 1; ${NAME:-default} reads one that may be missing. An environment variable that is set but empty counts as unset.
--sandbox DIR confines the shell, before it reads or runs anything, with the operating system's own sandbox: its commands, and any program they start through envx, may then read and write each --sandbox DIR, only read each --sandbox-read DIR and the system's own directories, and reach nothing else, the home directory included. The kernel enforces it, so neither a symbolic link nor .. gets around it, and it cannot be lifted. The sandbox is Landlock on Linux (5.13 or later, in a gnux built without cgo, as releases are), Seatbelt on macOS, an AppContainer on Windows and Capsicum on FreeBSD, where a command can run gnux's own tools only (capability mode starts no other program); where none can be used the shell refuses with status 125 and runs nothing. A SCRIPT must lie in an allowed directory, as it is read after the sandbox is entered.
gnux's terminal view (BR-13): on a terminal, the prompt shows the working directory and the status of a command that failed, and help is colored. --pretty[=WHEN] and --theme=NAME choose the view (GNUX_PRETTY, GNUX_THEME), and the shell passes them on to every tool it runs; --pretty=never brings back the plain gnux> prompt.
Permissions
The shell itself needs only read access to SCRIPT. Each command it runs needs whatever its tool needs; redirection creates files with mode 0644 (before the umask).
Use cases
- Build, clean and packaging scripts that must run unchanged on Windows, macOS and Linux.
- Running a script you did not write, or one an AI agent wrote, where it can only touch one directory.
- A consistent interactive shell on machines without the GNU tools installed.
- Embedding small file-management scripts in a Go application without spawning processes.
Flags
-c, --command STRING run the commands in STRING instead of reading a script
-e, --errexit exit at the first command that fails
--help display this help and exit
-u, --nounset treat expanding an unset variable as an error
--pretty WHEN[="always"] the gnux terminal view WHEN: 'always' (the default when WHEN is omitted), 'auto' (the default: on a terminal only), or 'never'; GNUX_PRETTY sets the default
--sandbox DIR confine the shell, its commands and the programs they start to DIR, which they may read and write, and the system's own directories, which they may only read; may be repeated
--sandbox-read DIR with --sandbox, also let them read DIR; may be repeated
--theme NAME color the view with the built-in theme NAME (gnux theme picks and saves one); GNUX_THEME sets the default
--version output version information and exitExamples
Start an interactive session
gnux shellRun a one-liner
gnux shell -c 'mkdirx -p dist && cpx -r assets dist/ && lsx -l dist'Run a script file, stopping at the first failure
gnux shell -e build.gnuxRun a script with arguments, refusing unset variables
gnux shell -eu release.gnux v1.2.3 distLoop over files and branch on each
gnux shell -c 'for f in *.txt; do if grepx -q TODO "$f"; then echox "$f"; fi; done'Use a command's output
gnux shell -c 'mkdirx -p "build/$(unamex -s)"'Run a downloaded build script so that it can change nothing outside the project
gnux shell --sandbox . -e ./build.gnuxLet a cleanup script read the shared config but write only in dist
gnux shell --sandbox dist --sandbox-read config -c 'rmx -rf dist/* && cpx config/app.json dist/'Pipe a script in
echo 'catx *.log | wcx -l' | gnux shellExit status
| Status | Meaning |
|---|---|
| N | the exit status of the last command run |
| 1 | a redirection could not be opened (that command is not run), or with -u a variable was not set |
| 2 | a syntax error, exit with a non-numeric argument, or a command-line mistake |
| 125 | --sandbox was given but the sandbox could not be entered; nothing was run |
| 127 | an unknown command, or a SCRIPT that cannot be opened |
Help in the terminal
gnux help shell # this page: the full manual
gnux help shell --OPTION # one option in depth, with its examples