Shell

Shell

NyxOS has two shells, and it is worth knowing which one you are typing into.

	Kernel shell	Userspace shell (/sh.elf)
Runs in	Ring 0	Ring 3
Reached from	Serial console, GUI terminal window	exec /sh.elf, or sh -c "…"
Commands	~209 builtins compiled into the kernel	fork + execve of real programs
Pipelines	No	Yes, up to 4 stages
Purpose	Kernel control and self-tests	A real Unix-style shell

Both offer tab completion and command history. The kernel shell auto-execs userspace ELFs: typing a bare name that is not a builtin runs /name.elf with argv forwarded, so wget, whoami and stat work without an exec prefix.

See also: Userspace, Process-Management, Filesystem, Networking-Stack, GUI-Subsystem

---

The userspace shell (/sh.elf)

A genuine Unix shell built entirely on the ring-3 process toolkit — fork(), execve(), waitpid(), pipe(), dup2(), setfg(). It has needed zero kernel changes for most of its features.

Syntax

Feature	Example
Pipelines (≤ 4 stages)	ls / | grep elf | wc
Redirection	echo hi > f · echo more >> f · sort < f
Command lists	a ; b · a && b · a || b
Background jobs	spin &
Command substitution	echo $(pwd)
Quoting	'literal $x' · "expanded $x"
Globbing	ls *.elf · cat file?.txt
Home expansion	cd ~
Variables	$VAR, $? (last exit status)

Builtins

cd [dir] · pwd · export NAME=value · jobs · fg [pid] · bg [pid] · true · false · exit · demo

These must be builtins because they change the shell's own state — a forked child's cd would be lost on exit.

Line editing

Raw tty mode (ttymode(TTY_RAW)) gives the shell byte-at-a-time input, and it renders its own line:

Key	Action
←/→	Move the cursor
Home / End	Jump to line start/end
↑/↓	Walk a 16-entry history (deduped against the last entry)
Tab	Complete commands (builtins + *.elf, pipeline-aware after |) and paths
Backspace/Delete	Edit anywhere in the line
Ctrl-C	SIGINT to the foreground job
Ctrl-Z	SIGTSTP — stop the job; resume with fg/bg

Tab completion fills in a unique match with a trailing space or /; several matches extend to the longest common prefix, or list the candidates.

$PATH

The shell searches $PATH to resolve a command name, so programs run by bare name. which NAME prints what a name would resolve to.

Modes

sh                        # interactive REPL at a `sh$ ` prompt
sh -c "ls / | grep elf"   # run one line and exit

---

Kernel shell builtins

Files and directories

ls cd pwd cat touch mkdir rm cp mv write echo diff head tail grep sort wc find tree which open df mount

open <file> is the cross-app one: it opens the file in the GUI Text Editor.

Processes and jobs

Command	Purpose
exec <file>	Run an ELF in the foreground and wait
spawn <file>	Run an ELF in the background
nice <weight> <file>	Spawn at a chosen scheduler weight
renice <pid> <weight>	Change a running process's weight (1–64)
ps	Process table
kill <pid>	Terminate a process
jobs	List background jobs
wait [pid]	Block until a child, or all children, exit
mem	Memory usage
mtdemo	Preemptive multitasking self-test
usertest	Spawn preemptive ring-3 test processes
cc [-c] [--self-libc] <in.c/.o …> [-o out]	Compile/link C in-OS via the ported tcc — see Toolchain

Multi-core

cpus smpstress [secs] smpthreads [secs] smpuser [n] smpbalance [on|off] tlbtest cowtest

See SMP.

Network

Command	Purpose
ifconfig	Interfaces and addresses
dhcp	Request a lease
setip <ip> <mask> <gw>	Static configuration
ping <ip|host>	4 ICMP echoes with RTT and loss
dns <hostname>	Resolve an A record
httpget <url>	Fetch a URL
tcptest <ip> <port>	Open a connection
tcpserve [port]	Serve one TCP/HTTP connection
tcploop [drop]	In-guest loopback self-test
tcpdrop <n>	Drop the next N TX segments, forcing retransmission
tls <host>	TLS handshake against host:443
tlsstrict [on|off]	Strict certificate enforcement
posttest	Live HTTP POST self-test over TLS

System

help version uname nyxfetch (alias fastfetch) date clear reboot history env export hexdump layout <us|es> useradd <user> <pass> users crash

Display and audio

gui desktop setres <w> <h> mode <w> <h> <bpp> fonttest beep [freq] [ms] play sb16play [freq] [ms]

Games and apps

doom pong snake tetris selene

See Desktop-Applications and Selene-Browser.

Self-tests

The kernel ships known-answer tests for most of the crypto and image code. They are the fastest way to check a build.

Area	Commands
Cryptography	x25519test prftest tlskeytest gcmtest tlsrectest csprngtest dertest p256test p384test skp384test rsatest sha512test chaintest
Images	deflatetest pngtest bmptest giftest jpegtest
Kernel	cowtest tlbtest mtdemo smpstress smpthreads
Browser	formtest

---

Ring-3 programs

Run from either shell by bare name. Full descriptions in Userspace.

Coreutils

cat wc ls cp mv rm mkdir touch grep head tail sort find stat echo upper which clear env date sleep uname whoami free pmap

Interactive

Program	Purpose
sh	The userspace shell
top	Live process monitor (TUI)
edit	Full-screen nano-style text editor (TUI)
less / more	Full-screen pager

Process and system

ps · kill [-SIG] pid...

Network

nc (netcat, full-duplex) · wget (HTTP client with its own resolver)

Games

doom — the 1993 shareware DOOM, as a real ring-3 ELF. Needs /mnt/doom1.wad.

See also

• Command-Reference - every builtin and program, exhaustively
• Userspace - the programs listed here, in detail
• HOWTO-Add-a-shell-command - add a kernel builtin
• Debugging - the self-test suite
• Filesystem - what the file commands operate on

External resources

• POSIX.1-2017 - Shell Command Language - The Open Group
• GNU coreutils manual - GNU