Command Reference

Command reference

Every command available in NyxOS: ~209 kernel-shell builtins and ~101 ring-3 programs (including the in-OS C compiler /tcc.elf — see Toolchain — and, via xbm install ncc, the N compiler — see N-Language). Help strings are quoted verbatim from the commands[] table in kernel/core/kernel.c; program descriptions come from the source of each user/*.c.

Tip

Run man <command> in the shell for a formatted manual page (NAME / SYNOPSIS / DESCRIPTION) of any command — the man_pages table now covers 86 commands (v6.4.56, v6.4.63, v6.4.79). help groups the builtins under category headers (v6.4.71).

For how the two shells differ, see Shell.

See also: Shell, Userspace, Syscall-Reference, Debugging

Resolution order

When you type a word at the kernel shell:

1. Match against the commands[] table → run the builtin
2. Otherwise, if /<name>.elf exists → auto-exec it in the foreground, argv forwarded
3. Otherwise → command not found

A builtin always shadows a program of the same name. Under the userspace shell (/sh.elf) there are no kernel builtins — every word resolves through $PATH — except its own shell builtins.

---

Kernel-shell builtins

System information

Command	Help string	Notes
help	Show this help	Lists every non-hidden builtin
version	Show kernel version	KERNEL_VERSION, currently 6.4.363
man	Show a command's manual page: man <command>	NAME/SYNOPSIS/DESCRIPTION, 86 commands covered
uname	Show system information
nyxfetch	Show system info with ASCII logo	Crescent-moon logo from nyx_logo.h
fastfetch	Alias for nyxfetch
date	Show current date and time	Reads the RTC
history	Show command history
env	Show environment variables
export	Set env variable: export <name>=<value>
mem	Show memory usage	Physical pages and heap
hexdump	Dump memory: hexdump <addr> [bytes]
clear	Clear the screen
reboot	Reboot the system
crash	Trigger a kernel panic	Verifies the panic path still works

Files and directories

Command	Help string
ls	List directory contents: ls [path]
cd	Change directory: cd <path>
pwd	Print working directory
cat	Display file contents: cat <file>
touch	Create empty file: touch <file>
mkdir	Create directory: mkdir <dir>
rm	Remove file or directory: rm <path>
cp	Copy file: cp <src> <dst>
mv	Move/rename file: mv <src> <dst>
write	Write text to file: write <file> <text>
head	Show first lines of a file: head <file> [lines]
tail	Show last lines of a file: tail <file> [lines]
grep	Search file contents: grep <pattern> <file>
sort	Sort lines of a file: sort <file>
wc	Count lines/words/chars: wc <file>
find	Find files by name: find <name> [path]
tree	Show filesystem tree: tree [path]
diff	Compare two files: diff <file1> <file2>
which	Show path of a command: which <name>
open	Open a file in the GUI Text Editor: open <file>
mount	Mount EXT2: mount [drive] [part_lba]
ext2ls	Alias for mount
ext2cat	Alias for mount
df	Show disk usage of the mounted filesystem

The v6.4 userland climb added flags to several of these — grep -i/-n/-v, sort -r/-n, ls -a/-l, wc -l/-w/-c — and replaced the naive diff with a real LCS-based diff.

Text and data utilities

Added across v6.4.23–v6.4.182 (builtins, most also shipped as ring-3 coreutils):

Command	Purpose
uniq	Collapse adjacent duplicate lines
cut	Select fields/columns
nl	Number lines
tac	Concatenate in reverse line order
seq	Print a number sequence
rev	Reverse the characters of each line
tr	Translate / delete (-d) / squeeze (-s) characters, with ranges and POSIX classes (-cds)
fold	Wrap long lines to a width (-w/-b/-s)
expand / unexpand	Tabs → aligned spaces, and the inverse
printf	Format and print arguments (backslash escapes, %s/%d/…)
basename / dirname	POSIX path splitting
cal	Month calendar (cal(1))
xxd	Canonical hex + ASCII dump
base64 / base32	RFC 4648 codecs (encode/decode)
cksum	POSIX CRC-32 checksum + byte count
comm	Compare two sorted files in three columns
tee	Copy stdin to stdout and to files
paste	Merge lines of files in parallel or serial (-s/-d)
join	Relational join of two sorted files
split	Split a file into pieces
od	Octal / hex / char file dump
cmp	Byte-by-byte file comparison
sum	Classic BSD/SysV checksum
column	Align input into a table
factor	Prime factorisation of 64-bit integers
dd	Block copy with bs/count/skip/seek/conv
xxd -r	Revert a hex dump back to binary

Checksums and digests

Command	Purpose
sha256sum	FIPS 180-4 SHA-256 digests (GNU format)
sha512sum	FIPS 180-4 SHA-512 digests
md5sum	RFC 1321 MD5 digests (matches GNU md5sum; interop only)
crc32c	CRC-32C (Castagnoli) checksum
fnv	FNV-1a hash (32/64-bit)
fletcher	Fletcher-16/32 positional checksum
murmur	MurmurHash3-32 non-cryptographic hash

Backed by the general-purpose crypto library — see Cryptography-and-TLS#the-general-purpose-crypto-library.

Encodings, parsers and data tools

Command	Purpose
base58	Bitcoin Base58 encode/decode
bech32	BIP-173 checksummed base-32 encode/decode
urlcode	URL percent-encoding (RFC 3986)
csv	RFC 4180 CSV field parser + table viewer
semver	Strict SemVer 2.0.0 parse and compare
iniget	Hardened INI / conf reader
file	File-type identification (magic + UTF-8)
tar	ustar archive lister
tsort	Topological sort of a dependency list
factor	Prime factorisation (64-bit)
date +FORMAT	strftime date formatting
vfsstat	VFS node-pool census (see Filesystem)

More v6.4 commands (v6.4.223–361)

A large run of additions. By area:

Area	Commands
Text / data	comm tee paste join split du strings sed expr fmt pr truncate shuf patch xargs realpath identify convert
Compression	deflate gzip gunzip zcat
Data formats	json (validate + json get jq-lite), calc, ipcalc, uuid
Crypto / files	sha256sum hmac totp encrypt/decrypt (AES-128-GCM + PBKDF2) shred mktemp
Processes	pgrep/pkill pstree taskset timeout time nproc uptime nice/renice
System / power	poweroff/halt/shutdown (ACPI soft-off), du, disks/lsblk, lspci, screenshot
Network	netstat route arp httpd (one-request server), ipcalc, wav
Install	nyxinstall nyxpart nyxgpt nyxfat nyxgrub mkfs nyxverify nvme — see Installation
Graphics / media	wav identify convert screenshot
Shell conditionals	test / [ · true · false — for && / || chains

The shell itself gained history expansion (!!, !N, !-N), $VAR/${VAR} and $((expr)) expansion, and alias/unalias (v6.4.283–319). The Text Editor gained Ctrl+F find and Ctrl+R replace; Erebus (the terminal) gained Up/Down history and Ctrl+R reverse search.

Processes and jobs

Command	Help string
ps	List processes
kill	Kill a process: kill <pid>
exec	Run ELF in foreground (waits): exec <file>
spawn	Run ELF in background: spawn <file>
cc	Compile/link C in-OS: cc [-c] [--self-libc] [--self] <in.c/.o ...> [-o out] — drives the ported tcc; see Toolchain
xbm	Package manager: xbm install|remove <name> · xbm search <str> · xbm list [--installed] — compiles packages with cc; see Toolchain#packages--xbm
jobs	List background jobs
wait	Wait for background jobs: wait [pid]
nice	Spawn ELF at a scheduler weight: nice <weight> <file>
renice	Change a process's weight: renice <pid> <weight>
usertest	Spawn preemptive ring-3 test processes
mtdemo	Preemptive multitasking self-test

sched_weight ranges 1–64. The compositor runs at 4 (SCHED_WEIGHT_GUI); background jobs default to 1.

Multi-core

Command	Help string
cpus	List CPU cores (SMP)
smpstress	Hammer the allocators from every CPU: smpstress [secs]
smpthreads	Run the per-AP kernel threads: smpthreads [secs]
smpuser	Spread user processes over the CPUs: smpuser [n]
smpbalance	Spread new processes AND threads over CPUs: smpbalance [on|off]
tlbtest	Prove cross-CPU TLB shootdown works
cowtest	Test demand paging + copy-on-write

See SMP.

Users

Command	Help string
useradd	Add a user account: useradd <user> <pass>
users	List user accounts

Accounts are stored on the EXT2 disk as user:salt_hex:iterations:hex_hash:avatar, hashed with PBKDF2-HMAC-SHA256 at 10 000 iterations. Minimum password length is 4. See Security.

Network

Command	Help string
ifconfig	Show network interfaces
dhcp	Request IP via DHCP
setip	Set static IP: setip <ip> <mask> <gw>
ping	Ping a host: ping <ip|hostname>
dns	DNS resolve: dns <hostname>
httpget	HTTP GET: httpget <url>
tcptest	Test TCP: tcptest <ip> <port>
tcpserve	Serve one TCP/HTTP connection: tcpserve [port]
tcploop	In-guest TCP loopback self-test: tcploop [drop]
tcpdrop	Test: drop next N TCP TX segs (force retransmit)

ping sends 4 echo requests and reports RTT and loss. See Networking-Stack.

TLS

Command	Help string
tls	TLS handshake test: tls <host> (https :443)
tlsstrict	Strict TLS cert enforcement: tlsstrict [on|off]
posttest	Live HTTP POST self-test (POST a form to httpbin over TLS)

Strict mode is off by default. See Cryptography-and-TLS.

Display and audio

Command	Help string
setres	Set screen resolution (setres 800 600)
mode	Set VBE video mode: mode <width> <height> <bpp>
desktop	Launch window compositor desktop
gui	Launch GUI demo with mouse
fonttest	Test font rendering on framebuffer
layout	Change keyboard layout: layout <us|es>
beep	Play a tone: beep [freq] [ms]
play	Play a demo melody
sb16play	Test SB16 playback: sb16play [freq] [ms]

Warning

setres and mode pass the mode straight through — vbe_set_mode validates nothing. An unsupported mode leaves you with an unusable display.

Applications and games

Command	Help string
selene	Open Selene, the web browser
doom	Play DOOM in a window (Ctrl-C to quit)
pong	Play Pong (mouse or arrows)
snake	Play Snake (arrows/WASD)
tetris	Play Tetris (arrows, Space=drop)
voxel	Open Nyx Voxels (isometric voxel sandbox)
fire	Open Nyx Fire (animated doom-fire effect)
matrix	Open Nyx Matrix (green code-rain effect)
lava	Open Nyx Lava (animated plasma effect)
fractal	Open Nyx Fractal (Mandelbrot render-perf demo)
julia	Open Nyx Julia (morphing Julia-set render-perf demo)
rotor	Open Nyx Rotor (spinning 3D point-lattice render-perf demo)
fill	Open Nyx Fill (2D fill-rate / overdraw render-perf demo)
life	Open Nyx Life (Conway's Game of Life compute/render-perf demo)

See Desktop-Applications for the visual effects and render-performance demos.

Self-tests

Every entry is a known-answer test against published vectors, printing a per-case result and returning non-zero on failure.

Cryptography

Command	Help string	Vectors
x25519test	X25519 (Curve25519) self-test — RFC 7748 vectors	RFC 7748
prftest	TLS 1.2 PRF self-test — RFC 4231 + P_SHA256 vectors	RFC 4231
tlskeytest	TLS 1.2 key-schedule self-test (master secret + keys)
gcmtest	AES-128-GCM self-test — FIPS-197 + NIST GCM vectors	FIPS 197, SP 800-38D
tlsrectest	TLS record + Finished self-test (GCM records, verify_data)
csprngtest	CSPRNG self-test — HMAC_DRBG (NIST) + hardware entropy	SP 800-90A
dertest	DER/ASN.1 reader self-test (X.509 pubkey extraction)
p256test	NIST P-256 self-test (point multiples + ECDSA verify)	FIPS 186-4
p384test	NIST P-384 self-test (point multiples + ECDSA verify)	FIPS 186-4
skp384test	ECDSA-P384 ServerKeyExchange verification self-test
rsatest	RSA PKCS#1 v1.5 SHA-256 signature-verify self-test	RFC 8017
sha512test	SHA-512 / SHA-384 self-test (FIPS 180-4 vectors)	FIPS 180-4
chaintest	X.509 certificate-chain verification self-test (pinned root)

Images

Command	Help string
deflatetest	DEFLATE/zlib decompression self-test (for PNG images)
pngtest	PNG image decoder self-test (color types + filters)
bmptest	BMP image decoder self-test (24/32/8-bit + top-down)
giftest	GIF image decoder self-test (LZW + interlace + transparency)
jpegtest	JPEG (baseline) decoder self-test (Huffman + IDCT + YCbCr)

Browser

Command	Help string
formtest	Selene HTML-forms self-test (parse form + build GET URL)

---

Ring-3 programs

62 ELF binaries, built by kernel/Makefile into user/ and packed into the initramfs. Run by bare name from either shell.

Coreutils

Program	Synopsis	Behaviour
cat	cat [FILE…]	Concatenate files to stdout. With no arguments, copies stdin
wc	wc [FILE…]	Count lines, words and bytes of each file, or of stdin
ls	ls [DIR]	List a directory, default /. Enumeration is getdents()
cp	cp SRC DST	Stream SRC into a freshly created, truncated DST
mv	mv SRC DST	Move a file
rm	rm PATH…	Unlink each argument
mkdir	mkdir DIR…	Create each directory, cwd-relative or absolute
touch	touch FILE…	Create as empty if absent (open with O_CREAT)
grep	grep PATTERN [FILE…]	Print input lines containing PATTERN, a literal substring
head	head [-n N] [FILE…]	First N lines, default 10
tail	tail [-n N] [FILE…]	Last N lines, default 10, via a circular buffer
sort	sort [FILE…]	Read fully, sort lines with strcmp, print
find	find [DIR] [NAME]	Recursive walk, optionally filtered by name substring
stat	stat FILE	Size and type via stat(2)
echo	echo ARG…	Write arguments space-separated to fd 1
upper	upper	Read stdin to EOF, uppercase, write to stdout
which	which NAME…	Print what each NAME resolves to via $PATH
clear	clear	Clear the terminal; ESC[3J also erases scrollback
env	env	Print the environment, one NAME=VALUE per line
date	date	Current date and time via time()
sleep	sleep N	Pause N seconds
uname	uname [-a]	With no arguments prints just the OS name
whoami	whoami	Current user, from $USER
free	free	Memory usage, read from /proc/meminfo
pmap	pmap [PID]	Mapped regions, read from /proc/<pid>/maps

Interactive

Program	Synopsis	Notes
sh	sh [-c LINE]	The userspace shell. No arguments = interactive REPL
top	top	Live process monitor; redraws every ~1.5 s, q quits
edit	edit [FILE]	Full-screen nano-style editor
less	less [FILE]	Full-screen pager; reads stdin with no argument
more	more [FILE]	Same binary as less

edit key bindings

Key	Action
Arrows	Move the cursor
Home / End	Line start / end
PgUp / PgDn	Page up / down
Enter	Split the line
Backspace	Join or delete
Ctrl-O	Save
Ctrl-X	Exit

Process and system

Program	Synopsis	Notes
ps	ps	Process table via getprocs()
kill	kill [-SIG] PID…	Numeric or named signals

Network

Program	Synopsis	Notes
nc	nc [-u] HOST PORT	Netcat over TCP or UDP; full-duplex via poll()
wget	wget URL	HTTP/1.0 client with its own DNS-over-UDP resolver; follows redirects

Games

Program	Notes
doom	The 1993 shareware DOOM. Requires /mnt/doom1.wad. main() injects -iwad /mnt/doom1.wad when launched with no arguments

Demos and regression tests

These exist to prove specific kernel behaviour, and are the shortest route to understanding a subsystem.

Program	Proves
init	The full syscall regression suite — fork, execve, signals, pipe, mmap, mprotect, /dev, /proc
hello	Minimal "Hello World", pure assembly, no libc
hello_nyx	The first Nyx C program, transpiled to C
args	execve argv passing — prints argv, exits with argc
spin	A spin loop, for scheduling tests
threads	clone(CLONE_VM) + futex, and the shared thread-group heap
fault	A NULL dereference becomes SIGSEGV, not a kernel panic
segv	A catchable CPU-exception signal with a handler installed
sigrec	Multi-fault recovery via sigsetjmp/siglongjmp
alarmdemo	alarm() and SIGALRM
stacktest	Demand-grown user stacks and the guard page
vmtest	The user/kernel address boundary actually holds
munmaptest	Partial munmap splits the VMA
mprotecttest	Partial mprotect splits the VMA, leaving pages outside untouched
dltest	dlopen/dlsym against libdemo.so, without linking it
fdleak	Fds are force-closed when a process exits without closing them
fsx	dup, rename, and the per-process cwd
vfsfill	The VFS per-directory child cap
sockdemo	TCP client sockets against the built-in echo service
srvdemo	TCP server sockets — bind/listen/accept
udpdemo	UDP over loopback
polldemo	poll() watching a pipe and a TCP socket at once
keyevtest	The raw key-event path — press and release
fbtest	The fullscreen framebuffer syscalls
bigread	A large-.bss stdin consumer, for the pipeline reproducer
pstorm	Pipeline storm — drives the shared-libc fault reproducer
netstorm	Concurrent multi-process TCP stress

Toolchain

File	Purpose
tcc.elf	The in-OS C compiler — a port of TinyCC 0.9.27. Driven by the cc builtin; also runnable directly. Compiles, assembles and links C to x86-64 ELF entirely in-OS. See Toolchain

Shared libraries

File	Purpose
libc.so	The prelinked shared libc mapped into every process at 0x30000000
libdemo.so	A tiny demonstration library for dlopen/dlsym

---

Userspace shell builtins

/sh.elf implements these in-process, because they change the shell's own state — a forked child's cd would be lost on exit.

Builtin	Syntax	Effect
cd	cd [DIR]	Change directory; no argument goes home
pwd	pwd	Print working directory
export	export NAME=VALUE	Set a shell environment variable
jobs	jobs	List background and stopped jobs
fg	fg [PID]	Resume a job in the foreground
bg	bg [PID]	Resume a stopped job in the background
true	true	Exit status 0
false	false	Exit status 1
exit	exit	Leave the shell
demo	demo	Run the canned demonstration script

Shell syntax

Feature	Example
Pipeline, up to 4 stages	ls / | grep elf | wc
Redirect out, truncate	echo hi > f
Redirect out, append	echo more >> f
Redirect in	sort < f
Sequence	a ; b
And-list	a && b
Or-list	a || b
Background	spin &
Command substitution	echo $(pwd)
Single quotes, fully literal	'literal $x'
Double quotes, expansion still applies	"expanded $x"
Glob	ls *.elf, cat file?.txt
Home expansion	cd ~
Variable	$VAR
Last exit status	$?

Limit	Value
Pipeline stages	4 (MAX_STAGES)
Arguments per stage	12 (MAX_ARGS)
History entries	16

Line editing

Raw tty mode gives the shell byte-at-a-time input; it renders its own line.

Key	Action
← / →	Move cursor
Home / End	Line start / end
↑ / ↓	Walk history, deduped against the last entry
Tab	Complete builtins, *.elf programs and paths; pipeline-aware after |
Backspace / Delete	Edit anywhere in the line
Ctrl-C	SIGINT to the foreground job
Ctrl-Z	SIGTSTP — stop the job

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

See also

• Shell — how the two shells relate
• Userspace — the programs in depth
• Syscall-Reference — what these commands call
• HOWTO-Add-a-shell-command — add a builtin
• Debugging — using the self-test suite

External resources

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