The utilities

The commands you type. Every one of them is documented here, and the documentation is the source of truth the implementation is held to - utilities/0_conventions.md is the shared contract all of them obey, and a utility that breaks it is a bug in the utility.

Why they look the way they do

A GodspeedOS utility is not a Unix utility with the corners knocked off. The primitives Unix builds on do not exist here: no fork, no exec, no inherited file descriptors, no ambient stdin, no environment inheritance, no signals. What replaces them is capabilities.

   UNIX                              GODSPEEDOS
   ls /data | grep .txt              dir /data | match .txt
   ────────────────────              ──────────────────────
   fork + exec + pipe(2)             the shell carries each stage's output
   fd 1 inherited by the child       on; a SERVICE stage gets an endpoint
   ambient access to /data           `dir` holds a cap to `fs`, or it
                                     cannot read anything at all

Three consequences you will feel immediately:

rm -rf / cannot exist. A utility can only touch what it was granted. There is no ambient authority to leak through a fork.
Words, not flags. write append /f.txt text, not write -a. A flag is a character to memorise; a word is readable a year later. (0_conventions.md §1.)
Every utility answers version and help. Not as a courtesy - as a contract, checked.

The full set

Each links to its full specification: what it is, what it may do, what it may not do, and how it fails.

Files and directories


`dir`	list a directory
`cd`	change current location
`pwd`	print the folder you are in
`home`	go to your home folder
`read`	print a file's contents
`write`	create, overwrite, append, or prepend a file
`mkdir`	create a directory
`copy`	copy a file or a whole subtree
`move`	relocate a file
`rename`	rename a file or directory in place
`delete`	remove a file, directory, or whole subtree
`seal`	freeze a file's content, permanently (no unseal)
`churn`	hammer the filesystem for N seconds so a power cut lands somewhere
`find`	search the tree for a name
`tree`	print the directory hierarchy
`edit`	the full-screen editor (a bounded piece table - any file size)
`fcap`	open a file as a real kernel capability
`drives`	manage attached disks

Text and records


`echo`	write text
`docs`	the manual: what the system is, and what you can rely on
`paginate`	read long output a screenful at a time (pipe stage)
`scrollback`	read back what has scrolled off the screen (also: PgUp)
`match`	keep the lines that match (the grep-equivalent)
`count`	how many lines, words, and bytes
`sort`	order the lines
`first` / `last`	keep the first or last N lines
`where` / `select` / `to` / `from`	typed record pipelines

The system


`status`	what is running, and where
`observe`	the live full-screen view
`caps`	what authority a service actually holds
`whatis`	what a name is: built-in, script, pipe stage, or service
`trace`	live kernel state: what is stuck, who can reach whom
`events`	what was recorded: IPC ring, metrics, logs, capture to disk
`mem`	memory
`cores`	the cores that came up
`hardware`	this machine's devices, and what drives each
`ask`	plain questions about this machine, answered from what its services know
`godspeed`	the native package manager: its settings, and the registry reached over verified TLS
`download`	a file from a web server, saved here: https:// checked, http:// said to be unchecked
`spawncap`	diagnostic: spawn a service and prove the capability to it routes
`uptime`	how long since boot
`date`	the wall clock
`audio`	sound: what is playing, the volume, a test tone
`about`	what this system is
`version`	version, of anything
`clear`	clear the screen

Lifecycle


`spawn`	start a service
`kill`	stop one
`restart`	stop and start, possibly on another core
`chaos`	kill things deliberately, and see what survives
`reboot`	restart the machine, now or after a delay
`poweroff`	not provided - and the page says why
`shutdown`	turn the machine off, now or after a delay (hardware-verified on all five boards)
`background`	run long work as a job, so the prompt stays usable

Networking


`net`	am I on the network?
`wifi`	what wireless networks are there, and join one
`sock`	a UDP socket as a capability
`ping`	continuous ICMP echo
`tcp`	one TCP transaction: connect, send, read, close
`serve`	accept one TCP connection and echo what arrives

Scripting


`run`	execute a script of commands
`assert`	verify a result or output (the test verb)
`result`	the previous command's result (Ok / Err)
`wait`	wait
`repeat`	run a command again and again
`fmt`	format a script to the GodspeedOS standard

The shared contract


Conventions	the fourteen rules every utility above obeys

One page worth reading even if you skip the rest

poweroff documents a utility that does not exist. It was built, tested, and removed - the firmware's ACPI \_PTS method could not be executed without an AML interpreter, and adding one to reach a power state was not a trade worth making. The page records what was tried, what stopped it, and what would have to change.

That is the house style: a limitation that cannot be closed is written down, never quietly left (§26.7).