74 lines
4.6 KiB
Markdown
74 lines
4.6 KiB
Markdown
# Chapter 4 — Shell, PATH, and scripts
|
||
|
||
**Prerequisites:** [Running seeder and booter](03-running-seeder-and-booter.md). **Time to read:** about six minutes.
|
||
|
||
---
|
||
|
||
## On this page
|
||
|
||
- [Line shell and `/bin`](#line-shell-and-bin)
|
||
- [How a command runs (conceptually)](#how-a-command-runs-conceptually)
|
||
- [User scripts and PATH](#user-scripts-and-path)
|
||
- [What is different from Node on the host](#what-is-different-from-node-on-the-host)
|
||
- [Example commands (safe to try)](#example-commands-safe-to-try)
|
||
- [Builtins, `/bin`, and `/proc`](#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](../handbook/09-posix-utilities-shell-and-vfs.md).
|
||
|
||
---
|
||
|
||
## 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](../developer-guide/04-user-scripts-and-path.md) and [Developer guide — The context object](../developer-guide/02-the-context-object.md).
|
||
|
||
---
|
||
|
||
## 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](../developer-guide/01-two-runtimes-host-vs-image.md). For guest-safe module choices, see [Node → Bare module map](../developer-guide/node-to-bare-modules.md).
|
||
|
||
---
|
||
|
||
## Example commands (safe to try)
|
||
|
||
After the shell prompt appears, these exercises help build intuition without touching identity material:
|
||
|
||
```sh
|
||
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](../docs/reference/kernel-extensions.md) 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](03-running-seeder-and-booter.md)_ · _Next: [Chapter 5 — Home, identity, and vault](05-home-identity-and-vault.md)_
|