4.6 KiB
Chapter 4 — Shell, PATH, and scripts
Prerequisites: Running seeder and booter. Time to read: about six minutes.
On this page
- Line shell and
/bin - How a command runs (conceptually)
- User scripts and PATH
- What is different from Node on the host
- Example commands (safe to try)
- Builtins,
/bin, and/proc
Line shell and /bin
Inside the booted image you interact through a line-oriented shell (fish-style readline is available unless disabled). It supports pipelines, redirects, and a broad set of utilities under /bin, including text tools such as sed and awk.
The shell and utilities are part of the guest runtime built by the booter. They are not the same process as your host’s system shell; they execute against the virtual file system that merges the system drive, personal drive, and synthetic mounts such as /proc.
For POSIX coverage and deliberate gaps, see Handbook — Chapter 9.
How a command runs (conceptually)
When you type a command name, the runtime resolves it against PATH. Built-in and /bin tools are implemented as guest JavaScript evaluated in a controlled way (no arbitrary Node import graph for drive-resident scripts). The booter supplies a ctx object that exposes the VFS, environment, subprocess helpers, and many optional bridges; in-image user scripts use the run(ctx, argv) convention.
You do not need the full ctx reference to use the system day to day. When you start writing or packaging scripts, read Developer guide — User scripts and PATH and Developer guide — The context object.
User scripts and PATH
Scripts on your personal or system drive can be executed when they are discoverable on PATH or invoked with a ./ path, subject to shebang and permission rules described in the developer guide. The stock kernel’s readline loop hands lines to the shell, which may invoke /bin tools or launch *.js handlers.
If a command is not found, verify PATH, whether the file is executable in the VFS sense, and whether you are in guest versus unlocked identity (some locations are only writable or meaningful after login).
What is different from Node on the host
Pear and Node on your laptop run ESM packages with normal import. Drive-resident scripts inside Bare OS follow the in-image execution model: they are not a second copy of Node with free module resolution. That distinction matters when you port tools from npm or expect node: built-ins to exist unchanged.
For a careful comparison of the two runtimes, read Developer guide — Two runtimes: host vs in-image. For guest-safe module choices, see Node → Bare module map.
Example commands (safe to try)
After the shell prompt appears, these exercises help build intuition without touching identity material:
uname -a
echo $HOME $USER
ls -la /bin | head
man ls | head -n 20
Pipelines and redirects behave like a small Unix (ls | wc -c, echo hello > /tmp/x), but paths such as /tmp map through the VFS—not every corner case matches Linux. When a command fails, read the stderr line first; many utilities print usage: hints aligned with man.
Builtins, /bin, and /proc
The shell implements builtins ( cd, export, control flow, …) in packages/bare-os-booter/lib/shell.js. Everything else normally resolves to /bin/<name> via PATH. Synthetic trees such as /proc/bare_os_features expose JSON or text summaries of capabilities and runtime state; they are documented in the kernel extensions reference and handbook chapters on the booter. If a name does not resolve, verify you are not shadowing a shell builtin and that PATH includes /bin (try command -v <name> when the shell supports it, or which <name> if installed).
Previous: Chapter 3 · Next: Chapter 5 — Home, identity, and vault