{"schemaVersion":1,"generatedAt":"2026-04-04T02:30:59.953Z","pages":[{"name":"awk","section":1,"title":"pattern scanning and processing language","synopsis":["awk [OPTION]... [OPERAND]..."],"description":"Pattern-directed scanning and processing. Engine in lib/awk-engine.js; not full POSIX awk.","options":[],"keywords":["awk","pattern","field","script"],"seeAlso":[{"name":"sed","section":1},{"name":"grep","section":1}],"bareOsNotes":"See handbook ch.9 for divergence from Issue 7.","examples":[{"caption":"print column 1","code":"awk '{print $1}' file.txt"},{"caption":"field separator","code":"awk -F: '{print $1}' /etc/passwd"},{"caption":"sum numbers in first column","code":"awk '{s+=$1} END{print s}' nums.txt"},{"caption":"lines matching /re/","code":"awk '/error/{print NR\": \"$0}' log.txt"}],"listCategory":"coreutils"},{"name":"basename","section":1,"title":"strip directory and suffix from pathnames","synopsis":["basename [OPTION]... [OPERAND]..."],"description":"Prints the last path component. Supports multiple paths with -a, suffix removal with -s or a second operand.","options":[{"flag":"-a, --multiple","meaning":"Treat every operand as a path"},{"flag":"-s SUFFIX, --suffix","meaning":"Remove trailing SUFFIX from basename"}],"keywords":["basename","bare-os","coreutils"],"examples":[{"caption":"strip directory","code":"basename /home/user/docs/readme.md"},{"caption":"strip suffix","code":"basename -s .md /path/readme.md"},{"caption":"several paths","code":"basename -a /a/x /b/y"}],"listCategory":"coreutils"},{"name":"cat","section":1,"title":"concatenate and print files","synopsis":["cat [OPTION]... [OPERAND]..."],"description":"Concatenates operands to stdout. With no operands, reads **`bareStdin(ctx)`**. Operand **`-`** is stdin. When **`process.stdout.write`** exists (host), output uses it so trailing newlines are not altered; otherwise **`ctx.console.log`** is used per chunk.","options":[{"flag":"-n","meaning":"Number all lines (width 6, tab after number)."},{"flag":"-b","meaning":"Number non-empty lines only (implies not **`-n`**)."},{"flag":"-A","meaning":"Equivalent to **`-vET`** (show ends, tabs, and non-printing)."},{"flag":"-e","meaning":"Like **`-vE`**."},{"flag":"-t","meaning":"Like **`-vT`**."},{"flag":"-E","meaning":"Show **$** before each newline."},{"flag":"-T","meaning":"Show tabs as **^I**."},{"flag":"-v","meaning":"Show non-printing characters (**^** / **M-** style)."}],"keywords":["cat","bare-os","coreutils"],"examples":[{"caption":"stdout several files","code":"cat a.txt b.txt"},{"caption":"numbered lines","code":"cat -n file.txt"},{"caption":"stdin explicitly","code":"cat - f.txt"}],"listCategory":"coreutils"},{"name":"chgrp","section":1,"title":"change file group ownership","synopsis":["chgrp [OPTION]... [OPERAND]..."],"description":"Changing group ownership is not supported on Bare OS: Hyperdrive metadata is single-session oriented.","options":[],"keywords":["chgrp","bare-os","coreutils","stub"],"stub":true,"diagnostics":["chgrp: changing group is not supported on Bare OS"],"bareOsNotes":"Single-user identity; gid fields exist for display only.","examples":[{"caption":"not supported — use identity model","code":"# chgrp is a stub; group is display metadata only"}],"listCategory":"coreutils"},{"name":"chmod","section":1,"title":"change file mode bits","synopsis":["chmod MODE FILE...","MODE is octal (e.g. 644) or symbolic (e.g. u+rw)"],"description":"Sets file mode bits on the VFS. Supports POSIX-style symbolic modes (u/g/o/a, +/-/=, rwxX) and octal modes.","options":[],"keywords":["chmod","mode","permission","octal","symbolic"],"diagnostics":["chmod: No such file","chmod: invalid mode"],"bareOsNotes":"Applies to Hyperdrive metadata; not a host inode.","examples":[{"caption":"octal","code":"chmod 644 ~/.profile"},{"caption":"recursive-ish (run find + chmod per file)","code":"find . -type f -name \"*.sh\" -print"},{"caption":"symbolic user bits","code":"chmod u+x script.sh"},{"caption":"all read, owner write","code":"chmod a+r,u+w shared.txt"}],"listCategory":"coreutils"},{"name":"chown","section":1,"title":"change file owner and group","synopsis":["chown [OPTION]... [OPERAND]..."],"description":"Changing file owner is not supported on Bare OS (single-user Hyperdrive metadata).","options":[],"keywords":["chown","bare-os","coreutils","stub"],"stub":true,"diagnostics":["chown: changing owner is not supported on Bare OS"],"bareOsNotes":"Use identity login/logout instead of POSIX ownership changes.","examples":[{"caption":"not supported","code":"# chown stub — see man identity / login"}],"listCategory":"coreutils"},{"name":"cksum","section":1,"title":"write file checksums and sizes","synopsis":["cksum [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of write file checksums and sizes. Full behavior is defined in packages/bare-os-coreutils/src/cksum.js.","options":[],"keywords":["cksum","bare-os","coreutils"],"examples":[{"caption":"checksum file","code":"cksum iso.img"},{"caption":"verify pipeline","code":"cat f | cksum"}],"listCategory":"coreutils"},{"name":"clear","section":1,"title":"clear the terminal screen","synopsis":["clear [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of clear the terminal screen. Full behavior is defined in packages/bare-os-coreutils/src/clear.js.","options":[],"keywords":["clear","bare-os","coreutils"],"examples":[{"caption":"wipe screen","code":"clear"}],"listCategory":"coreutils"},{"name":"cp","section":1,"title":"copy files","synopsis":["cp [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of copy files. Full behavior is defined in packages/bare-os-coreutils/src/cp.js.","options":[],"keywords":["cp","bare-os","coreutils"],"examples":[{"caption":"copy file","code":"cp src.txt dest.txt"},{"caption":"into directory","code":"cp a b c ~/backup/"},{"caption":"preserve implied (if implemented)","code":"cp -R proj proj.bak"}],"listCategory":"coreutils"},{"name":"crontab","section":1,"title":"user crontab manipulation","synopsis":["crontab [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of user crontab manipulation. Full behavior is defined in packages/bare-os-coreutils/src/crontab.js.","options":[],"keywords":["crontab","bare-os","coreutils"],"examples":[{"caption":"list jobs","code":"crontab -l"},{"caption":"install from file","code":"crontab ~/.crontab"},{"caption":"remove all","code":"crontab -r"}],"listCategory":"coreutils"},{"name":"cut","section":1,"title":"cut out selected fields of each line","synopsis":["cut [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of cut out selected fields of each line. Full behavior is defined in packages/bare-os-coreutils/src/cut.js.","options":[],"keywords":["cut","bare-os","coreutils"],"examples":[{"caption":"fields by delimiter","code":"cut -d: -f1,3 /etc/passwd"},{"caption":"characters","code":"cut -c1-16 file.txt"}],"listCategory":"coreutils"},{"name":"date","section":1,"title":"display or set date and time","synopsis":["date [OPTION]... [OPERAND]..."],"description":"Prints the current date and time, or formats it with a leading +FORMAT string (subset of strftime: %Y %m %d %H %M %S %s %z %a %b %%). Setting the clock is not supported.","options":[{"flag":"-u, --utc","meaning":"Use UTC for default output and +FORMAT"},{"flag":"+FORMAT","meaning":"strftime-like format (see description)"}],"keywords":["date","bare-os","coreutils"],"examples":[{"caption":"RFC-ish output","code":"date"},{"caption":"epoch seconds","code":"date +%s"}],"listCategory":"coreutils"},{"name":"dirname","section":1,"title":"return directory portion of a pathname","synopsis":["dirname [OPTION]... [OPERAND]..."],"description":"Prints the directory portion of each path. -z emits NUL-terminated records (host stdout).","options":[{"flag":"-z, --zero","meaning":"Separate outputs with NUL (requires process.stdout.write)"}],"keywords":["dirname","bare-os","coreutils"],"examples":[{"caption":"parent path","code":"dirname /a/b/c.txt"},{"caption":"compose with basename","code":"p=/x/y/z; echo $(dirname $p)/$(basename $p)"}],"listCategory":"coreutils"},{"name":"dircolors","section":1,"title":"print LS_COLORS from dircolors database","synopsis":["dircolors [-b] [FILE]","dircolors -p"],"description":"With -p, prints the default GNU-like dircolors database. Otherwise reads FILE (or the default database), applies TERM blocks, and outputs LS_COLORS. With -b, prints Bourne-shell export commands.","options":[{"flag":"-b, --sh","meaning":"Print LS_COLORS=… and export LS_COLORS"},{"flag":"-p, --print-database","meaning":"Print default database text"}],"keywords":["dircolors","LS_COLORS","ls","color"],"bareOsNotes":"Subset of GNU dircolors; FILE is read via VFS.","examples":[{"caption":"default database","code":"dircolors -p"},{"caption":"eval in shell","code":"eval \"$(dircolors -b ~/.dir_colors)\""}],"listCategory":"coreutils"},{"name":"du","section":1,"title":"estimate file space usage","synopsis":["du [OPTION]... [OPERAND]..."],"description":"Prints disk usage totals per path: POSIX-ish block counts by default, or human-readable byte totals with -h.","options":[{"flag":"-k","meaning":"1024-byte blocks"},{"flag":"-h, --human-readable","meaning":"IEC-style sizes (K, M, …) from byte totals"},{"flag":"-s, --summarize","meaning":"One line per operand (default behavior here)"}],"keywords":["du","bare-os","coreutils"],"examples":[{"caption":"sizes under cwd","code":"du ."},{"caption":"human-readable","code":"du -h ~"}],"listCategory":"coreutils"},{"name":"edit","section":1,"title":"terminal file editor with syntax highlighting","synopsis":["edit [file]","edit -h|--help"],"description":"Full-screen TUI editor (nano-style) for the Bare OS shell. Uses the session TTY (ctx.replStdin / replStdout), suspends the fish readline layer while active, and reads/writes paths via the VFS. Syntax highlighting is best-effort for JavaScript/TypeScript, JSON, shell, Markdown, and plain text. Files larger than 2,000,000 characters are rejected. The shell alias nano invokes edit.","options":[{"flag":"-h, --help","meaning":"Print usage and exit."}],"keywords":["edit","nano","editor","tty","syntax"],"bareOsNotes":"Requires an interactive TTY (stdin.isTTY). Uses ctx.suspendReplForSubprocess / resumeReplAfterSubprocess around raw mode.","examples":[{"caption":"edit a file","code":"edit README.md"},{"caption":"same via alias","code":"nano foo.js"}],"listCategory":"coreutils"},{"name":"echo","section":1,"title":"write arguments to standard output","synopsis":["echo [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of write arguments to standard output. Full behavior is defined in packages/bare-os-coreutils/src/echo.js.","options":[],"keywords":["echo","bare-os","coreutils"],"examples":[{"caption":"literal","code":"echo hello world"},{"caption":"no newline (if -n supported)","code":"echo -n OK"}],"listCategory":"coreutils"},{"name":"env","section":1,"title":"set the environment for command invocation","synopsis":["env [OPTION]... [-] [NAME=VALUE]... [COMMAND [ARG]...]"],"description":"Without **COMMAND**, prints the environment sorted by name. With **`-i`** / **`--ignore-environment`**, the environment for the utility starts empty (plus any **`NAME=value`** assignments before the utility). The utility runs via **`ctx.runBinCommand`**. While the utility runs, **`ctx.vfs.env`** (and **`ctx.env`** when present) are temporarily replaced and restored afterward so the parent session is unchanged.","options":[{"flag":"-i, --ignore-environment","meaning":"Start with an empty environment before applying assignments."}],"keywords":["env","bare-os","coreutils"],"examples":[{"caption":"print environment","code":"env"},{"caption":"minimal env and run","code":"env -i PATH=/bin printf '%s' ok"},{"caption":"override for one command","code":"env VAR=value mycmd"}],"listCategory":"coreutils"},{"name":"exit","section":1,"title":"exit the shell or booter session","synopsis":["exit [status]"],"description":"When run as /bin/exit, requests the booter to end the session via ctx.requestBooterExit. Status defaults to 0.","options":[],"keywords":["exit","bare-os","coreutils"],"bareOsNotes":"Also available as a shell builtin with different wiring.","examples":[{"caption":"leave session with status","code":"exit 0"},{"caption":"from script","code":"/bin/exit 42"}],"listCategory":"coreutils"},{"name":"false","section":1,"title":"return false value","synopsis":["false [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of return false value. Full behavior is defined in packages/bare-os-coreutils/src/false.js.","options":[],"keywords":["false","bare-os","coreutils"],"examples":[{"caption":"force failure in pipeline tests","code":"false; echo $?"}],"listCategory":"coreutils"},{"name":"find","section":1,"title":"find files","synopsis":["find [PATH...] [EXPRESSION]"],"description":"Walks a directory tree with a small predicate set: -maxdepth, -mindepth, -name, -iname, -path, -type, -print0. Does not implement full POSIX find expression grammar.","options":[{"flag":"-name / -iname","meaning":"Base name glob match (case-sensitive / case-insensitive)"},{"flag":"-print0","meaning":"Separate paths with NUL (requires host stdout)"},{"flag":"-type f|d|l","meaning":"Restrict to file, directory, or symlink"}],"keywords":["find","directory","walk","search"],"bareOsNotes":"Expression syntax is a simplified subset.","examples":[{"caption":"files by name glob","code":"find . -name \"*.js\""},{"caption":"directories only","code":"find . -type d"},{"caption":"max depth","code":"find . -maxdepth 2 -type f"},{"caption":"skip top directory level (GNU-like -mindepth 2)","code":"find . -mindepth 2 -type f"},{"caption":"case-insensitive name","code":"find . -iname \"*.TXT\""}],"listCategory":"coreutils"},{"name":"getconf","section":1,"title":"get configuration values","synopsis":["getconf [-a] system_var"],"description":"Prints a fixed subset of POSIX-style limit names and values for Bare OS. There is no host sysconf path; constants match the documented JavaScript/VFS environment.","options":[{"flag":"-a","meaning":"Write every known variable (each name on one line, value on the next)"}],"keywords":["getconf","limits","PATH_MAX","POSIX","bare-os","coreutils"],"bareOsNotes":"Subset only; unknown names fail with exit status 1. See src/getconf.js for the name table.","examples":[{"caption":"path length limit","code":"getconf PATH_MAX"},{"caption":"list known names and values","code":"getconf -a"}],"listCategory":"coreutils"},{"name":"git-pear","section":1,"title":"Git-in-Pear hints","synopsis":["git-pear help"],"description":"Prints short documentation for git+pear remotes (gip-transport / gip-remote). See packages/bare-os-coreutils/src/git-pear.js.","options":[],"keywords":["git","pear","gip","bare-os"],"examples":[{"caption":"help","code":"git-pear help"}],"listCategory":"coreutils"},{"name":"grep","section":1,"title":"pattern matching utility","synopsis":["grep [-E|-F] [-i] [-v] [-w] [-n] [-c] [-l] [-q] [-s] [-H|-h] [-e pat] ... [-f file] ... [pattern] [file...]"],"description":"Searches input or files for lines matching a pattern. Uses JavaScript RegExp unless -F (fixed string). Not bit-identical to GNU grep.","options":[{"flag":"-E","meaning":"Extended regex (accepted; patterns use JS RegExp)"},{"flag":"-F","meaning":"Fixed string match"},{"flag":"-r, --recursive","meaning":"Recurse into directories (skips **`.git`**; max depth 64); with no file args, searches **`.`**"},{"flag":"-i","meaning":"Ignore case"},{"flag":"-v","meaning":"Invert match"},{"flag":"-w","meaning":"Match whole words (regex: \\b…\\b; fixed: non-alphanumeric boundaries)"},{"flag":"-n","meaning":"Prefix lines with line number"},{"flag":"-c","meaning":"Count matching lines only"},{"flag":"-l","meaning":"List files with matches"},{"flag":"-q","meaning":"Quiet (exit status only)"},{"flag":"-s","meaning":"Suppress error messages"},{"flag":"-H / -h","meaning":"Force / suppress filename prefix"},{"flag":"-e pat","meaning":"Specify pattern"},{"flag":"-f file","meaning":"Read patterns from file"},{"flag":"-A / -B / -C N","meaning":"Print after / before / both context lines around matches"},{"flag":"--color=never|always|auto","meaning":"Highlight matches (default never; auto uses TTY and respects NO_COLOR)"}],"keywords":["grep","search","regex","pattern","filter"],"seeAlso":[{"name":"sed","section":1},{"name":"awk","section":1}],"bareOsNotes":"UTF-16 strings and JS regex differ from strict POSIX/GNU.","examples":[{"caption":"recursive feel (grep each file)","code":"grep -n error *.log"},{"caption":"case insensitive","code":"grep -i todo NOTES.md"},{"caption":"invert (lines without)","code":"grep -v '^#' config"},{"caption":"fixed string (no regex)","code":"grep -F \"v1.0\" CHANGES"},{"caption":"count matches","code":"grep -c FAIL build.log"},{"caption":"only filenames","code":"grep -l main *.js"},{"caption":"multiple patterns","code":"grep -e foo -e bar file.txt"}],"listCategory":"coreutils"},{"name":"head","section":1,"title":"copy the first part of files","synopsis":["head [OPTION]... [OPERAND]..."],"description":"Prints the first part of each file. Supports -n for line count and -c for a byte count (UTF-8 byte-oriented).","options":[{"flag":"-n, --lines=NUM","meaning":"Print the first NUM lines (default 10)"},{"flag":"-c, --bytes=NUM","meaning":"Print the first NUM bytes"},{"flag":"-NUM","meaning":"Shorthand for -n NUM (e.g. head -5 file)"}],"keywords":["head","bare-os","coreutils"],"seeAlso":[{"name":"tail","section":1}],"examples":[{"caption":"first 10 lines","code":"head /etc/os-release"},{"caption":"first N lines","code":"head -n 50 big.log"},{"caption":"first bytes","code":"head -c 80 data.bin"},{"caption":"stdin","code":"cat long.txt | head"}],"listCategory":"coreutils"},{"name":"hdms","section":1,"title":"Hyperswarm distributed map store","synopsis":["hdms [OPTION]... [OPERAND]..."],"description":"Invokes ctx.runHdms when the booter provides HDMS integration; otherwise prints unavailable.","options":[],"keywords":["hdms","hyperswarm","map"],"bareOsNotes":"Optional booter capability.","examples":[{"caption":"when booter wires HDMS","code":"hdms ls /mnt"},{"caption":"otherwise","code":"# prints unavailable without ctx.runHdms"}],"listCategory":"coreutils"},{"name":"help","section":1,"title":"Bare OS help summary","synopsis":["help"],"description":"Prints a one-screen summary of shell builtins and /bin command names. Use man for long-form documentation.","options":[],"keywords":["help","summary","builtins","commands"],"seeAlso":[{"name":"man","section":1},{"name":"bare-os-shell","section":1}],"examples":[{"caption":"quick index","code":"help"},{"caption":"then deep dive","code":"man grep"}],"listCategory":"coreutils"},{"name":"hostname","section":1,"title":"set or print hostname","synopsis":["hostname [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of set or print hostname. Full behavior is defined in packages/bare-os-coreutils/src/hostname.js.","options":[],"keywords":["hostname","bare-os","coreutils"],"examples":[{"caption":"show host","code":"hostname"}],"listCategory":"coreutils"},{"name":"id","section":1,"title":"return user identity","synopsis":["id [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of return user identity. Full behavior is defined in packages/bare-os-coreutils/src/id.js.","options":[],"keywords":["id","bare-os","coreutils"],"examples":[{"caption":"who am I numerically","code":"id"}],"listCategory":"coreutils"},{"name":"jq","section":1,"title":"command-line JSON processor (jq language subset)","synopsis":["jq [-n] [-R] [-s] [-c] [-r] [-e] [-f file] filter [file...]","jq reads JSON (concatenated values or NDJSON-style streams) from files or stdin."],"description":"Runs a jq filter program against JSON values. The engine is vendored jqjs (pure JavaScript), not the C implementation at https://github.com/jqlang/jq — language coverage and edge cases differ.","options":[{"flag":"-n, --null-input","meaning":"Use null as the sole input (ignore file/stdin for input)"},{"flag":"-R, --raw-input","meaning":"Treat each line as a string instead of JSON"},{"flag":"-s, --slurp","meaning":"Read all inputs into one array; run the filter once"},{"flag":"-c, --compact-output","meaning":"Compact JSON on output"},{"flag":"-r, --raw-output","meaning":"Print strings without JSON quotes"},{"flag":"-e, --exit-status","meaning":"Set exit status from outputs (no output → 4; last false/null → 1)"},{"flag":"-f, --from-file","meaning":"Read filter program from file"}],"keywords":["jq","json","query","filter","jqjs"],"seeAlso":[{"name":"grep","section":1},{"name":"awk","section":1}],"bareOsNotes":"Engine: lib/jq-engine.js from @sscots/jqjs (mwh/jqjs). Missing vs C jq: try/catch, user-defined functions, recurse, many builtins, modules, full Unicode. See upstream jqjs README for the feature matrix.","examples":[{"caption":"pretty-print","code":"jq . data.json"},{"caption":"field","code":"jq .version package.json"},{"caption":"slurp array","code":"jq -s 'map(.x) | add' parts.jsonl"},{"caption":"compact","code":"jq -c '.[] | select(.ok)' items.json"}],"listCategory":"coreutils"},{"name":"ln","section":1,"title":"link files","synopsis":["ln [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of link files. Full behavior is defined in packages/bare-os-coreutils/src/ln.js.","options":[],"keywords":["ln","bare-os","coreutils"],"examples":[{"caption":"symlink","code":"ln -s target name"},{"caption":"hard link (if supported)","code":"ln file linkname"}],"listCategory":"coreutils"},{"name":"login","section":1,"title":"begin a session on the system","synopsis":["login [OPTION]... [OPERAND]..."],"description":"When invoked from /bin, behavior aligns with session identity hooks (see booter). Prefer the shell builtin for passphrase entry.","options":[],"keywords":["login","identity","passphrase"],"seeAlso":[{"name":"logout","section":1}],"examples":[{"caption":"unlock existing identity","code":"login my passphrase words here"},{"caption":"register new","code":"login --new first time passphrase"}],"listCategory":"coreutils"},{"name":"logout","section":1,"title":"end session (save vault)","synopsis":["logout [OPTION]... [OPERAND]..."],"description":"Ends session; may persist vault depending on booter and flags.","options":[],"keywords":["logout","session"],"seeAlso":[{"name":"login","section":1}],"examples":[{"caption":"end session","code":"logout"},{"caption":"save vault hint","code":"logout --save"}],"listCategory":"coreutils"},{"name":"logname","section":1,"title":"return the user's login name","synopsis":["logname [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of return the user's login name. Full behavior is defined in packages/bare-os-coreutils/src/logname.js.","options":[],"keywords":["logname","bare-os","coreutils"],"examples":[{"caption":"login name","code":"logname"}],"listCategory":"coreutils"},{"name":"ls","section":1,"title":"list directory contents","synopsis":["ls [-1al] [--color[=never|auto|always]] [FILE...]"],"description":"Lists directory contents. Long format shows mode, links, owner, group, size, mtime, and symlink targets. With color (default auto on a TTY), directories, symlinks, executables, and permission bits are highlighted.","options":[{"flag":"-a","meaning":"Include names starting with ."},{"flag":"-l","meaning":"Long listing"},{"flag":"-1","meaning":"One name per line (short format)"},{"flag":"--color[=never|auto|always]","meaning":"ANSI colors: never, auto (TTY only), or always; plain --color is auto"}],"environment":["NO_COLOR — disable color even when a TTY or --color=always"],"keywords":["ls","list","directory","dir"],"bareOsNotes":"Hides .bareos_empty marker like other tools.","examples":[{"caption":"long + hidden","code":"ls -la ~"},{"caption":"one per line","code":"ls -1 /bin | head"},{"caption":"multiple paths","code":"ls /bin /etc"}],"listCategory":"coreutils"},{"name":"man","section":1,"title":"display on-line manual pages","synopsis":["man [-k keyword] [-f name] [-l] [-w] [[section] name]","man reads /share/man/man.json on the system drive."],"description":"Displays manual pages from the merged JSON database. Section 1: /bin and git/shell pages. Section 7: handbook (man handbook) and developer guide (man devguide), merged at build from handbook/*.md and developer-guide/*.md.","options":[{"flag":"-k, --apropos","meaning":"Search keywords and titles (substring)"},{"flag":"-f, --whatis","meaning":"One-line description for exact name"},{"flag":"-l, --list","meaning":"List pages grouped by category (/bin, git/shell, handbook, developer guide), then alphabetically"},{"flag":"-w, --where, --path","meaning":"Print logical path to the manual database (/share/man/man.json)"}],"keywords":["man","manual","help","documentation","apropos","whatis","cheat","examples"],"environment":["MANWIDTH — wrap width (default 72, min 40)","NO_COLOR — disable bold headings on TTY","PAGER=bare-slice — insert section breaks in long pages (optional MAN_SLICE lines per chunk, default 24)"],"seeAlso":[{"name":"help","section":1},{"name":"bare-os-handbook","section":7},{"name":"bare-os-developer-guide","section":7}],"bareOsNotes":"No troff; no embedded DB fallback in v1.","examples":[{"caption":"open page","code":"man sed"},{"caption":"handbook TOC (section 7)","code":"man handbook"},{"caption":"handbook chapter by section","code":"man 7 handbook-01-introduction"},{"caption":"apropos","code":"man -k copy"},{"caption":"whatis","code":"man -f grep"},{"caption":"all pages","code":"man -l"},{"caption":"narrow terminal","code":"MANWIDTH=64 man awk"}],"listCategory":"coreutils"},{"name":"mkdir","section":1,"title":"make directories","synopsis":["mkdir [OPTION]... DIRECTORY..."],"description":"Creates directories using the VFS marker convention. **`-m MODE`** sets permission bits (octal) on **`.bareos_empty`**; **`lstat`** on the directory reports **`S_IFDIR`** with those bits (execute bits are implied for user/group/other when the corresponding read bit is set, so traversal still works).","options":[{"flag":"-p, --parents","meaning":"Create parent directories as needed."},{"flag":"-m MODE","meaning":"Directory mode (octal, e.g. **755** or **0755**)."}],"keywords":["mkdir","bare-os","coreutils"],"examples":[{"caption":"one dir","code":"mkdir proj"},{"caption":"parents","code":"mkdir -p a/b/c"},{"caption":"mode","code":"mkdir -m 700 private"}],"listCategory":"coreutils"},{"name":"mkfifo","section":1,"title":"make FIFO special files","synopsis":["mkfifo [OPTION]... [OPERAND]..."],"description":"FIFO special files are not implemented on Hyperdrive. The command reports failure.","options":[],"keywords":["mkfifo","bare-os","coreutils","stub"],"stub":true,"bareOsNotes":"Documented stub; no real pipes as kernel objects.","examples":[{"caption":"stub","code":"# FIFOs not on Hyperdrive — use shell pipelines"}],"listCategory":"coreutils"},{"name":"mktemp","section":1,"title":"create a temporary file or directory","synopsis":["mktemp [OPTION] [TEMPLATE]"],"description":"Creates a file or directory under /tmp (or absolute TEMPLATE). Replaces XXXXXX with random characters. See packages/bare-os-coreutils/src/mktemp.js.","options":[{"flag":"-d","meaning":"create a directory"}],"keywords":["mktemp","bare-os","coreutils"],"examples":[{"caption":"file","code":"mktemp tmp.XXXXXX"},{"caption":"dir","code":"mktemp -d dir.XXXXXX"}],"listCategory":"coreutils"},{"name":"mv","section":1,"title":"move or rename files","synopsis":["mv [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of move or rename files. Full behavior is defined in packages/bare-os-coreutils/src/mv.js.","options":[],"keywords":["mv","bare-os","coreutils"],"examples":[{"caption":"rename","code":"mv old.txt new.txt"},{"caption":"into dir","code":"mv *.txt ~/inbox/"}],"listCategory":"coreutils"},{"name":"nano","section":1,"title":"alias for edit — terminal file editor","synopsis":["nano [file]"],"description":"The /bin/nano script is identical to edit. In the default shell, the name nano is also an alias for edit. See edit(1) for behavior, key bindings, and requirements.","options":[],"keywords":["nano","edit","editor"],"bareOsNotes":"Same implementation as edit; see man edit.","examples":[{"caption":"open a file","code":"nano ~/.barerc"}],"listCategory":"coreutils"},{"name":"nl","section":1,"title":"line numbering utility","synopsis":["nl [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of line numbering utility. Full behavior is defined in packages/bare-os-coreutils/src/nl.js.","options":[],"keywords":["nl","bare-os","coreutils"],"examples":[{"caption":"number all lines","code":"nl README.md"}],"listCategory":"coreutils"},{"name":"od","section":1,"title":"octal dump","synopsis":["od [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of octal dump. Full behavior is defined in packages/bare-os-coreutils/src/od.js.","options":[],"keywords":["od","bare-os","coreutils"],"examples":[{"caption":"hex dump vibe","code":"od -c file.bin | head"}],"listCategory":"coreutils"},{"name":"pathchk","section":1,"title":"check pathname portability","synopsis":["pathchk [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of check pathname portability. Full behavior is defined in packages/bare-os-coreutils/src/pathchk.js.","options":[],"keywords":["pathchk","bare-os","coreutils"],"examples":[{"caption":"portable path check","code":"pathchk -p \"$HOME/file name\""}],"listCategory":"coreutils"},{"name":"printenv","section":1,"title":"print environment variables","synopsis":["printenv [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of print environment variables. Full behavior is defined in packages/bare-os-coreutils/src/printenv.js.","options":[],"keywords":["printenv","bare-os","coreutils"],"examples":[{"caption":"one variable","code":"printenv HOME"},{"caption":"all","code":"printenv"}],"listCategory":"coreutils"},{"name":"printf","section":1,"title":"format and print","synopsis":["printf [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of format and print. Full behavior is defined in packages/bare-os-coreutils/src/printf.js.","options":[],"keywords":["printf","bare-os","coreutils"],"examples":[{"caption":"format","code":"printf \"hex=%x dec=%d\\n\" 255 255"},{"caption":"no newline","code":"printf \"%s\" OK"}],"listCategory":"coreutils"},{"name":"pwd","section":1,"title":"return working directory name","synopsis":["pwd [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of return working directory name. Full behavior is defined in packages/bare-os-coreutils/src/pwd.js.","options":[],"keywords":["pwd","bare-os","coreutils"],"examples":[{"caption":"where am I","code":"pwd"}],"listCategory":"coreutils"},{"name":"readlink","section":1,"title":"print symbolic link targets","synopsis":["readlink [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of print symbolic link targets. Full behavior is defined in packages/bare-os-coreutils/src/readlink.js.","options":[],"keywords":["readlink","bare-os","coreutils"],"examples":[{"caption":"symlink target","code":"readlink ~/.config"}],"listCategory":"coreutils"},{"name":"rm","section":1,"title":"remove files","synopsis":["rm [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of remove files. Full behavior is defined in packages/bare-os-coreutils/src/rm.js.","options":[],"keywords":["rm","bare-os","coreutils"],"examples":[{"caption":"file","code":"rm tmp.txt"},{"caption":"tree","code":"rm -rf build/"}],"listCategory":"coreutils"},{"name":"rmdir","section":1,"title":"remove empty directories","synopsis":["rmdir [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of remove empty directories. Full behavior is defined in packages/bare-os-coreutils/src/rmdir.js.","options":[],"keywords":["rmdir","bare-os","coreutils"],"examples":[{"caption":"empty dir","code":"rmdir olddir"}],"listCategory":"coreutils"},{"name":"savevault","section":1,"title":"encrypt snapshot of personal drive","synopsis":["savevault [OPTION]... [OPERAND]..."],"description":"Encrypts a copy of the personal drive under /.bare/vault/ when identity services are available.","options":[],"keywords":["savevault","vault","encrypt","backup"],"seeAlso":[{"name":"login","section":1}],"examples":[{"caption":"snapshot encrypted vault","code":"savevault"}],"listCategory":"coreutils"},{"name":"sed","section":1,"title":"stream editor","synopsis":["sed [OPTION]... [OPERAND]..."],"description":"Stream editor with a subset of POSIX sed. Large engine is vendored in lib/sed-engine.js.","options":[],"keywords":["sed","stream","edit","substitute"],"seeAlso":[{"name":"awk","section":1},{"name":"grep","section":1}],"bareOsNotes":"JavaScript implementation; edge cases differ from GNU sed.","examples":[{"caption":"substitute first per line","code":"sed 's/foo/bar/' file.txt"},{"caption":"global per line","code":"sed 's/ //g' spaced.txt"},{"caption":"in-place (if supported)","code":"sed -i.bak 's/^/# /' f.cfg"},{"caption":"print line 5 only","code":"sed -n '5p' file"},{"caption":"delete blank lines","code":"sed '/^$/d' file"}],"listCategory":"coreutils"},{"name":"seq","section":1,"title":"print sequences of numbers","synopsis":["seq [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of print sequences of numbers. Full behavior is defined in packages/bare-os-coreutils/src/seq.js.","options":[],"keywords":["seq","bare-os","coreutils"],"examples":[{"caption":"1..10","code":"seq 1 10"},{"caption":"step","code":"seq 0 2 20"}],"listCategory":"coreutils"},{"name":"sleep","section":1,"title":"suspend execution for an interval","synopsis":["sleep [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of suspend execution for an interval. Full behavior is defined in packages/bare-os-coreutils/src/sleep.js.","options":[],"keywords":["sleep","bare-os","coreutils"],"examples":[{"caption":"pause seconds","code":"sleep 2"}],"listCategory":"coreutils"},{"name":"sort","section":1,"title":"sort lines","synopsis":["sort [OPTION]... [OPERAND]..."],"description":"Sorts lines from files or stdin. Supports numeric sort, reverse, unique consecutive lines, and case fold for sort keys.","options":[{"flag":"-n, --numeric-sort, -g","meaning":"Sort by leading numeric prefix"},{"flag":"-r, --reverse","meaning":"Reverse sort order"},{"flag":"-u, --unique","meaning":"Suppress duplicate lines after sorting"},{"flag":"-f, --ignore-case","meaning":"Fold case for ordering"},{"flag":"-t, --field-separator SEP","meaning":"Field delimiter for **`-k`** (use **\\t** for tab)"},{"flag":"-k, --key POS","meaning":"Sort by 1-based field **POS** or **START,END** (bare subset; blank-separated fields when **`-t`** omitted)"},{"flag":"-","meaning":"Operand reads stdin"}],"keywords":["sort","bare-os","coreutils"],"examples":[{"caption":"lexicographic","code":"sort names.txt"},{"caption":"numeric","code":"sort -n scores.txt"},{"caption":"unique","code":"sort -u tags.txt"}],"listCategory":"coreutils"},{"name":"stat","section":1,"title":"display file status","synopsis":["stat [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of display file status. Full behavior is defined in packages/bare-os-coreutils/src/stat.js.","options":[],"keywords":["stat","bare-os","coreutils"],"examples":[{"caption":"metadata","code":"stat ~/README.md"}],"listCategory":"coreutils"},{"name":"tail","section":1,"title":"copy the last part of a file","synopsis":["tail [OPTION]... [OPERAND]..."],"description":"Prints the last part of each file. Supports -n (line count, including +N to start at line N), -c (bytes, including +K to start at byte K), and -f/--follow for Hyperdrive-backed files. Follow mode uses vfs.watch when available (see BARE_OS_VFS_WATCH) and otherwise polls (BARE_OS_TAIL_F_POLL_MS, default 1000). For automated tests, BARE_OS_TAIL_F_MAX_ROUNDS limits poll iterations (unset = unlimited). Stdin follow is not supported (shell stdin is a captured string). Following multiple files at once is not supported.","options":[{"flag":"-n, --lines=[+]NUM","meaning":"Last NUM lines, or from line NUM onward if +NUM"},{"flag":"-c, --bytes=[+]NUM","meaning":"Last NUM bytes, or from byte NUM onward if +NUM"},{"flag":"-f, --follow","meaning":"Print appended data as the file grows (one file only)"},{"flag":"-F","meaning":"Same as -f (retry-on-truncate not distinct on Bare OS)"}],"environment":["BARE_OS_TAIL_F_POLL_MS — milliseconds between polls when watch is unavailable or capped","BARE_OS_TAIL_F_MAX_ROUNDS — max poll cycles after initial output (empty = unlimited)","BARE_OS_VFS_WATCH=0 — disable Hyperdrive watch; tail -f uses polling only"],"keywords":["tail","follow","log","bare-os","coreutils"],"seeAlso":[{"name":"head","section":1}],"examples":[{"caption":"last lines","code":"tail -n 20 app.log"},{"caption":"follow a log","code":"tail -f /var/log/app.log"},{"caption":"last bytes","code":"tail -c 512 image.bin"}],"listCategory":"coreutils"},{"name":"tee","section":1,"title":"duplicate standard input","synopsis":["tee [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of duplicate standard input. Full behavior is defined in packages/bare-os-coreutils/src/tee.js.","options":[],"keywords":["tee","bare-os","coreutils"],"examples":[{"caption":"copy stdout to file","code":"cat x | tee copy.txt | wc -l"}],"listCategory":"coreutils"},{"name":"test","section":1,"title":"evaluate a condition","synopsis":["test [OPTION]... [OPERAND]..."],"description":"Evaluates file tests, string equality, and signed integer comparisons. Subset of POSIX test(1).","options":[{"flag":"-eq -ne -lt -le -gt -ge","meaning":"Integer comparisons (decimal)"},{"flag":"-f -d -e -a","meaning":"File type / existence (stat)"},{"flag":"-h -L","meaning":"Symlink (lstat)"},{"flag":"-z -n","meaning":"String empty / non-empty"}],"keywords":["test","bare-os","coreutils"],"examples":[{"caption":"file exists","code":"test -f ~/.barerc && echo yes"},{"caption":"directory","code":"test -d /home/user"},{"caption":"string equal","code":"test \"$USER\" = guest"}],"listCategory":"coreutils"},{"name":"theme","section":1,"title":"switch Bare OS color theme","synopsis":["theme [list|current|set |apply]"],"description":"Lists bundled theme presets, shows the active BARE_OS_THEME, writes theme to ~/.barerc and reapplies colors (when the booter provides bareOsApplyTheme), or reapplies the current theme without editing the file.","options":[],"keywords":["theme","colors","LS_COLORS","prompt"],"bareOsNotes":"Requires ctx.bareOsApplyTheme for set/apply to refresh env; list/current work with static preset names.","examples":[{"caption":"list presets","code":"theme list"},{"caption":"switch to Nord palette","code":"theme set nord"},{"caption":"re-apply after manual env edits","code":"theme apply"}],"listCategory":"coreutils"},{"name":"time","section":1,"title":"time a simple command","synopsis":["time [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of time a simple command. Full behavior is defined in packages/bare-os-coreutils/src/time.js.","options":[],"keywords":["time","bare-os","coreutils"],"examples":[{"caption":"wall time a command","code":"time sort big.txt"}],"listCategory":"coreutils"},{"name":"touch","section":1,"title":"change file timestamps or create files","synopsis":["touch [OPTION]... FILE..."],"description":"Creates missing files (empty) or updates timestamps via **`vfs.writeFile`** with explicit **`mtimeMs`** / **`ctimeMs`** in metadata. Bare has no separate atime; **`-a`** updates **ctime** only and leaves **mtime** unchanged unless a time is given; **`-m`** updates **mtime** only and leaves **ctime** unchanged unless a time is given. Default (neither **`-a`** nor **`-m`**) updates both to the chosen time or now.","options":[{"flag":"-a","meaning":"Change access time only (approximated: **ctime** only; **mtime** unchanged)."},{"flag":"-m","meaning":"Change modification time only (**mtime**; **ctime** unchanged unless a time is given)."},{"flag":"-d, --date","meaning":"Use parsed time (**`Date.parse`**; **`@seconds`** for Unix seconds)."},{"flag":"-r, --reference","meaning":"Use **mtime** of **FILE** (last **`-d`** / **`-r`** wins)."}],"keywords":["touch","bare-os","coreutils"],"examples":[{"caption":"create empty","code":"touch newfile"},{"caption":"set time","code":"touch -d '@315532800' old.txt"},{"caption":"match another file","code":"touch -r template.txt copy.txt"}],"listCategory":"coreutils"},{"name":"tr","section":1,"title":"translate or delete characters","synopsis":["tr [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of translate or delete characters. Full behavior is defined in packages/bare-os-coreutils/src/tr.js.","options":[],"keywords":["tr","bare-os","coreutils"],"examples":[{"caption":"uppercase","code":"echo hi | tr 'a-z' 'A-Z'"},{"caption":"delete chars","code":"tr -d '\\r' < win.txt"}],"listCategory":"coreutils"},{"name":"true","section":1,"title":"return true value","synopsis":["true [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of return true value. Full behavior is defined in packages/bare-os-coreutils/src/true.js.","options":[],"keywords":["true","bare-os","coreutils"],"examples":[{"caption":"always success","code":"true && echo ok"}],"listCategory":"coreutils"},{"name":"tty","section":1,"title":"return user's terminal name","synopsis":["tty [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of return user's terminal name. Full behavior is defined in packages/bare-os-coreutils/src/tty.js.","options":[],"keywords":["tty","bare-os","coreutils"],"examples":[{"caption":"am I a tty","code":"tty"}],"listCategory":"coreutils"},{"name":"uname","section":1,"title":"return operating system name","synopsis":["uname [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of return operating system name. Full behavior is defined in packages/bare-os-coreutils/src/uname.js.","options":[],"keywords":["uname","bare-os","coreutils"],"examples":[{"caption":"kernel-ish info","code":"uname -a"}],"listCategory":"coreutils"},{"name":"wc","section":1,"title":"word, line, and byte or character count","synopsis":["wc [OPTION]... [OPERAND]..."],"description":"Counts newlines, words, and bytes in each file. With no options, prints lines, words, and bytes. Line count is newline count (POSIX).","options":[{"flag":"-l, --lines","meaning":"Print newline counts"},{"flag":"-w, --words","meaning":"Print word counts"},{"flag":"-c, --bytes, -m","meaning":"Print byte counts"},{"flag":"-","meaning":"Operand reads stdin"}],"keywords":["wc","bare-os","coreutils"],"examples":[{"caption":"lines words bytes","code":"wc README.md"},{"caption":"lines only","code":"wc -l *.txt"},{"caption":"stdin","code":"cat f | wc -l"}],"listCategory":"coreutils"},{"name":"which","section":1,"title":"locate a command","synopsis":["which [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of locate a command. Full behavior is defined in packages/bare-os-coreutils/src/which.js.","options":[],"keywords":["which","bare-os","coreutils"],"examples":[{"caption":"resolve on PATH","code":"which ls"}],"listCategory":"coreutils"},{"name":"whoami","section":1,"title":"display effective user ID","synopsis":["whoami [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of display effective user ID. Full behavior is defined in packages/bare-os-coreutils/src/whoami.js.","options":[],"keywords":["whoami","bare-os","coreutils"],"examples":[{"caption":"effective user","code":"whoami"}],"listCategory":"coreutils"},{"name":"xargs","section":1,"title":"construct argument lists and invoke utility","synopsis":["xargs [-0] [-I repl] [-n maxargs] [--] [utility [argument ...]]"],"description":"Reads stdin, splits into words (or null-terminated records with -0), and invokes the utility via ctx.runBinCommand in batches. Enforces fixed limits on stdin size, token count, arguments per run, and total invocations.","options":[{"flag":"-0, --null","meaning":"Input items are separated by null bytes instead of whitespace"},{"flag":"-n maxargs, --max-args maxargs","meaning":"Use at most maxargs arguments from stdin per utility invocation (capped at 128)"},{"flag":"-I repl, -irepl","meaning":"Replace repl in utility arguments with each input item (implies -n 1 unless -n is set)"}],"keywords":["xargs","arguments","bare-os","coreutils"],"bareOsNotes":"No host fork; subset of POSIX/GNU xargs. See src/xargs.js for numeric limits.","examples":[{"caption":"pass lines as arguments","code":"printf 'a\\nb\\n' | xargs echo"},{"caption":"one argument per run","code":"printf 'a\\nb\\n' | xargs -n1 echo"},{"caption":"workaround for complex scripts","code":"# for f in *.txt; do grep -l foo $f; done"}],"listCategory":"coreutils"},{"name":"bare-os-ctx-bare","section":7,"title":"ctx.bare library and drive bundles","synopsis":["# reference — not a shell command"],"description":"Documents BARE_OS_BARE_MODULES and BARE_OS_BARE_DRIVE_BUNDLES for the booter ctx.bare registry. In-image scripts (AsyncFunction) use ctx.bare. instead of import(). Keys come from host dynamic import of packages listed in packages/bare-os-booter/lib/bare-module-manifest.json, then optional merge from trusted IIFE bundles under /lib/bare/bundles/ on the system image (see manifest.json there). Set BARE_OS_BARE_MODULES=0 to omit ctx.bare entirely. Set BARE_OS_BARE_DRIVE_BUNDLES=0 to skip executing drive bundles (host imports only). Rebuild bundles with npm run build -w bare-os-bare-libs.","options":[],"keywords":["BARE_OS_BARE_MODULES","BARE_OS_BARE_DRIVE_BUNDLES","ctx.bare","bare-module-manifest","bare-os-bare-libs"],"environment":["BARE_OS_BARE_MODULES — set to 0 or false to disable ctx.bare (hardened sessions).","BARE_OS_BARE_DRIVE_BUNDLES — set to 0 or false to skip loading /lib/bare/bundles/*.js into ctx.bare."],"seeAlso":[{"name":"bare-os-developer-guide","section":7}],"bareOsNotes":"See developer-guide/05-modules-and-imports.md and 12-bare-modules-and-pear-ecosystem.md.","examples":[],"listCategory":"extra"},{"name":"bare-os-shell","section":1,"title":"Bare OS interactive shell builtins","synopsis":["# builtins only — no full POSIX sh grammar"],"description":"The line-at-a-time shell supports aliases, simple pipelines (simulated), redirection, and the builtins below. Compound commands (if, for, while) are not available.","options":[],"aliases":["sh-builtins"],"keywords":["shell","builtin","cd","export","alias","bare-os-shell","sh-builtins"],"builtins":[{"name":"alias","synopsis":["alias","alias name=value ...","unalias name ..."],"description":"Define or list command aliases. unalias removes definitions."},{"name":"cd","synopsis":["cd [DIR]"],"description":"Change working directory via vfs.chdir; default is HOME."},{"name":"export","synopsis":["export NAME=value ..."],"description":"Set environment variables visible to child /bin invocations."},{"name":"unset","synopsis":["unset NAME ..."],"description":"Remove variables; readonly names cannot be unset."},{"name":"readonly","synopsis":["readonly NAME[=value] ..."],"description":"Mark variables read-only."},{"name":"umask","synopsis":["umask [octal]"],"description":"Show or set shell file creation mask (stored in env UMASK)."},{"name":"command","synopsis":["command -v|-V NAME","command ARGV..."],"description":"Resolve or run a command without using shell functions (none) or aliases for -v/-V."},{"name":"type","synopsis":["type NAME"],"description":"Report whether NAME is a builtin or a path under PATH."},{"name":"login / logout","synopsis":["login [--new] passphrase...","logout [--save]"],"description":"Identity unlock/register and session teardown; require booter hooks."},{"name":":","synopsis":[":"],"description":"No-op builtin."},{"name":"exit","synopsis":["exit [n]"],"description":"Request booter exit with status n (builtin path)."}],"seeAlso":[{"name":"help","section":1},{"name":"man","section":1}],"bareOsNotes":"Pipelines do not use OS pipes; see handbook ch.4 and ch.9.","examples":[{"caption":"pipeline (simulated)","code":"ls -1 /bin | grep man"},{"caption":"redirect out","code":"echo hi > ~/hello.txt"},{"caption":"append","code":"date >> ~/log.txt"},{"caption":"alias + use","code":"alias ll='ls -la'\nll ~"},{"caption":"export for children","code":"export EDITOR=ed\nman ls"},{"caption":"temp var for one command","code":"PATH=/bin man which"}],"listCategory":"extra"},{"name":"systemctl","section":1,"title":"bare-initd service control (systemd-like subset)","synopsis":["systemctl list|list-units","systemctl status [UNIT] [--lines N]","systemctl logs UNIT [--lines N]","systemctl start|stop|restart UNIT","systemctl enable|disable UNIT","systemctl is-enabled UNIT","systemctl is-active UNIT","journalctl -u UNIT [--lines N]"],"description":"Lists and manages session-scoped bare-initd units (kernel-logger, bare-cron, …). Implemented by the booter (kernel-runner); /bin stubs exist for PATH and man(1). enable/disable toggle the personal-drive preset file ~/.config/bare-os/initd/disabled.txt for future boots in the same image. is-enabled reports enabled or disabled; is-active reports active vs inactive from runtime phase (exit 0 vs 3). Logs live under /var/log/bare-os/ when the unit defines a logPath. The legacy name bare-initctl is still accepted by the booter as an alias.","options":[{"flag":"--lines N","meaning":"Tail N lines from the unit log (status, logs, journalctl)"}],"aliases":["bare-initctl"],"keywords":["bare-initd","initctl","service","supervisor","cron","systemd"],"bareOsNotes":"journalctl only supports -u UNIT and optional --lines / -n. Unknown systemd verbs are not implemented.","seeAlso":[{"name":"crontab","section":1},{"name":"bare-os-shell","section":1}],"examples":[{"caption":"list units","code":"systemctl list-units"},{"caption":"restart scheduler","code":"systemctl restart bare-cron"},{"caption":"tail cron errors","code":"journalctl -u bare-cron --lines 20"}],"listCategory":"extra"},{"name":"curl","section":1,"title":"transfer a URL (Fetch-based client, not libcurl)","synopsis":["curl [options] URL...","curl uses Fetch in the booter (Node fetch or bare-fetch on bare-http1/bare-https), not libcurl."],"description":"HTTP/HTTPS client delegated from the booter. Subset of curl(1) flags; networking is WHATWG Fetch, not https://curl.se libcurl. See options and exitStatus for supported behavior; ../bare-os-booter/CLI_PARITY.md lists gaps vs full curl.","options":[{"flag":"-X, --request METHOD","meaning":"HTTP method"},{"flag":"-H, --header LINE","meaning":"Request header (repeatable)"},{"flag":"-A, --user-agent STRING","meaning":"Set User-Agent (default curl/VERSION-style string; last -A or -H User-Agent on the command line wins)"},{"flag":"-d, --data / --data-* / --json","meaning":"Request body (POST by default when present)"},{"flag":"-o, --output FILE","meaning":"Write response to VFS path; multiple URLs append .0, .1, …"},{"flag":"-O, --remote-name","meaning":"Write each URL to a local name from the URL path (basename); cannot combine with -o"},{"flag":"-T, --upload-file PATH","meaning":"PUT file body from VFS"},{"flag":"-I, --head","meaning":"HEAD request; with -L, uses HEAD then GET after redirects (curl semantics; see bareOsNotes)"},{"flag":"-i, --include","meaning":"Include response headers in output (non-HEAD)"},{"flag":"-L, --location","meaning":"Follow redirects (GET/POST use fetch follow; -I -L uses manual hops)"},{"flag":"-f, --fail","meaning":"Exit 22 on HTTP 4xx/5xx"},{"flag":"-s, --silent","meaning":"No progress/error to stderr (unless -S)"},{"flag":"-S, --show-error","meaning":"With -s, still show errors on stderr"},{"flag":"-v, --verbose","meaning":"Trace request/response headers to stderr"},{"flag":"-u, --user USER[:PASS]","meaning":"HTTP Basic Authorization"},{"flag":"-m, --max-time SECONDS","meaning":"Abort whole request after SECONDS (AbortSignal); not a separate connect timeout"},{"flag":"-w, --write-out FORMAT","meaning":"%{http_code}, %{url_effective}, %{size_download}, %{num_redirects} (num_redirects counts 3xx hops only for -I -L)"},{"flag":"-V, --version / -h, --help","meaning":"Version string and short usage"}],"keywords":["curl","http","https","fetch","download"],"bareOsNotes":"Not libcurl; implementation is packages/bare-os-booter/lib/curl-cli.js over global fetch (bare-fetch on Pear/Bare). Default User-Agent matches curl/VERSION form. Options and URLs may be interleaved. Host-style URLs without a scheme get http://; protocol-relative //host gets https://. Allowed URL schemes after normalization: http(s), data:, file://. For -I -L, HEAD is sent first; after a redirect, GET is used on the next URL (bare-fetch with redirect: follow keeps HEAD on every hop, so this path is manual). %{num_redirects} in -w reflects that manual redirect count only when -I and -L are both set.","exitStatus":["0 — success","1 — no fetch implementation","2 — bad usage or unknown option","7 — network or fetch failure","22 — HTTP error with -f","26 — cannot read upload file (-T)"],"seeAlso":[{"name":"git","section":1},{"name":"jq","section":1},{"name":"wget","section":1}],"listCategory":"extra"},{"name":"git","section":1,"title":"Bare OS git front-end (isomorphic-git)","synopsis":["git [-C dir] [ARGUMENTS...]"],"description":"Runs isomorphic-git against the VFS-backed adapter. Remote HTTP(S) uses BARE_OS_GIT_HTTP when set; otherwise Pear bare module fetch.","options":[{"flag":"-C dir","meaning":"Run as if git was started in dir"}],"environment":["BARE_OS_GIT_HTTP — optional fetch implementation for remotes","GIT_* — standard hints where supported"],"keywords":["git","version control","repository","clone","commit","isomorphic-git"],"bareOsNotes":"Not a separate /bin script; booter delegates argv[0]=git to git-cli.js.","seeAlso":[{"name":"bare-os-shell","section":1}],"examples":[{"caption":"new repo","code":"git init -C ~/myrepo"},{"caption":"status","code":"git -C ~/myrepo status"},{"caption":"clone over HTTP (needs remote + fetch)","code":"git clone https://example.com/repo.git ~/work/repo"},{"caption":"config local","code":"git -C ~/myrepo config user.email \"you@example.com\""},{"caption":"log one line","code":"git -C ~/myrepo log --oneline -5"}],"listCategory":"extra"},{"name":"wget","section":1,"title":"non-interactive network download (Fetch-based, not GNU wget2)","synopsis":["wget [options] URL...","wget is implemented in the booter with the Fetch API (Node fetch or bare-fetch), not the C GNU wget2 tree."],"description":"Downloads resources over HTTP or HTTPS into the VFS. Bare OS does not ship GNU wget or wget2 (C); this command is a small compatibility-oriented subset built on JavaScript fetch. It is delegated from the booter (like curl and git), not loaded from a /bin script on the system drive. Full flag matrix: ../bare-os-booter/CLI_PARITY.md.","options":[{"flag":"-O, --output-document FILE","meaning":"Write the body to FILE; use - for stdout. Only one URL allowed."},{"flag":"-P, --directory-prefix DIR","meaning":"Save under DIR using a name derived from the URL (last path segment, or index.html if the path ends with /)"},{"flag":"-q, --quiet","meaning":"Suppress non-error messages on stderr (saved path lines)"},{"flag":"-c, --continue","meaning":"Resume: if the output file exists, send Range: bytes=-; 206 responses are appended. Cannot use with -O -. If the server returns 416, the download is skipped for that URL (treated as already complete)."},{"flag":"-U, --user-agent STRING","meaning":"Set User-Agent (default Wget/VERSION (linux-gnu)-style when -U and --header User-Agent are absent)"},{"flag":"-T, --timeout SECONDS","meaning":"Abort the request after SECONDS (AbortController); whole-request timer, not connect-only"},{"flag":"--header LINE","meaning":"Extra header Name: value (repeatable). If you set Range, -c will not add another."},{"flag":"--post-data STRING","meaning":"POST body (sets method POST; default Content-Type application/x-www-form-urlencoded)"},{"flag":"--post-file PATH","meaning":"POST body read from a file on the VFS"},{"flag":"-V, --version","meaning":"Print Bare OS wget version string"},{"flag":"-h, --help","meaning":"Short usage"}],"environment":[],"keywords":["wget","download","http","https","fetch","mirror"],"bareOsNotes":"Not GNU wget2; packages/bare-os-booter/lib/wget-cli.js. Default User-Agent matches GNU wget-style Wget/VERSION (linux-gnu). -U overrides; --header User-Agent is used if present unless -U is set. Options and URLs may be interleaved; short options can be clustered (e.g. -qO-, -T30, -c). Host-style URLs without a scheme get http://; //host gets https://. Fetch follows redirects by default (unlike wget without --max-redirect, behavior may differ from GNU wget). No recursive retrieval, FTP, or WARC. Cannot combine -O and -P. Tests may set ctx.httpFetch.","seeAlso":[{"name":"curl","section":1},{"name":"git","section":1}],"examples":[{"caption":"save with default name in cwd","code":"wget https://example.com/README"},{"caption":"choose output path","code":"wget -O ~/page.html https://example.com/"},{"caption":"directory prefix","code":"wget -P ~/dl https://example.com/a/b.bin"},{"caption":"stdout","code":"wget -O - -q https://example.com/robots.txt"},{"caption":"resume partial file","code":"wget -c -O ~/big.bin https://example.com/big.bin"}],"exitStatus":["0 — success","1 — generic error (reserved)","2 — bad usage or options","3 — file I/O error (e.g. --post-file unreadable)","4 — network failure or no fetch implementation","8 — HTTP 4xx/5xx response"],"listCategory":"extra"},{"name":"bare-os-handbook","section":7,"title":"Bare OS handbook — table of contents and reading order","synopsis":["man 7 bare-os-handbook","Handbook chapter (plain text from handbook/README.md)"],"description":"BARE OPERATING SYSTEM — HANDBOOK\n\nWelcome. This handbook is the narrative companion to the repo: it explains _why_ the pieces exist, _how_ they connect, and _what_ to run when things go wrong. For an exhaustive file-by-file inventory, keep DOCUMENTATION.md <../DOCUMENTATION.md> open alongside—it is the closest thing to a generated map of every source path.\n\nThis project is experimental research software: a distributed system image living in Hyperdrive, discovered over Hyperswarm, executed by Bare/Pear apps. It is not a production OS.\n\nWHO THIS IS FOR\n\n- You want a mental model of seeder vs booter vs kernel vs /bin.\n- You need diagrams of data flow and trust boundaries.\n- You are extending coreutils, VFS, identity, HDMS, or initd services.\n\nREADING ORDER\n\n| Chapter | Topic |\n| 01 — Introduction <01-introduction.md> | Goals, vocabulary, Holepunch stack |\n| 02 — Blueprints <02-blueprints.md> | Layered architecture, trust, diagrams |\n| 03 — Protocol and disk <03-protocol-and-disk.md> | MBR, swarm, Protomux, SwarmDisk |\n| 04 — The booter runtime <04-the-booter-runtime.md> | ctx, VFS, shell, kernel runner, initd, cron, REPL |\n| 05 — Identity, vault, HDMS <05-identity-vault-and-hdms.md> | Guest vs user, /.bare/account, extra drives |\n| 06 — Kernel and binaries <06-kernel-and-binaries.md> | /boot/init.js, coreutils catalog |\n| 07 — Operations and development <07-operations-and-development.md> | Env vars, npm scripts, CI, Pear, troubleshooting |\n| 08 — Git on Bare OS <08-git-on-bare-os.md> | isomorphic-git, VFS fs adapter, HTTP modes |\n| 09 — POSIX utilities, shell, VFS <09-posix-utilities-shell-and-vfs.md> | XCU-style /bin, sed/awk, shell \\\\;/&&/ | | **, getconf/xargs subsets, stubs, divergence from Issue 7 |\n| 10 — Manual pages and online help <10-manpages-and-online-help.md> | man(1), /share/man/man.json, schema, build, relationship to help |\n\nCompanion — developer guide (how to write run(ctx, argv) / start(ctx), extend /bin, testing, Pear workflows): developer-guide/README.md <../developer-guide/README.md> — includes ch.11 — Kernel + Pear cookbook <../developer-guide/11-kernel-pear-cookbook.md> and ch.12 — Bare modules and Pear ecosystem <../developer-guide/12-bare-modules-and-pear-ecosystem.md> (ctx.bare, drive bundles).\n\nctx API changelog: packages/bare-os-booter/CHANGELOG.md <../packages/bare-os-booter/CHANGELOG.md>.\n\nPACKAGE READMES (QUICK LINKS)\n\n- bare-os-protocol <../packages/bare-os-protocol/README.md>\n- bare-os-bare-libs <../packages/bare-os-bare-libs/README.md>\n- bare-os-coreutils <../packages/bare-os-coreutils/README.md>\n- bare-os-seeder <../packages/bare-os-seeder/README.md>\n- bare-os-booter <../packages/bare-os-booter/README.md>\n- kernel <../kernel/README.md>\n- scripts <../scripts/README.md>\n\nROOT README\n\nThe top-level README.md <../README.md> is the short runbook (install, test, pear run, guest identity). Start there if you only need commands.\n\n_License: Apache-2.0 — see LICENSE <../LICENSE>._","descriptionMode":"preserve","options":[],"keywords":["handbook","bare-os","documentation","narrative","chapter","bare","os","table","contents","and","reading","order"],"seeAlso":[{"name":"handbook-01-introduction","section":7},{"name":"man","section":1}],"bareOsNotes":"Generated at build time from handbook/README.md. Diagrams in ```mermaid blocks are omitted; open the Markdown in the repo for figures.","aliases":["handbook","bare-os-handbook-index"],"listCategory":"handbook"},{"name":"handbook-01-introduction","section":7,"title":"Chapter 1 — Introduction: what “Bare OS” is","synopsis":["man 7 handbook-01-introduction","Handbook chapter (plain text from handbook/01-introduction.md)"],"description":"CHAPTER 1 — INTRODUCTION: WHAT “BARE OS” IS\n\nIf you have only a minute: Bare operating system is a tiny Unix-flavored environment whose root filesystem is a Hyperdrive replicated from peers. A seeder publishes that drive and a 512-byte MBR over Hyperswarm; a booter joins the swarm, downloads the image, mounts a second Hyperdrive for per-user mutable state, and runs JavaScript “kernel” and /bin scripts inside a Bare or Node runtime.\n\nThe rest of this chapter sets vocabulary straight—without it, the architecture diagrams in Chapter 2 <02-blueprints.md> will not stick.\n\nTHE PROBLEM THIS PROJECT EXPLORES\n\nTraditional OS images live on block devices or tarball layers. Here, the image is a Merkle tree you can address by key and replicate live. Peers do not hand you a .iso; they help you fill in the same Hyperdrive from the same discovery key.\n\nThat raises three design questions this repo answers in code:\n\n1. Discovery — How does a fresh node find _someone_ who has block 0 (the MBR) and the drive root?\n2. Separation of concerns — What is immutable-ish OS vs mutable per-device home?\n3. Execution model — What runs in the host process vs what is “inside” the simulated POSIX surface?\n\nBare OS picks: one swarm topic for the project, Protomux channels for control + replication, two Hyperdrives (system + personal), and AsyncFunction-loaded JS for kernel and utilities.\n\nKEY VOCABULARY\n\n| Term | Meaning here |\n| System drive | Hyperdrive containing /boot/init.js, /bin, /etc — replicated from the seeder image |\n| Personal drive | Separate Hyperdrive (Corestore namespace) for $HOME, /.bare, cron, logs |\n| MBR | 512 bytes: magic BIOS + embedded Hyperdrive public keys (primary + optional failover) |\n| Kernel | /boot/init.js — async function start(ctx); not a microkernel, a session loop |\n| /bin | Small JS programs (async function run(ctx, argv)) built from bare-os-coreutils — includes a TTY editor (edit, nano) and usual POSIX-style tools |\n| VFS | Booter-provided path layer: routes paths under $HOME to the personal drive, else system |\n| ctx | Context object passed to kernel and commands: vfs, console, execLine, identity hooks, etc. |\n| Guest | Default session before login — predictable HOME=/home/guest, no Ed25519 identity |\n| HDMS | “Hyperdrive management” — optional extra drives mounted under /mnt after unlock |\n\nWHY HYPERDRIVE AND HYPERSWARM\n\nHyperdrive gives you a single-writer (per key) log-backed filesystem with deterministic reads and sparse replication—good for an OS tree that many nodes can share.\n\nHyperswarm gives you topic-based and discovery-key-based peer finding. The seeder joins both the bare-os-v1 topic (so booters find _some_ peer) and the drive discovery key (so Hyperdrive replication completes).\n\nYou do not need to agree with every product choice to read the code: the handbook describes what the repo does, not whether it is the only way to build a P2P OS.\n\nRELATIONSHIP TO PEAR AND BARE\n\n- Bare is a minimal JavaScript runtime used by Pear apps.\n- Both seeder and booter are Pear applications (pear field in package.json) and can run under node index.js for development.\n- brittle-bare vs brittle-node split in tests reflects native addons (e.g. identity crypto) that only load on Bare.\n\nWHERE TO GO NEXT\n\n- Big picture: Chapter 2 — Blueprints <02-blueprints.md>\n- Wire protocol: Chapter 3 <03-protocol-and-disk.md>\n- Day-to-day hacking: Chapter 7 <07-operations-and-development.md>\n\n← Handbook home · Next: Blueprints → <02-blueprints.md>","descriptionMode":"preserve","options":[],"keywords":["handbook","bare-os","documentation","narrative","chapter","01","introduction","what","bare"],"seeAlso":[{"name":"handbook-02-blueprints","section":7},{"name":"bare-os-handbook","section":7},{"name":"man","section":1}],"bareOsNotes":"Generated at build time from handbook/01-introduction.md. Diagrams in ```mermaid blocks are omitted; open the Markdown in the repo for figures.","listCategory":"handbook"},{"name":"handbook-02-blueprints","section":7,"title":"Chapter 2 — Blueprints: architecture and trust","synopsis":["man 7 handbook-02-blueprints","Handbook chapter (plain text from handbook/02-blueprints.md)"],"description":"CHAPTER 2 — BLUEPRINTS: ARCHITECTURE AND TRUST\n\nThis chapter is the aerial view: boxes, arrows, and what is allowed to trust what. Implementation details live in later chapters.\n\n1. TWO APPLICATIONS, ONE PROTOCOL\n\n- The seeder is the publisher of the OS image (plus MBR in a small RAM map).\n- The booter is a consumer that refuses to invent a local copy: it must see peers.\n\n2. TWO DRIVES ON THE BOOTER\n\nTrust model (pragmatic):\n\n- System drive content is whatever replicated from the swarm matching the MBR keys. In dev you treat the seeder as trusted; in the wild this is “who you peer with.”\n- Personal drive is your namespace (Corestore bare-os-personal-v1). It holds secrets, cron, dotfiles, HDMS registry, vault snapshots.\n\n3. PROTOCOL, MBR, AND DISCOVERY\n\nThe shared package bare-os-protocol pins:\n\n- TOPIC_STRING === 'bare-os-v1'\n- topicKey() = crypto.hash(b4a.from(TOPIC_STRING))\n- MBR layout: 512 bytes, magic BIOS, primary key at offset 8, optional failover keys at 40 and 72\n\nMBR layout (512 bytes, see bare-os-protocol/constants.js):\n\n- Bytes 0–3: BIOS magic\n- Bytes 8–39: primary system Hyperdrive public key\n- Bytes 40–71, 72–103: optional additional keys\n\nProtomux channel bare-os-v1 carries:\n\n- Block read requests (MBR and any indexed RAM the seeder exposes)\n- Hyperdrive replication on the same socket\n- Stubs for gossip, search, RPC (see packages/bare-os-protocol/lib/channel.js)\n\n4. EXECUTION STACK INSIDE THE BOOTER\n\nKernel and /bin scripts are not separate processes. They are AsyncFunction closures in the same JS realm as the booter, with a synthetic ctx instead of syscalls.\n\n5. SERVICES AFTER THE CONSOLE EXISTS\n\nstopBareInitd() runs from REPL session cleanup so timers do not leak across session restarts.\n\n6. IDENTITY STATES\n\n- Guest: fixed HOME=/home/guest, read-oriented personal tree policy for some operations.\n- Unlocked: HOME under /home/, HDMS can attach writable drives, crontab install/remove allowed.\n\n7. WHAT IS _NOT_ HERE (BOUNDARY)\n\n- No hardware kernel, no MMU, no ELF loader for native /bin.\n- No container cgroup isolation—commands are JS with full host capability of the Pear/Bare process.\n- Future: stronger isolation would compose Bare workers, Pear runtime isolates, or bare-kit-style embeds; the stock ctx.bareOsSandboxRunScript hook is a documented placeholder until then (see developer guide security chapter).\n- No global consensus: two booters can diverge if they replicate different forks of the same discovery key (Hyperdrive versioning is a separate concern).\n\n← Introduction <01-introduction.md> · Handbook home · Next: Protocol and disk → <03-protocol-and-disk.md>","descriptionMode":"preserve","options":[],"keywords":["handbook","bare-os","documentation","narrative","chapter","02","blueprints","architecture","and","trust"],"seeAlso":[{"name":"handbook-03-protocol-and-disk","section":7},{"name":"handbook-01-introduction","section":7},{"name":"man","section":1}],"bareOsNotes":"Generated at build time from handbook/02-blueprints.md. Diagrams in ```mermaid blocks are omitted; open the Markdown in the repo for figures.","listCategory":"handbook"},{"name":"handbook-03-protocol-and-disk","section":7,"title":"Chapter 3 — Protocol, MBR, and SwarmDisk","synopsis":["man 7 handbook-03-protocol-and-disk","Handbook chapter (plain text from handbook/03-protocol-and-disk.md)"],"description":"CHAPTER 3 — PROTOCOL, MBR, AND SWARMDISK\n\nHere we connect bare-os-protocol to what seeder and booter actually do on the wire and in RAM.\n\nSEEDER LIFECYCLE\n\n1. Resolve kernel root (BARE_OS_KERNEL_ROOT or vendored kernel/).\n2. Optionally rebuild coreutils when running under Node (file: URL) — skipped under Pear.\n3. Open Corestore + Hyperdrive, stageKernelTree:\n- init.js → /boot/init.js\n- bin/ → /bin/\n- etc/ → /etc/\n4. Build MBR with buildMbr(drive.key) and store block 0 in a Map (localRAM).\n5. Hyperswarm join(topicKey()) and join(drive.discoveryKey).\n6. On each connection: Protomux + setupSeedChannel, which:\n- Answers read index requests from localRAM (index 0 → MBR)\n- Attaches drive.replicate(stream)\n\nBOOTER: FROM PEERS TO HYPERDRIVE\n\nSwarmDisk (booter) mirrors the seeder’s channel handlers:\n\n- read(index) — if not local RAM, broadcast msg 0 to peers, await msg 1 (timeout).\n- addPeer — open channel, replicate system (and later personal) drives on the mux stream.\n\nBoot path:\n\n1. Wait until disk.peers.size > 0 or boot timeout.\n2. parseMbr(await disk.read(0)) → list of 32-byte keys.\n3. For each key, try Hyperdrive(store, key) + replicate until /boot/init.js exists.\n4. Initialize personal drive namespace and join its discovery key.\n5. Hand off to executeKernel.\n\nThere is intentionally no “use my checkout’s kernel/ if the network fails” path—the project forces you to think about availability of the swarm.\n\nMESSAGE IDS (REFERENCE)\n\nAligned with packages/bare-os-protocol/lib/channel.js and swarm-disk.js:\n\n| ID | Direction | Purpose |\n| 0 | Client → peers | Read block by index |\n| 1 | Peer → client | Data payload |\n| 2 | Gossip stub | Bitfield buffer |\n| 3 / 4 | Search req/res | Stub (empty matches) |\n| 5 / 6 | RPC req/res | bare_os.version implemented; other methods return “not implemented” |\n\nThe important path for boot is 0/1 + Hyperdrive replication on the same socket.\n\nKERNEL FEATURE BITMASK (DOCUMENTATION)\n\nThe package bare-os-protocol exports lib/kernel-feature-bits.js (re-exported from index.js) with a small versioned bitmask describing optional booter capabilities (IPC fan-out, abort/timeouts, HTTP policy, virtual files, host stats bridge). It is not sent on the Protomux wire today; it appears under /proc/bare_os_features for introspection and release notes. Unknown bits should be ignored.\n\nPERSONAL DRIVE REPLICATION\n\nSwarmDisk.initPersonalDrive creates a separate Hyperdrive under a stable Corestore namespace and swarm.join(personalDrive.discoveryKey). Your $HOME tree can therefore sync across your devices if peers share that discovery key—orthogonal to the system image key from the MBR.\n\nFAILURE MODES YOU WILL SEE IN THE WILD\n\n- Boot timeout — no peer answered the topic (seeder not running, firewall, wrong network).\n- Invalid MBR — corrupt block 0 or wrong magic; parseMbr throws.\n- Drive never completes — replication stalled; check peer count and discovery key joins.\n\n← Blueprints <02-blueprints.md> · Handbook home · Next: Booter runtime → <04-the-booter-runtime.md>","descriptionMode":"preserve","options":[],"keywords":["handbook","bare-os","documentation","narrative","chapter","03","protocol","and","disk","mbr","swarmdisk"],"seeAlso":[{"name":"handbook-04-the-booter-runtime","section":7},{"name":"handbook-02-blueprints","section":7},{"name":"man","section":1}],"bareOsNotes":"Generated at build time from handbook/03-protocol-and-disk.md. Diagrams in ```mermaid blocks are omitted; open the Markdown in the repo for figures.","listCategory":"handbook"},{"name":"handbook-04-the-booter-runtime","section":7,"title":"Chapter 4 — The booter runtime: ctx, VFS, shell, kernel, services","synopsis":["man 7 handbook-04-the-booter-runtime","Handbook chapter (plain text from handbook/04-the-booter-runtime.md)"],"description":"CHAPTER 4 — THE BOOTER RUNTIME: CTX, VFS, SHELL, KERNEL, SERVICES\n\nThe booter is the largest package because it is the machine: everything the user experiences as “the OS” (except the raw Hyperdrive bytes) is assembled in packages/bare-os-booter/index.js and *lib/.js**.\n\nBOOT SPLASH AND STDIO\n\nresolveStdio() picks session stdin/stdout appropriate for Pear/Bare vs Node. When stdout is a TTY and BARE_OS_NO_SPLASH is unset, createBootSplash shows a full-screen progress UI tied to BARE_OS_BOOT_TIMEOUT_MS, then prepareForKernel() clears the screen before the line editor attaches.\n\nNon-TTY mode skips splash noise; automation uses BARE_OS_SKIP_REPL=1.\n\nEXECUTEKERNEL IN ONE PARAGRAPH\n\nAfter the system and personal drives exist:\n\n1. Build shellEnv (guest defaults: HOME, PATH, USER, …, BARE_OS_CTX_API_VERSION), copying host keys when set — including *BARE_OS_PIPELINE_, boot and audit toggles (BARE_OS_BOOT_PROFILE, BARE_OS_ONBOOT, BARE_OS_BOOT_STRICT, BARE_OS_RC_D_SKIP, BARE_OS_BOOT_MINIMAL, BARE_OS_BOOT_SKIP, BARE_OS_BOOT_TRACE, BARE_OS_KERNEL_SELFTEST, BARE_OS_SELFTEST_FORMAT, BARE_OS_AUDIT, BARE_OS_AUDIT_JSON, BARE_OS_AUDIT_REDACT, BARE_OS_BOOT_ALLOWLIST, BARE_OS_EXEC_MAX_DEPTH, BARE_OS_IPC_MAX_BYTES, BARE_OS_IPC_RPC_TOKEN, BARE_OS_IPC_FANOUT, BARE_OS_IPC_JSON_MAX_BYTES, BARE_OS_HTTP_ALLOWLIST, BARE_OS_HTTP_DENYLIST, BARE_OS_TLS_PIN_SHA256, BARE_OS_VFS_WATCH, BARE_OS_IMAGE_DIGEST, BARE_OS_PEAR_CHANNEL, BARE_OS_PEAR_RELEASE, BARE_OS_BARE_MODULES, BARE_OS_BARE_DRIVE_BUNDLES, PEAR_CHANNEL) — see Chapter 7 <07-operations-and-development.md> and the context object developer guide <../developer-guide/02-the-context-object.md>. Set BARE_OS_BOOT_PROFILE_RESOLVED from the host override or the first line of /etc/bare-os/profile on the system drive; assign BARE_OS_SESSION_ID for /run/bare-os/session. Seed /run/bare-os/boot.json fields imageDigest, pearChannel, pearRelease, and accumulate booterPhases (vfs, ctx, repl, initd, kernel_invoke) for observability alongside kernel phases**.\n2. createBareOsIpc({ maxFifoBytes, ipcRpcToken?, enableFanout?, maxJsonRpcLineBytes? }) — in-memory FIFOs under /run/bare-os/ipc/; pushJson/takeJson with optional shared-secret field bareOsIpcToken when BARE_OS_IPC_RPC_TOKEN is set; fan-out topics fanoutPublish/fanoutSubscribe (disable with BARE_OS_IPC_FANOUT=0); stats includes fan-out subscriber counts.\n3. createVfs(drive, personalDrive, shellEnv, mntRef, vfsOptions?) — the two-drive router; optional vfsOptions supply procSnapshot (/proc/version, cmdline), dynamic text for /proc/net/dev, /proc/diskstats, /proc/bare_os_quotas, /proc/bare_os_resources, /proc/bare_os_features, /sys/class/net/lo, bootProfileText, sessionText, initdRunText, bootReadyJsonText, getVirtualReaders for /run/bare-os/virtual/, etc.\n4. After VFS: buildBareCtxObjectFromHost + maybeMergeBareFromDrive fill a bareLibrary map (host imports first; drive bundles only add missing keys). /lib/bare/manifest.json and */lib/bare/bundles/.js are trusted like /bin**. See developer guide ch.12 <../developer-guide/12-bare-modules-and-pear-ecosystem.md>.\n5. Construct ctx: disks, vfs, bareOsIpc, env, b4a, optional bare: Object.freeze(bareLibrary) when BARE_OS_BARE_MODULES is enabled, topic, bareOsRuntimeCaps (pipeline limits, quotas, pseudo path list, feature flags such as vfsWatch, ipcRpcJson, ipcFanout, initdSocketActivation, bareCtxModules, bareDriveBundles), optional httpFetch (policy-wrapped fetch when the host provides global fetch), optional bareOsHostStats from the bare-os module, bareOsGetResourceStatus, bareOsRegisterVirtualFile, Pear/sandbox stubs, identity hooks, bareOsSubscribeBootEvent / bareOsEmitBootEvent, bareOsSubscribeHdmsLifecycle, bareOsAwaitInitdUnits, runHdms, requestBooterExit, bareOsPublishBootReady, …\n6. applyGuestEnv + ensureGuestHome — identity stub and /.bare skeleton on the personal drive (after the ctx object exists).\n7. createKernelReplSession — fish-style readLine + console bound to the same stdout as the prompt.\n8. Set ctx.execLine, ctx.readLine, ctx.runBinCommand — optional AbortSignal/timeoutMs on execLine, readLine, runBinCommand, and VFS readFile/writeFile; exit, optional audit logging (BARE_OS_AUDIT, BARE_OS_AUDIT_JSON, redaction), execLine nesting cap (BARE_OS_EXEC_MAX_DEPTH), then execShellLine.\n9. await startBareInitd(ctx) — see below.\n10. runKernelFromSource(initSource, ctx) — runs /boot/init.js.\n\nCleanup path closes swarm/drives and calls session.cleanup(), which runs stopBareInitd().\n\nVFS: TWO DRIVES, ONE PATH SPACE\n\nlib/vfs.js implements resolveLogical with unix-path-resolve(cwd, userPath) (two arguments only—important when reading the code).\n\n- Paths under $HOME resolve to the personal Hyperdrive under /.bare-os/home//… (mutable writeFile / unlink where policy allows); writable /var/log uses /.bare-os/var/log//…; writable /tmp uses /.bare-os/tmp//… (session-isolated scratch).\n- Other absolute paths hit the system drive (OS image).\n- Hyperdrive rejects / as a filename; the VFS special-cases logical root for stat, chdir, exists.\n\nVirtual listings include /home (session-specific), /mnt when HDMS mounts exist, and injected root entries proc, sys, tmp when absent from the system image.\n\nPSEUDO /PROC, /SYS, /RUN, /DEV (MOSTLY READ-ONLY)\n\nThese paths are synthetic (not stored on either Hyperdrive). They exist for inspection and scripting ergonomics, not Linux ABI compatibility.\n\n- /proc: version, bare_os_version, uptime, meminfo, cpuinfo, loadavg, mounts, diskstats (stub text), bare_os_quotas (JSON: pipeline limits, exec-depth cap, IPC cap, session stats, FIFO stats), bare_os_resources (unified operator snapshot), bare_os_features (protocol/kernel feature bitmask doc), net/dev (P2P-oriented stub), self/ with environ, cmdline, exe, plus bare_os_session_stats. environ omits keys whose names look secret-bearing (e.g. PASSWORD, TOKEN, VAULT) and only includes a small public set plus *BARE_OS_ (including BARE_OS_SESSION_ID**).\n- /sys: fs/bare_os/version, fs/bare_os/build_id, class/net/lo (stub operstate / carrier).\n- /sys/fs/bare_os/version: same text as /proc/version.\n- /run/bare-os/units: tab-separated snapshot of bare-initd registered units (phase, start time, description).\n- /run/bare-os/boot_profile: one line (plus newline): resolved boot profile name (BARE_OS_BOOT_PROFILE from the host, else first line of /etc/bare-os/profile, else empty). Listed in ctx.bareOsRuntimeCaps.pseudoFsPaths.\n- /run/bare-os/session: session UUID (from BARE_OS_SESSION_ID) plus newline.\n- /run/bare-os/virtual/: optional kernel-registered synthetic files via ctx.bareOsRegisterVirtualFile.\n- /dev/null, /dev/zero: minimal device semantics — null discards writes and reads empty; zero reads a fixed 64 KiB zero buffer. Not infinite /dev/zero like Linux.\n\nNon-goals: no real PIDs, accurate meminfo, or guarantees of path parity with Linux.\n\nvfs.watch(logicalPath) (Hyperdrive-backed paths only — not pseudo roots): returns { watcher, destroy, logicalAbs, driveFolder }; use Hyperdrive’s async iterator on watcher. Disabled when host sets BARE_OS_VFS_WATCH=0. See ctx.bareOsRuntimeCaps.features.vfsWatch.\n\nImplementation note: pseudo-file content is UTF-8 encoded with b4a, not TextEncoder, because some Bare/Pear runtimes omit the Web Encoding globals (TextEncoder / TextDecoder). The same applies elsewhere in the booter and in-image utilities that must run on Bare.\n\n/DEV AND /RUN (MINIMAL SUBSET)\n\nSee Pseudo /proc, /sys, /run, /dev above. A full device tree and /run parity with Linux are still out of scope.\n\nKERNEL / BOOTER FOLLOW-ONS (BACKLOG)\n\nPriorities from existing gap docs: curl / wget items in packages/bare-os-booter/CLI_PARITY.md that remain out of scope (e.g. -Y/-y, mutual TLS, extra protocols); optional wget split connect vs total timeout to mirror curl; host ctx.httpFetch honoring init.bareOsCurlTls for real TLS when integrating Pear/custom stacks. Optional extra *bare_os. seeder RPC beyond version in bare-os-protocol; coreutils stubs and flag gaps per DOCUMENTATION.md §14a. Bounded shell pipeline limits and ctx.bareOsRuntimeCaps** introspection are implemented (see Chapter 9 <09-posix-utilities-shell-and-vfs.md> and the context object developer guide <../developer-guide/02-the-context-object.md>).\n\nIMPLEMENTATION PRIORITY (MILESTONES)\n\nWork is sequenced for POSIX/script ergonomics first, then networking and long-running service features:\n\n1. VFS and shell — Synthetic /proc / /sys (including mounts, quotas JSON, net/disk stubs) and /run (including /run/bare-os/session, boot_profile, units, boot.json) and minimal /dev paths, bounded pipeline capture in execShellLine (done), vfs.watch on Hyperdrive paths when enabled (done), ctx.bareOsRuntimeCaps (done, including features.httpDelegate, gitDelegate, systemctlDelegate, vfsWatch, ipcRpcJson, initdSocketActivation), kernel boot trace (BARE_OS_BOOT_TRACE text, json, or ndjson), rc.local, kernel.d, BARE_OS_BOOT_STRICT, BARE_OS_RC_D_SKIP, BARE_OS_BOOT_ALLOWLIST, multiline onboot, banner, profile hooks on the system image (Chapter 6 <06-kernel-and-binaries.md>).\n2. /bin and help — man -w, optional sliced long pages via MAN_SLICE / PAGER=bare-slice, incremental coreutils flags (e.g. grep -w).\n3. Networking — CLI_PARITY.md: cookies, --connect-timeout, combined --max-time, and bareOsCurlTls passthrough for delegated httpFetch are implemented; remaining gaps are mostly out-of-scope transports and optional wget timeout split.\n4. Init and protocol — Richer *bare_os.** RPC, after the above stabilize.\n\nDirectories: vfs.mkdir(path, { recursive }) and vfs.rmdir(path) implement POSIX-like tree creation and removal using a .bareos_empty marker file for empty directories (aligned with git-fs-adapter). See Chapter 9 <09-posix-utilities-shell-and-vfs.md>.\n\nctx.runBinCommand(argv) — same resolution as external commands in the shell; exposed for utilities such as /bin/time.\n\nSHELL AND KERNEL RUNNER\n\nexecShellLine (lib/shell.js):\n\n- Tokenizes words, quotes, escapes, $VAR, pipelines |, redirections > / >> / <.\n- Builtins: alias, unalias, cd, export, unset, readonly, umask, :, command, type, login, logout, exit — plus external commands via runBinCommand. readonly blocks export and assignment writes to the same name; command -v / -V and type use resolveBinInPath for PATH lookup.\n- First-word aliases (defaults like ll → ls -la, nano → edit) expand after $VAR substitution; alias / unalias match the restricted ~/.barerc syntax (not full POSIX sh).\n- Pipes capture console.log into the next stage or a string sink.\n\nrunBinCommand (lib/kernel-runner.js):\n\n1. If argv[0] contains / — resolve via VFS, drive.get, runScriptFromSource.\n2. Else if the name ends with .js — resolve $PWD/name.js first (same as explicit ./ for many cases).\n3. Else walk PATH on the system drive only.\n\nrunScriptFromSource strips an optional #! line, runs the script body as top-level code in an async function, then awaits a top-level run(ctx, argv) if one is defined (optional for user scripts; /bin utilities always define run). It catches errors—logs to ctx.console.error without unwinding the kernel loop.\n\nrunKernelFromSource requires async function start(ctx) at the top level of /boot/init.js.\n\n~/.BARERC (RESTRICTED STARTUP FILE)\n\nOn guest and logged-in identity transitions, the booter loads ~/.barerc from the personal drive if it exists. On login (unlocked identity), if the file is missing, the booter creates a comment-only skeleton you can edit. Only these forms are applied (other lines are ignored; set BARE_OS_STRICT_BARC=1 to log warnings):\n\n- export NAME=value — same name rules as the shell builtin; value is expanded like export in execShellLine.\n- alias name=value and unalias — same behavior as the interactive builtins (unalias -a resets to the default alias table).\n\nThere is no arbitrary command execution, source, or control flow — it is intentionally not a full sh profile.\n\nBARE-INITD AND KERNEL LOGGER\n\nbare-initd.js:\n\n- registerBareService({ name, start, stop?, description?, logPath? }) — optional stop enables systemctl stop / restart for that unit; logPath is a logical VFS path for systemctl status / logs\n- startBareInitd(ctx) — ensures /var/log/bare-os (see below), then ordered start (skips units listed in ~/.config/bare-os/initd/disabled.txt on the personal drive; optional ~/.config/bare-os/units/.unit with [Unit] keys After=, Requires=, Wants=, TimeoutStartSec=, TimeoutStopSec=, Restart=, RestartSec=, ExecStartPost=, SocketActivationIpc= — the last defers start() until the first read on that logical FIFO name — plus ReadinessPath= (VFS path that must exist before the unit is marked active) and ReadinessTimeoutSec= (poll budget, default 30s)). Default bare-cron runs after kernel-logger. Per-service try/catch, [bare-initd] name: err on failure; failures append to /var/log/bare-os/initd.log; runtime state active / failed / inactive. waitForBareInitdUnits(names, timeoutMs) polls until listed units are active (exposed on ctx as bareOsAwaitInitdUnits).\n- listBareServices(), getBareServiceRuntime(name), findBareServiceDefinition(name), startBareService / stopBareService / restartBareService — introspection and lifecycle (used by the CLI below)\n- registerKernelShutdownHook(fn) + runKernelShutdownHooks() — async-friendly teardown before disposers (REPL session.cleanup awaits hooks, then stopBareInitd())\n- registerBareInitdDisposer(fn) + stopBareInitd() — for intervals and synchronous teardown\n- Kernel logger — mirrors console.log/error to /var/log/bare-os/kernel-console.log. The VFS exposes /var as a virtual directory and maps /var/log/… onto the personal Hyperdrive at /.bare-os/var/log/… (the system image drive stays read-only). Each log file is trimmed when it grows past 512 KiB (last 256 KiB kept plus a notice line).\n\nBuilt-in kernel-logger wraps ctx.console.log / error to append UTF-8 lines to that path (with stop / restart support). startBareInitd also creates /var/log/bare-os and a short README there. Other services use the same tree (e.g. cron.log). Failures to write logs are swallowed so logging never kills the session.\n\nService control: /bin/systemctl is implemented by the booter (kernel-runner delegates to systemctl-cli.js), not by eval’d image JS. Subcommands: list / list-units (shows PRESET enabled/disabled from disabled.txt), status, logs, start, stop, restart, enable, disable, is-enabled. journalctl -u UNIT (log tail only) shares the same backend. The legacy name bare-initctl is still accepted as an alias. enable / disable only affect the next startBareInitd (personal-drive config); runtime start / stop remain session commands. See man systemctl.\n\nBARE-CRON\n\nbare-cron.js registers service bare-cron:\n\n- Reads /etc/bare-os/crontab on the system image (if present), then ~/.crontab on the personal drive (silent if missing). Invalid lines are skipped and logged to /var/log/bare-os/cron.log.\n- Loads timer drop-ins from *~/.config/bare-os/timers/.timer: [Timer] section with OnCalendar= (five cron fields) and ExecLine=** — merged into the same minute tick as crontab jobs.\n- Parses five-field cron lines + command remainder.\n- Aligns to minute boundaries, setInterval(60s), runs await ctx.execLine(command) with per-line in-flight guard; job errors are appended to /var/log/bare-os/cron.log as well as console.error.\n- One disposer at module load clears timers on session shutdown; stopBareCron is also the unit stop for systemctl.\n\nInstall/list/remove user crontab with /bin/crontab (see Chapter 6 <06-kernel-and-binaries.md>). See Developer guide ch.11 <../developer-guide/11-kernel-pear-cookbook.md> for timer file layout.\n\nREPL: FISH-STYLE LINE EDITOR\n\nWhen stdin/stdout are a capable TTY and BARE_OS_FISH≠0, fish-readline.js provides history, hints, and synchronized Console output so prompts and console.log do not fight. History files live on the personal drive keyed by user identity.\n\nDEBUG\n\ndebug-repl.js and env-driven logging can trace readline and write paths—useful when stdin is a pipe vs TTY.\n\n← Protocol and disk <03-protocol-and-disk.md> · Handbook home · Next: Identity and HDMS → <05-identity-vault-and-hdms.md>","descriptionMode":"preserve","options":[],"keywords":["handbook","bare-os","documentation","narrative","chapter","04","the","booter","runtime","ctx","vfs","shell","kernel","services"],"seeAlso":[{"name":"handbook-05-identity-vault-and-hdms","section":7},{"name":"handbook-03-protocol-and-disk","section":7},{"name":"man","section":1}],"bareOsNotes":"Generated at build time from handbook/04-the-booter-runtime.md. Diagrams in ```mermaid blocks are omitted; open the Markdown in the repo for figures.","listCategory":"handbook"},{"name":"handbook-05-identity-vault-and-hdms","section":7,"title":"Chapter 5 — Identity, vault, and HDMS","synopsis":["man 7 handbook-05-identity-vault-and-hdms","Handbook chapter (plain text from handbook/05-identity-vault-and-hdms.md)"],"description":"CHAPTER 5 — IDENTITY, VAULT, AND HDMS\n\nThis chapter covers who the session is (guest vs unlocked), where keys live, encrypted vault snapshots, and extra Hyperdrives under /mnt.\n\nGUEST SESSION\n\nOn boot, applyGuestEnv sets:\n\n- USER / LOGNAME — guest\n- HOME / PWD — /home/guest\n- BARE_OS_IDENTITY — guest\n- Empty or absent BARE_OS_PUBLIC_KEY\n\nThe personal drive still persists: guest data is not anonymous to the drive—it is simply the unauthenticated profile.\n\nHome and session logs on disk: logical $HOME and /var/log map to the personal Hyperdrive under /.bare-os/home/ and /.bare-os/var/log/, where is the first segment of HOME (e.g. guest or the 12-hex display name). That keeps guest and unlocked trees separate on the same drive. Shared machine metadata (/.bare/account, /.bare/hdms/, vault blobs, etc.) stays outside those prefixes. On first boot after an upgrade from older booters, a best-effort migration may move non-reserved files from the personal drive root into the current session’s home prefix when that prefix is still empty.\n\nACCOUNT BLOB: /.BARE/ACCOUNT\n\nidentity-account.js defines v2 on-disk format:\n\n- Magic BAREOS01, version 2\n- 32-byte Ed25519 public key\n- PBKDF2-SHA256 salt + iteration count (default 210000)\n- ChaCha20-Poly1305 seal over the 64-byte secret key material (bare-crypto)\n\nlogin --new creates a new account; login decrypts an existing one. Legacy v1 blobs are rejected with a message to recreate.\n\nUNLOCKED SESSION\n\nidentity-session.js:\n\n- Updates ctx.vfs.env with real USER, HOME under /home/, BARE_OS_PUBLIC_KEY, derived UID/GID-like fields from a hash of the public key.\n- vfs.chdir to the new home.\n- onIdentityUnlocked (from index.js) activates HDMS with Corestore, swarm bootstrap, personal drive, mount map.\n- loadBarerc runs inside applyUnlockedEnv after a successful login or login --new (with createSkeletonIfMissing: true on first unlock), so ~/.barerc exports and aliases apply immediately—custom kernels normally do not need to reload barerc themselves. Use ctx.onIdentityUnlocked if you want an extra banner or post-login message.\n\nlogout zeroes sensitive material and returns to guest; logout --save (and savevault) snapshot selected paths into /.bare/vault/ as encrypted records (see identity-account.js helpers for AEAD and path hashing).\n\nHDMS (HYPERDRIVE MANAGEMENT)\n\nhdms-manager.js implements /bin/hdms via ctx.runHdms(argv):\n\n- Registry JSON on the personal drive: /.bare/hdms/registry.json\n- Writable drives: new Corestore namespace + Hyperdrive, label, replicate to swarm\n- Read-only drives: open by key string\n- invite / pair — uses Autopass (static ESM import for Pear tracing)\n\nassertLoggedIn requires ctx.identity.state === 'unlocked' and active controller—guests can list mounts that are already open but cannot mutate registry until login.\n\nVFS exposes /mnt/