Skip to Content
gnux

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 exit

Examples

Start an interactive session

gnux shell

Run 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.gnux

Run a script with arguments, refusing unset variables

gnux shell -eu release.gnux v1.2.3 dist

Loop 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.gnux

Let 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 shell

Exit status

StatusMeaning
Nthe exit status of the last command run
1a redirection could not be opened (that command is not run), or with -u a variable was not set
2a 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
127an 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

See also

On this page