snxraven/bare-operating-system
1
1
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
2655fe6a7d9379260ac919b2b52d7030c9b6c371
bare-operating-system/packages/bare-os-seeder/kernel/share/man/man.json
T
Raven Scott 2655fe6a7d Updates
2026-04-03 20:46:09 -04:00

3627 lines
278 KiB
JSON
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
{
"schemaVersion": 1,
"generatedAt": "2026-04-04T00:43:49.073Z",
"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": "Bare OS implementation of strip directory and suffix from pathnames. Full behavior is defined in packages/bare-os-coreutils/src/basename.js.",
"options": [],
"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" }
],
"listCategory": "coreutils"
},
{
"name": "cat",
"section": 1,
"title": "concatenate and print files",
"synopsis": ["cat [OPTION]... [OPERAND]..."],
"description": "Bare OS implementation of concatenate and print files. Full behavior is defined in packages/bare-os-coreutils/src/cat.js.",
"options": [],
"keywords": ["cat", "bare-os", "coreutils"],
"examples": [
{ "caption": "stdout several files", "code": "cat a.txt b.txt" },
{
"caption": "number lines (use nl)",
"code": "cat -n file.txt # if supported; else nl file"
},
{ "caption": "here-string via echo pipe", "code": "echo hello | cat" }
],
"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": "Bare OS implementation of display or set date and time. Full behavior is defined in packages/bare-os-coreutils/src/date.js.",
"options": [],
"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": "Bare OS implementation of return directory portion of a pathname. Full behavior is defined in packages/bare-os-coreutils/src/dirname.js.",
"options": [],
"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": "du",
"section": 1,
"title": "estimate file space usage",
"synopsis": ["du [OPTION]... [OPERAND]..."],
"description": "Bare OS implementation of estimate file space usage. Full behavior is defined in packages/bare-os-coreutils/src/du.js.",
"options": [],
"keywords": ["du", "bare-os", "coreutils"],
"examples": [
{ "caption": "sizes under cwd", "code": "du ." },
{ "caption": "human (if supported)", "code": "du -h ~" }
],
"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]... [OPERAND]..."],
"description": "Bare OS implementation of set the environment for command invocation. Full behavior is defined in packages/bare-os-coreutils/src/env.js.",
"options": [],
"keywords": ["env", "bare-os", "coreutils"],
"examples": [
{ "caption": "print environment", "code": "env" },
{
"caption": "run with override",
"code": "env PATH=/bin:/usr/bin man ls"
}
],
"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 directories and applies expressions (-name, -type, -print, -maxdepth, -mindepth, logical -and/-or/-not).",
"options": [],
"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": "OR names",
"code": "find . \\( -name \"*.c\" -o -name \"*.h\" \\)"
}
],
"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": "-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" }
],
"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": "Bare OS implementation of copy the first part of files. Full behavior is defined in packages/bare-os-coreutils/src/head.js.",
"options": [],
"keywords": ["head", "bare-os", "coreutils"],
"examples": [
{ "caption": "first 10 lines", "code": "head /etc/os-release" },
{ "caption": "first N", "code": "head -n 50 big.log" },
{ "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] [FILE...]"],
"description": "Lists directory contents. Long format shows mode, links, owner, group, size, mtime, and symlink targets.",
"options": [
{ "flag": "-a", "meaning": "Include names starting with ." },
{ "flag": "-l", "meaning": "Long listing" },
{ "flag": "-1", "meaning": "One name per line (short format)" }
],
"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]... [OPERAND]..."],
"description": "Bare OS implementation of make directories. Full behavior is defined in packages/bare-os-coreutils/src/mkdir.js.",
"options": [],
"keywords": ["mkdir", "bare-os", "coreutils"],
"examples": [
{ "caption": "one dir", "code": "mkdir proj" },
{ "caption": "parents", "code": "mkdir -p a/b/c" }
],
"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": "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": "Bare OS implementation of sort lines. Full behavior is defined in packages/bare-os-coreutils/src/sort.js.",
"options": [],
"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": "Bare OS implementation of copy the last part of a file. Full behavior is defined in packages/bare-os-coreutils/src/tail.js.",
"options": [],
"keywords": ["tail", "bare-os", "coreutils"],
"examples": [
{ "caption": "last lines", "code": "tail -n 20 app.log" },
{
"caption": "follow vibe (Bare: poll manually)",
"code": "tail error.log"
}
],
"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": "Bare OS implementation of evaluate a condition. Full behavior is defined in packages/bare-os-coreutils/src/test.js.",
"options": [],
"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": "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]... [OPERAND]..."],
"description": "Bare OS implementation of change file timestamps or create files. Full behavior is defined in packages/bare-os-coreutils/src/touch.js.",
"options": [],
"keywords": ["touch", "bare-os", "coreutils"],
"examples": [
{ "caption": "create empty", "code": "touch newfile" },
{ "caption": "refresh mtime", "code": "touch -c existing" }
],
"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": "Bare OS implementation of word, line, and byte or character count. Full behavior is defined in packages/bare-os-coreutils/src/wc.js.",
"options": [],
"keywords": ["wc", "bare-os", "coreutils"],
"examples": [
{ "caption": "lines words bytes", "code": "wc README.md" },
{ "caption": "stdin only", "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] [-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)"
}
],
"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-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] <subcommand> [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 \"[email protected]\""
},
{
"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=<size>-; 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>.\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-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 |\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 <README.md> · 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/<pubkey-prefix>, 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 <README.md> · 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 <README.md> · 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, 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/<name>; 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/<name>, etc.\n4. applyGuestEnv + ensureGuestHome — identity stub and /.bare skeleton on the personal drive.\n5. Construct ctx: disks, vfs, bareOsIpc, env, b4a, topic, bareOsRuntimeCaps (pipeline limits, quotas, pseudo path list, feature flags such as vfsWatch, ipcRpcJson, ipcFanout, initdSocketActivation), 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. createKernelReplSession — fish-style readLine + console bound to the same stdout as the prompt.\n7. 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.\n8. await startBareInitd(ctx) — see below.\n9. 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/<HOME-basename>/… (mutable writeFile / unlink where policy allows); writable /var/log uses /.bare-os/var/log/<same-basename>/…; writable /tmp uses /.bare-os/tmp/<same-basename>/… (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) 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, requires async function run(ctx, argv), and 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/<name>.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 <README.md> · 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/<basename> and /.bare-os/var/log/<basename>, where <basename> 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/<pubkey-prefix>, 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/<label>/... for mounted drives; writable mounts allow put on those routes.\n\nKernel hooks: ctx.bareOsSubscribeHdmsLifecycle(fn) runs your callback after HDMS activate and before deactivate with { kind: 'afterActivate' | 'beforeDeactivate', labels?: string[] } so custom /boot/init.js can refresh mounts-dependent state without forking HDMS. The stock booter also invokes onAfterActivate on the hdms module export when present (see Developer guide ch.11 <../developer-guide/11-kernel-pear-cookbook.md>).\n\nCRON AND IDENTITY\n\ncrontab install/remove requires unlocked identity so arbitrary guests cannot overwrite ~/.crontab on a shared replica interpretation—reading jobs is still “whatever file exists on your personal drive.”\n\nTHREAT SKETCH (NOT A FORMAL AUDIT)\n\n- Passphrase strength matters: PBKDF2 iterations slow brute force but do not fix weak secrets.\n- Vault ciphertext is only as safe as the derived key and where copies replicate.\n- JS in-process commands can exfiltrate keys from memory—this is a toy OS shell, not a sandbox.\n\n← Booter runtime <04-the-booter-runtime.md> · Handbook home <README.md> · Next: Kernel and binaries → <06-kernel-and-binaries.md>",
"descriptionMode": "preserve",
"options": [],
"keywords": [
"handbook",
"bare-os",
"documentation",
"narrative",
"chapter",
"05",
"identity",
"vault",
"and",
"hdms"
],
"seeAlso": [
{ "name": "handbook-06-kernel-and-binaries", "section": 7 },
{ "name": "handbook-04-the-booter-runtime", "section": 7 },
{ "name": "man", "section": 1 }
],
"bareOsNotes": "Generated at build time from handbook/05-identity-vault-and-hdms.md. Diagrams in ```mermaid blocks are omitted; open the Markdown in the repo for figures.",
"listCategory": "handbook"
},
{
"name": "handbook-06-kernel-and-binaries",
"section": 7,
"title": "Chapter 6 — Kernel and /bin utilities",
"synopsis": [
"man 7 handbook-06-kernel-and-binaries",
"Handbook chapter (plain text from handbook/06-kernel-and-binaries.md)"
],
"description": "CHAPTER 6 — KERNEL AND /BIN UTILITIES\n\nThe kernel is a single script. The utilities are many small scripts. Both follow strict AsyncFunction contracts so the same code runs under Bare without a bundler per command.\n\n/BOOT/INIT.JS\n\nStaged from kernel/init.js. Responsibilities (typical):\n\n1. Print /etc/os-release via ctx.drive.get + b4a.toString\n2. Print optional /etc/motd if present\n3. Optional boot profile: first line of /etc/bare-os/profile, overridden by host BARE_OS_BOOT_PROFILE; if the name is safe, run /etc/bare-os/rc.profile.<name> when present (before main rc)\n4. Run non-comment lines from /etc/bare-os/rc through execLine (boot-time shell snippets)\n5. Run digit-prefixed snippets under /etc/bare-os/rc.d/ (same rules as before)\n6. Run optional /etc/bare-os/rc.local (non-comment lines via execLine, after rc.d)\n7. Run digit-prefixed snippets under /etc/bare-os/kernel.d/ (same skip rules as rc.d) after rc.local and before the banner\n8. Print a one-line hint (commands, login, paths), or /etc/bare-os/banner / /etc/issue when present\n9. When BARE_OS_SKIP_REPL: optional onboot — every non-comment line from host BARE_OS_ONBOOT (newline-separated), or if unset, every such line from /etc/bare-os/onboot in order, via execLine\n10. Loop forever:\n\n- line = await readLine('')\n- Break on null (EOF / session end)\n- Skip empty lines\n- try/catch around execLine(t) so stray throws do not kill the loop\n\nThe prompt ([user@host:path] > ) is applied by the booter’s readline layer, not by init.js.\n\nBOOT PROFILES, RECOVERY, AND READINESS\n\n| Host / kernel env | Purpose |\n| BARE_OS_BOOT_PROFILE / /etc/bare-os/profile | First line names /etc/bare-os/rc.profile.<name> (before rc). Suggested names: dev (extra PATH, aliases), ci (BARE_OS_SKIP_REPL + BARE_OS_ONBOOT smoke lines), kiosk (minimal rc.d, fixed onboot). |\n| BARE_OS_BOOT_MINIMAL | Skip rc, rc.d, rc.local, kernel.d, onboot, and profile *rc.profile. — recovery shell with os-release / motd** only. |\n| BARE_OS_BOOT_SKIP | Comma list of phases to skip: profile, rc, rc.d, rc.local, kernel.d, onboot. |\n| BARE_OS_BOOT_TRACE=ndjson | One JSON object per boot phase on stderr (type, phase, ms, sessionId, ts). |\n| BARE_OS_KERNEL_SELFTEST | After boot snippets, run a short trusted execLine checklist. |\n| BARE_OS_SELFTEST_FORMAT=tap | Same self-test emits TAP lines on stderr (CI-friendly). |\n| BARE_OS_BOOT_ALLOWLIST=1 | Only run boot snippet lines whose first shell token is listed in /etc/bare-os/boot.allow (plus safe builtins); distributors can start from etc/bare-os/boot.allow.example on the system image. Pair with BARE_OS_BOOT_STRICT to exit on the first disallowed or failing line. |\n| BARE_OS_EXEC_MAX_DEPTH | Max nested execLine depth (host → session; default 64). |\n| ctx.bareOsPublishBootReady(...) | Kernel calls this when boot is complete; populates /run/bare-os/ready (1 / 0) and /run/bare-os/boot.json (imageDigest, pearChannel, pearRelease are pre-seeded from host env when set — see DOCUMENTATION.md <../DOCUMENTATION.md> §14). |\n\nCUSTOM INIT.JS CONTRACT\n\nReplacing /boot/init.js on the system image is supported: the booter loads it with AsyncFunction and expects a top-level async function start(ctx). Stable ctx fields for kernels are documented in Chapter 4 <04-the-booter-runtime.md> and the context object developer guide <../developer-guide/02-the-context-object.md>, including ctx.bareOsRuntimeCaps for pipeline limits, quotas, pseudo path lists, and features (e.g. httpDelegate, gitDelegate, systemctlDelegate, vfsWatch, ipcRpcJson, initdSocketActivation). Use ctx.registerKernelShutdownHook for teardown that must run before stopBareInitd. Boot snippets under /etc/bare-os/rc, /etc/bare-os/rc.d/ (only rc.d files whose names start with a digit), rc.local, kernel.d/ (same digit-prefix rules), *rc.profile., and onboot are trusted (full execLine power); keep them minimal. Optional /etc/bare-os/boot.allow (see boot.allow.example in the kernel tree) lists allowed first tokens when BARE_OS_BOOT_ALLOWLIST=1**.\n\nCOREUTILS BUILD PIPELINE\n\n packages/bare-os-coreutils/lib/runtime.js\n +\n (optional) packages/bare-os-coreutils/lib/<engine>.js ← sed-engine, awk-engine\n +\n packages/bare-os-coreutils/src/<cmd>.js\n ↓ (build.mjs, see preamble map)\n kernel/bin/<cmd>\n packages/bare-os-seeder/kernel/bin/<cmd> ← Pear vendored copy\n\nRule: no import in src/.js — only async function run(ctx, argv) (shared helpers live in lib/runtime.js). Large sed and awk bodies live in lib/-engine.js and are prepended at build time (same global scope as run**).\n\nFull POSIX-style catalog, stubs, and divergence notes: Chapter 9 — POSIX utilities, shell, and VFS <09-posix-utilities-shell-and-vfs.md>.\n\nFILE METADATA AND PERMISSIONS (NOT FULL POSIX)\n\nHyperdrive entries carry optional metadata.bareOs (mode, uid, gid, names, mtime) set on vfs.writeFile. New files use UMASK from the environment (default 022): typically 0644 for data files, 0755 when executable is set. ls -l and stat/lstat read that metadata; seeded system files without bareOs are synthesized (e.g. root, 0555 under /bin). The VFS enforces basic read/write/traverse checks from UID/GID and mode bits. chown / chgrp update that metadata on the personal drive (same writable scope as chmod); this is still not ACLs or a multi-user host kernel.\n\nCOMMAND REFERENCE (SUMMARY)\n\n| Command | Role |\n| systemctl, journalctl | Booter-delegated: list/status/logs/start/stop/restart/enable/disable/is-enabled/is-active for bare-initd units; preset file on personal drive; journalctl -u only; bare-initctl alias; see ch. 4 |\n| basename, dirname | Path manipulation |\n| cat, head, tail, nl | Text |\n| clear | ANSI clear screen |\n| crontab | -l list, -r remove, <file> install (~/.crontab; writes need login) |\n| date | Date/time |\n| echo, printf-like simplicity | Args to stdout |\n| env, printenv | Environment |\n| exit | Sets exit code / session end via booter |\n| false, true | Status |\n| grep | Line filter: -E/-F, -i, -v, -w, -x, -n, -c, -l, -o, -m, -q, -s, -e, -f, -H/-h; JS RegExp, not full GNU/PCRE |\n| hdms | Hyperdrive management CLI |\n| help | Lists builtins + /bin |\n| hostname | Host string |\n| id, whoami, tty | Identity / TTY |\n| login, logout | Account session |\n| ls | Lists directories; *hides . unless -a; -l** uses real mode, owner, group, mtime from VFS stat |\n| chmod | Octal (e.g. 644) or symbolic (e.g. u+rw) on writable drives; updates stored metadata + executable bit |\n| mkdir, rmdir | mkdir -p; empty dirs use .bareos_empty (see ch. 9) |\n| cp, mv, ln | cp -R, mv (copy+delete trees), ln -s only (no hard links) |\n| stat, readlink | File metadata and symlink targets |\n| printf, cut, tr, od | Formatting and text transforms (ASCII-oriented tr) |\n| sed, awk | Large JavaScript engines in *lib/-engine.js** — not byte-identical to GNU/POSIX everywhere; see ch. 9 |\n| tee, find, du, cksum | Pipe tee, limited find (-maxdepth, -mindepth, -depth, -name, -type), du -k, POSIX CRC cksum |\n| mktemp | Creates a temp file under session /tmp (template XXX suffix) |\n| git-pear | Thin helper for Git + Pear workflows (channel/release env); see Chapter 8 <08-git-on-bare-os.md> |\n| time, logname | Wall-clock time via ctx.runBinCommand; identity string |\n| chown, chgrp | Update ownership in metadata.bareOs on the personal drive (same writable scope as chmod); supports :group and numeric ids; root vs owner rules as in VFS |\n| mkfifo | Creates a simulated named pipe at /run/bare-os/ipc/<name> (in-memory FIFO in the booter; readFile blocks until writeFile delivers bytes) |\n| getconf, xargs | Documented Bare subsets (fixed getconf table; bounded xargs via ctx.runBinCommand) |\n| pathchk | Path sanity |\n| pwd | Logical cwd |\n| rm | Remove files; -r/-R/--recursive for directories, -f/--force (bundled -rf) — uses VFS tree walk + del per entry |\n| savevault | Encrypted vault snapshot |\n| seq, sleep, sort | Misc |\n| test, [ | Conditionals (as implemented) |\n| touch | Create/empty files |\n| uname | OS string |\n| wc, which | Text / PATH lookup |\n\nExact flags vary—read each src/<cmd>.js for truth.\n\nRUNNING USER SCRIPTS\n\n- ./foo.js — explicit relative path via VFS.\n- foo.js — if the basename ends with .js, the runner tries $PWD/foo.js before scanning PATH on the system drive.\n\nShebang lines #!... are stripped before compilation.\n\nEDITING THE BANNER\n\nUpdate kernel/init.js and packages/bare-os-seeder/kernel/init.js if you want the staged Pear copy’s first-run text to match (some workflows copy automatically via build; the seeder’s kernel/ tree may be vendored separately—check your release process).\n\n← Identity and HDMS <05-identity-vault-and-hdms.md> · Handbook home <README.md> · POSIX utilities & shell (detail) → <09-posix-utilities-shell-and-vfs.md> · Next: Operations → <07-operations-and-development.md>",
"descriptionMode": "preserve",
"options": [],
"keywords": [
"handbook",
"bare-os",
"documentation",
"narrative",
"chapter",
"06",
"kernel",
"and",
"binaries",
"bin",
"utilities"
],
"seeAlso": [
{ "name": "handbook-07-operations-and-development", "section": 7 },
{ "name": "handbook-05-identity-vault-and-hdms", "section": 7 },
{ "name": "man", "section": 1 }
],
"bareOsNotes": "Generated at build time from handbook/06-kernel-and-binaries.md. Diagrams in ```mermaid blocks are omitted; open the Markdown in the repo for figures.",
"listCategory": "handbook"
},
{
"name": "handbook-07-operations-and-development",
"section": 7,
"title": "Chapter 7 — Operations, development, and release",
"synopsis": [
"man 7 handbook-07-operations-and-development",
"Handbook chapter (plain text from handbook/07-operations-and-development.md)"
],
"description": "CHAPTER 7 — OPERATIONS, DEVELOPMENT, AND RELEASE\n\nThis chapter is the operator’s desk: how to install, test, run Pear apps, and interpret common failures.\n\nREPOSITORY LAYOUT (MONOREPO)\n\n| Path | Package / role |\n| package.json | Workspaces root, pretest builds coreutils + kernel/seeder parity check |\n| kernel/ | System image sources |\n| packages/bare-os-protocol | Topic + MBR + Protomux helpers |\n| packages/bare-os-coreutils | Build /bin scripts |\n| packages/bare-os-seeder | Publish OS drive |\n| packages/bare-os-booter | Network boot + runtime |\n| scripts/ | Pear node_modules fixer, etc. |\n| data/ | Gitignored legacy Corestore dir (optional; defaults use ~/.bare-os) |\n\nEach workspace has its own README.md with package-specific commands.\n\nINSTALL AND TEST\n\n npm ci\n npm test\n\n- pretest runs npm run build -w bare-os-coreutils and node scripts/verify-kernel-seeder-parity.mjs (fail if kernel/ and packages/bare-os-seeder/kernel/ diverge).\n- booter tests use Node for Hyperdrive + Bare for identity crypto (test.identity.js).\n\nInstall Bare globally for CI parity: npm install -g bare (see .github/workflows/ci.yml).\n\nRUNNING SEEDER AND BOOTER (NODE)\n\nFrom packages/bare-os-seeder:\n\n node index.js\n\nFrom packages/bare-os-booter:\n\n node index.js\n\nDefault Corestore paths are ~/.bare-os/corestore/seeder and ~/.bare-os/corestore/booter (override base with BARE_OS_HOST_DATA, or set BARE_OS_SEED_STORE / BARE_OS_BOOT_STORE). See each package’s lib/paths.js.\n\nRUNNING WITH PEAR (RECOMMENDED FOR “REAL” BEHAVIOR)\n\nFrom repo root:\n\n npm run os:seeder\n npm run os:booter # second terminal\n\nThese run scripts/ensure-pear-node-modules.mjs first. Do not run pear run os:seeder — os:seeder is an npm script name, not a Pear link.\n\nENVIRONMENT VARIABLES (CHEAT SHEET)\n\n| Variable | Component | Meaning |\n| BARE_OS_KERNEL_ROOT | Seeder | Override kernel tree path |\n| BARE_OS_HOST_DATA | paths | Host state base (default ~/.bare-os) |\n| BARE_OS_SEED_STORE | Seeder | Corestore directory |\n| BARE_OS_BOOT_STORE | Booter | Booter Corestore directory |\n| BARE_OS_BOOT_TIMEOUT_MS | Booter | Boot deadline (default 60000) |\n| BARE_OS_NO_SPLASH | Booter | Disable TTY splash |\n| BARE_OS_SKIP_REPL | Booter | Non-interactive kernel |\n| BARE_OS_FISH | Booter | Set 0 to disable fish readline |\n| HYPERSWARM_BOOTSTRAP | Booter / HDMS | Comma-separated bootstrap nodes |\n\nThe booter also copies many *BARE_OS_ toggles from the host into the guest session (pipeline caps, boot strictness, audit, Pear metadata, BARE_OS_VFS_WATCH, BARE_OS_BOOT_ALLOWLIST**, etc.). See DOCUMENTATION.md <../DOCUMENTATION.md> §14 for the full list.\n\nPEAR STAGING AND PEAR:// LINKS\n\nAfter pear stage / pear release, Pear prints a pear://… link per app. Distribution expects consumers to run those keys—not arbitrary git checkouts—unless they run in dev mode with pear run --dev ..\n\nFORMATTING\n\n npm run format\n npm run lint\n\nPrettier config: no semicolons, single quotes (.prettierrc).\n\nTROUBLESHOOTING\n\n| Symptom | Likely cause |\n| Booter exits at timeout | No seeder peer on bare-os-v1 topic |\n| /bin/foo missing under Pear | Forgot npm run build -w bare-os-coreutils before staging |\n| autopass / module not found in Pear | Hoist/ensure-pear-node-modules / static imports in HDMS |\n| test is not defined in user script | Bug in user JS—should log and continue (kernel runner catches) |\n| Double cron or log spam | Session restarted without stopBareInitd — should run on REPL cleanup |\n\nFURTHER READING\n\n- DOCUMENTATION.md <../DOCUMENTATION.md> — file-by-file reference (large, authoritative for paths)\n- README.md <../README.md> — short overview\n- Handbook Chapter 1 <01-introduction.md> — vocabulary recap\n\n← Kernel and binaries <06-kernel-and-binaries.md> · Handbook home <README.md> · Next: Git on Bare OS → <08-git-on-bare-os.md> · POSIX alignment (detail) → <09-posix-utilities-shell-and-vfs.md>",
"descriptionMode": "preserve",
"options": [],
"keywords": [
"handbook",
"bare-os",
"documentation",
"narrative",
"chapter",
"07",
"operations",
"and",
"development",
"release"
],
"seeAlso": [
{ "name": "handbook-08-git-on-bare-os", "section": 7 },
{ "name": "handbook-06-kernel-and-binaries", "section": 7 },
{ "name": "man", "section": 1 }
],
"bareOsNotes": "Generated at build time from handbook/07-operations-and-development.md. Diagrams in ```mermaid blocks are omitted; open the Markdown in the repo for figures.",
"listCategory": "handbook"
},
{
"name": "handbook-08-git-on-bare-os",
"section": 7,
"title": "Git on Bare OS",
"synopsis": [
"man 7 handbook-08-git-on-bare-os",
"Handbook chapter (plain text from handbook/08-git-on-bare-os.md)"
],
"description": "GIT ON BARE OS\n\nThe git command in this project is not the GNU Git binary. It is a small CLI in the booter package that calls isomorphic-git <https://isomorphic-git.org/> — a JavaScript implementation with a fixed set of APIs, not parity with every git subcommand you might know from a desktop Linux install.\n\nHOW IT RUNS\n\n- Delegation: When you type git (or an absolute path like /bin/git whose basename is git), the booter loads git-cli.js with a normal ESM import. That avoids the Hyperdrive /bin model, where utilities are concatenated and eval’d without import, which cannot load npm packages.\n- Storage: Repositories live on the VFS (personal drive under $HOME, or writable HDMS mounts). isomorphic-git expects a Node-style fs.promises surface; the booter provides createGitFsFromVfs, which maps those calls onto Hyperdrive-backed paths. Empty directories use a hidden marker file (.bareos_empty) because Hyperdrive does not always mirror POSIX directory semantics.\n\nNETWORK (CLONE, FETCH, PUSH)\n\n- On Node, HTTP defaults to isomorphic-git/http/node (simple-get).\n- If that fails to load, or when you set BARE_OS_GIT_HTTP=web, the CLI uses isomorphic-git/http/web, which expects a global fetch. Node 18+ and browsers already provide it; Pear/Bare does not, so the booter loads bare-fetch (Holepunch) and assigns globalThis.fetch (plus Request / Response / Headers) before using the web client.\n- TLS and network policy still depend on the host; some remotes may fail for certificate or connectivity reasons unrelated to isomorphic-git.\n\nEXPECTATIONS\n\n- Use git --help inside Bare OS for the supported subcommand list.\n- Unsupported subcommands print a short message; for full API behavior, see the isomorphic-git documentation <https://isomorphic-git.org/docs/en/next/alphabetic>.\n\nGIT-PEAR AND PEAR METADATA\n\n/bin/git-pear is a small coreutils utility that prints or exports Pear-oriented hints (PEAR_CHANNEL, BARE_OS_PEAR_CHANNEL, BARE_OS_PEAR_RELEASE) for scripts that clone or tag against a Pear release channel. It complements git (which remains the isomorphic-git CLI) and is documented in man git-pear after a coreutils build.\n\ngip (when installed on the host) is described in the Developer guide — Kernel + Pear cookbook <../developer-guide/11-kernel-pear-cookbook.md> as a host-side companion for publishing drives; inside the guest image, prefer git + git-pear for VFS-local workflows.\n\n← Operations and development <07-operations-and-development.md> · Handbook home <README.md> · Next: POSIX utilities and shell → <09-posix-utilities-shell-and-vfs.md>",
"descriptionMode": "preserve",
"options": [],
"keywords": [
"handbook",
"bare-os",
"documentation",
"narrative",
"chapter",
"08",
"git",
"on",
"bare",
"os"
],
"seeAlso": [
{ "name": "handbook-09-posix-utilities-shell-and-vfs", "section": 7 },
{ "name": "handbook-07-operations-and-development", "section": 7 },
{ "name": "man", "section": 1 }
],
"bareOsNotes": "Generated at build time from handbook/08-git-on-bare-os.md. Diagrams in ```mermaid blocks are omitted; open the Markdown in the repo for figures.",
"listCategory": "handbook"
},
{
"name": "handbook-09-posix-utilities-shell-and-vfs",
"section": 7,
"title": "Chapter 9 — POSIX-style utilities, shell builtins, and VFS alignment",
"synopsis": [
"man 7 handbook-09-posix-utilities-shell-and-vfs",
"Handbook chapter (plain text from handbook/09-posix-utilities-shell-and-vfs.md)"
],
"description": "CHAPTER 9 — POSIX-STYLE UTILITIES, SHELL BUILTINS, AND VFS ALIGNMENT\n\nBare OS targets a usable subset of POSIX.1-2017 <https://pubs.opengroup.org/onlinepubs/9699919799/toc.htm> XCU (utilities) and shell-like behavior. It does not implement a full POSIX kernel, process model, or a complete sh (background & and jobs / fg are a small convenience layer, not real job control). This chapter documents what ships today, how it differs from the standard, and where to look in source.\n\nNormative reference: Open Group Issue 7 — use the online utilities index for intended semantics; Bare behavior may intentionally diverge where Hyperdrive or the single-process runtime makes full compliance impossible.\n\n1. EXECUTIVE SUMMARY: WHAT IS _NOT_ POSIX HERE\n\n| Expectation (full POSIX) | Bare OS reality |\n| sh grammar (for, subshells, …) | Line-at-a-time shell: builtins + /bin; lists with ; (outside if/fi), &&, \\\\ | | , \\| pipelines; bounded if then [ else ] fi (condition = last exit status like &&)—no for, groups, or full sh\\\\ grammar. |\n| Processes, fork, pipes as OS primitives | Pipelines are simulated by capturing console.log (and merged console.error when 2>&1 is used) into the next command. |\n| chown / chgrp / real UIDs across users | Single-session identity; metadata carries uid/gid for display and checks. |\n| FIFOs, mknod, real devices | No kernel FIFOs or mknod; mkfifo creates in-memory channels under /run/bare-os/ipc/<name> (see bare-os-ipc.js). |\n| xargs full POSIX/GNU surface | Bounded implementation: ctx.runBinCommand only; -0, -n (and -nN); stdin/token/invocation caps (see src/xargs.js). |\n| getconf / live sysconf | Fixed name table + -a; values are Bare constants, not host kernel queries (see src/getconf.js). |\n| Byte-identical sed / awk / grep | JavaScript engines; regex and edge cases differ from GNU or strict POSIX. |\n\nFor the /bin build contract (no import, AsyncFunction load), see Chapter 6 <06-kernel-and-binaries.md>.\n\n2. VFS: DIRECTORIES, METADATA, AND EMPTY FOLDERS\n\npackages/bare-os-booter/lib/vfs.js <../packages/bare-os-booter/lib/vfs.js> exposes a unified path space over the system and personal Hyperdrives (see Chapter 4 <04-the-booter-runtime.md>).\n\n2.1 EMPTY DIRECTORIES (.BAREOS_EMPTY)\n\nHyperdrive does not always behave like a POSIX directory tree. Empty directories are represented by a hidden marker file .bareos_empty, consistent with git-fs-adapter.js <../packages/bare-os-booter/lib/git-fs-adapter.js> and Chapter 8 — Git <08-git-on-bare-os.md>. readdir on the raw VFS may list that name; git paths filter it.\n\n2.2 MKDIR AND RMDIR\n\n- vfs.mkdir(path, { recursive }) — creates directories by writing dirname/.bareos_empty. -p / --parents is implemented by /bin/mkdir.\n- vfs.rmdir(path) — removes a directory only if it has no entries other than .bareos_empty (and removes the marker).\n\n2.3 PSEUDO /PROC, /SYS, /RUN, /DEV, AND SESSION /TMP\n\n- /proc, /sys, /run, /dev — read-only synthetic trees except /dev/null and /dev/zero accept writes that are discarded (see Chapter 4 <04-the-booter-runtime.md>). Other pseudo writeFile / unlink / chmod paths fail as documented there. Extra Linux-shaped stubs include /proc/cpuinfo, /proc/loadavg, /proc/net/dev, /proc/diskstats, /proc/bare_os_quotas (JSON quotas + session stats), /proc/bare_os_resources (unified resource snapshot), /proc/bare_os_features (documented capability bitmask), /proc/bare_os_session_stats, /proc/self/exe, /sys/class/net/lo, /sys/fs/bare_os/build_id, */run/bare-os/virtual/ (optional kernel-registered readers), and /dev/urandom (each readFile of urandom returns a bounded buffer; not** suitable for cryptography).\n- /tmp — writable on the personal drive under /.bare-os/tmp/<HOME-basename>/…, isolated like $HOME and /var/log.\n\n2.4 CHMOD (OCTAL AND SYMBOLIC)\n\n/bin/chmod accepts:\n\n- Octal modes (e.g. 644, 0755) — passed through to vfs.chmod (permission bits; type bits come from the existing entry).\n- Symbolic modes (e.g. u+rw, go-w) — a supported subset of POSIX symbolic chmod; see packages/bare-os-coreutils/src/chmod.js.\n\n/bin/chown and /bin/chgrp update metadata.bareOs on the personal drive via vfs.chown (same writable scope as chmod); root vs owner rules apply, but this is still a single-session runtime (not a multi-user host kernel).\n\n2.5 COPY AND MOVE\n\n- cp — -R/-r recursive copy; follows the same marker convention (skips copying .bareos_empty as a separate “file” where appropriate).\n- mv — Hyperdrive has no atomic rename; the general case is copy-tree + vfs.rm on the source. A single regular file to a non-directory destination uses readFile → writeFile → unlink on the source (same semantics, slightly less overhead than recursive rm).\n\n3. SHELL LISTS, PIPELINES, AND BUILTINS (PACKAGES/BARE-OS-BOOTER/LIB/SHELL.JS)\n\nTop-level syntax: the line is split on ; into separate lists (semicolons inside an if … fi block do not end the outer statement). if then [ else ] fi uses the same && / || / pipeline rules inside the condition and each branch; the condition is true when the last evaluated command in that &&/|| list exits 0. Each list is an AND-OR chain: pipelines separated by && or ||, evaluated left-to-right with POSIX-style short-circuiting (ctx.exitCode — treat missing as 0). Within a pipeline, | connects stages as before (simulated stdin between utilities).\n\nBackground / jobs (subset): a trailing & on a top-level list runs that list asynchronously (microtask). jobs lists recent jobs; fg awaits the selected (or latest) job; bg is a stub (no stopped-job resume). This is not POSIX job control (no real processes or signals).\n\nHere-string / here-document: <<< word feeds the expanded word as stdin to the first command in the pipeline. A line that ends with << DELIMITER (optional '...' / \"...\" around the delimiter) collects following lines from readLine('> ') until a line equals DELIMITER, then uses that body as stdin ($ expansion is skipped for a single-quoted delimiter name).\n\nPipeline limits: simulated pipe capture is bounded. Defaults: BARE_OS_PIPELINE_MAX_STAGES (32), BARE_OS_PIPELINE_MAX_BYTES (2 MiB), BARE_OS_PIPELINE_MAX_LINES (50 000). Exceeding a limit fails the pipeline with exit status 1 and an error on stderr. Current caps and FIFO stats also surface in /proc/bare_os_quotas and ctx.bareOsRuntimeCaps.quotas.\n\nexecLine nesting: host BARE_OS_EXEC_MAX_DEPTH (default 64) caps recursive execLine calls (e.g. cron, ExecStartPost); exceeding it fails with a clear error.\n\nStderr redirection: 2> / 2>> redirect console.error for the command (same byte/line caps as stdout when captured for a pipe). 2>&1 merges stderr into the stdout capture stream so both appear in the simulated pipe input for the next stage (and in a stdout redirect when it is the last command in the list).\n\nLast exit status: after each full execLine evaluation, vfs.env.BARE_OS_EXIT_STATUS is updated (decimal string). Words expand $? and ${?} from that value (default 0 if unset), similar to POSIX $?.\n\nBeyond alias, unalias, cd, export, login, logout, exit:\n\n| Builtin | Behavior |\n| unset | Removes variables from vfs.env; refuses readonly names (POSIX-style error). |\n| readonly | Marks names readonly; readonly NAME=value sets and locks. Blocks export and leading assignments on readonly keys. |\n| umask | With an argument, sets env.UMASK (octal string); without, prints the current mask (default 022 if unset). |\n| : | No-op (exit status 0). |\n| command | -v / -V: prints builtin name or resolved PATH location via resolveBinInPath. Otherwise runs runBinCommand with the remaining words (external commands only for that path). |\n| type | type NAME — “builtin” vs resolved /bin/... path or “not found”. |\n\n~/.barerc remains restricted ( export, alias, unalias, comments only) — see Chapter 4 <04-the-booter-runtime.md>.\n\n4. BOOTER CTX HELPERS\n\n- ctx.runBinCommand(argv) — same resolution as the shell’s external dispatch ( PATH on the system drive, *.js in $PWD, explicit paths). Used by /bin/time to run another utility and report wall time.\n- resolveBinInPath(ctx, name) in kernel-runner.js — used by command -v / type.\n- ctx.vfs.watch(logicalPath) — Hyperdrive-backed paths only; returns { watcher, destroy, … } when ctx.bareOsRuntimeCaps.features.vfsWatch is true (disable with host BARE_OS_VFS_WATCH=0).\n- ctx.bareOsIpc — in-memory FIFOs under /run/bare-os/ipc/<name>; when features.ipcRpcJson is true, pushJson, takeJson, and stats support bounded JSON envelopes (see bare-os-ipc.js).\n- ctx.bareOsSubscribeBootEvent, ctx.bareOsEmitBootEvent, ctx.bareOsAwaitInitdUnits, ctx.bareOsSubscribeHdmsLifecycle — automation hooks (see Developer guide §2 <../developer-guide/02-the-context-object.md>).\n\n5. /BIN UTILITIES (CATALOG)\n\nSources: packages/bare-os-coreutils/src/<name>.js. Authoritative list: packages/bare-os-coreutils/build.mjs.\n\n5.1 FILESYSTEM AND LINKS\n\n| Command | Notes |\n| mkdir | -p / --parents for recursive create. |\n| rmdir | Empty directories only (marker-aware). |\n| cp | -R/-r/--recursive for trees. |\n| mv | Multi-source → directory; recursive directory moves via copy + delete. |\n| ln | Symbolic links only (-s): hard links are not supported on Hyperdrive entries. |\n| stat | Human-readable stat-style block (not full stat -c format strings). |\n| readlink | -n requested in argv; output still goes through console.log (trailing newline behavior may differ from GNU). |\n| mkfifo | mkfifo /run/bare-os/ipc/NAME only; creates an in-memory channel (readFile pairs with writeFile; unlink removes it). |\n\n5.2 TEXT AND BINARY VIEWING\n\n| Command | Notes |\n| cut | -d delimiter, -f field list (numeric and ranges). |\n| tr | -d delete set, or set1 set2 mapping (byte/char oriented). |\n| od | Hex-ish dump (fixed width); not full POSIX od flag matrix. |\n| tee | -a append; duplicates stdin to files and stdout. |\n| sed | Large subset — see §6. |\n| awk | Substantial interpreter — see §7. |\n| grep | -F fixed strings, -i, -v, -w, -x, -n, -c, -l, -o, -m, -e, -f, etc.; JS RegExp (not PCRE / full GNU). |\n\n5.3 DISCOVERY AND MEASUREMENT\n\n| Command | Notes |\n| find | -maxdepth, -mindepth, -depth (post-order directory walk), -name (glob-to-regex), -type f/d/l. |\n| du | -k for 1024-byte blocks; otherwise 512-byte units (POSIX-ish). |\n| cksum | POSIX / Open Group CRC + length + name (matches common cksum on BSD/macOS for the same bytes). |\n| printf | Subset of printf(1) conversions (%s, %d, %o, %x, etc.). |\n| logname | Prints LOGNAME / USER / guest. |\n| time | Times ctx.runBinCommand for the rest of the line; prints real to stderr. |\n\n5.4 GETCONF AND XARGS (BARE SUBSETS)\n\n| Command | Behavior |\n| getconf | getconf NAME prints a value from a fixed table (PATH_MAX, _POSIX_VERSION, …). getconf -a prints all known names (each name then value on the following line). Unknown names exit 1. |\n| xargs | Reads bareStdin(ctx); splits on whitespace or -0 null bytes; runs await ctx.runBinCommand([utility, …initial, …batch]) per batch. Flags: -0/--null, -n N/--max-args N (capped). Hard limits on stdin size, token count, args per run, and invocations per process—see src/xargs.js. |\n\nAll other commands from build.mjs not listed here follow the summaries in Chapter 6 <06-kernel-and-binaries.md> or their *src/.js** files.\n\nExports for tests / tools: splitTokensBySemicolon, splitTokensByAndOr (same module as tokenize).\n\n6. SED IMPLEMENTATION\n\nEngine: packages/bare-os-coreutils/lib/sed-engine.js (prepended before src/sed.js at build time).\n\nCLI: sed supports -n, -E/-r, multiple -e, -f, and operands as files or stdin.\n\nBroadly supported: line addresses (#, $, /re/, ranges, first~step), s/// with common flags (g, p, digit), y///, d/D/p/P/n/N, hold space (h/H/g/G/x), b/t/:label, q, r/w, =, l, a/i/c (backslash forms). r reads paths via a preload scan + vfs.readFile; w appends via vfs.writeFile.\n\nNot guaranteed: full GNU sed extensions, every POSIX corner case (e.g. all s flag combinations, locale collation), or s delimiter edge cases identical to every implementation.\n\n7. AWK IMPLEMENTATION\n\nEngine: packages/bare-os-coreutils/lib/awk-engine.js (prepended before src/awk.js).\n\nCLI: -F, -v name=value (implemented as a synthetic BEGIN assignment), -f, program string, then optional input files (stdin if none).\n\nBroadly supported: BEGIN/END, regex and expression patterns, print/printf with redirection to files, if/while/for/for (i in arr), arrays, next/exit, many builtins (length, substr, index, split, sprintf, sub/gsub, match, int, tolower/toupper, rand/srand), ENVIRON[\"VAR\"], user-defined function.\n\nKnown limitations: / in expressions is always a regex literal in the lexer (division is ambiguous in real awk — use spaces or refactor); getline from files is incomplete; print to files is queued and flushed per statement batch — fine for typical scripts but not identical to every awk I/O timing. Not gawk-compatible for extensions.\n\n8. COREUTILS BUILD: PREAMBLE MAP\n\nbuild.mjs <../packages/bare-os-coreutils/build.mjs> concatenates:\n\n1. lib/runtime.js\n2. Optional extra libs from the preamble map (sed → sed-engine.js, awk → awk-engine.js)\n3. src/<cmd>.js\n\nThere is still no import in *src/.js — large utilities are vendored as plain script chunks in lib/**.\n\n9. WHERE TO READ NEXT\n\n- Chapter 6 — Kernel and /bin summary <06-kernel-and-binaries.md>\n- Chapter 4 — Shell and VFS routing <04-the-booter-runtime.md>\n- Chapter 10 — Manual pages (man) and online help <10-manpages-and-online-help.md>\n- DOCUMENTATION.md §12.6–§12.10 <../DOCUMENTATION.md> — file-level inventory\n- bare-os-coreutils README <../packages/bare-os-coreutils/README.md> — build and command contract\n\n← Git on Bare OS <08-git-on-bare-os.md> · Handbook home <README.md> · Manual pages → <10-manpages-and-online-help.md>",
"descriptionMode": "preserve",
"options": [],
"keywords": [
"handbook",
"bare-os",
"documentation",
"narrative",
"chapter",
"09",
"posix",
"utilities",
"shell",
"and",
"vfs",
"style",
"builtins",
"alignment"
],
"seeAlso": [
{ "name": "handbook-10-manpages-and-online-help", "section": 7 },
{ "name": "handbook-08-git-on-bare-os", "section": 7 },
{ "name": "man", "section": 1 }
],
"bareOsNotes": "Generated at build time from handbook/09-posix-utilities-shell-and-vfs.md. Diagrams in ```mermaid blocks are omitted; open the Markdown in the repo for figures.",
"listCategory": "handbook"
},
{
"name": "handbook-10-manpages-and-online-help",
"section": 7,
"title": "Chapter 10 — Manual pages (man) and online help",
"synopsis": [
"man 7 handbook-10-manpages-and-online-help",
"Handbook chapter (plain text from handbook/10-manpages-and-online-help.md)"
],
"description": "CHAPTER 10 — MANUAL PAGES (MAN) AND ONLINE HELP\n\nBare OS ships a man(1)-style viewer backed by a JSON manual database on the system Hyperdrive, not troff, mandoc, or groff. This matches the project’s model: utilities are AsyncFunction scripts, and documentation must load without a host typesetter.\n\nPURPOSE\n\n- Familiar UX: Users expect man ls, man -k pattern (apropos), and man -f name (whatis).\n- Shippable: Pages live at /share/man/man.json (staged from kernel/share/man/man.json), merged at build time from *packages/bare-os-coreutils/man/pages/.json**.\n- Verifiable: The build fails if any /bin command from lib/commands.mjs <../packages/bare-os-coreutils/lib/commands.mjs> lacks a page.\n\nSession environment: many boot knobs are *BARE_OS_** variables copied from the host (HTTP policy, IPC token/fan-out, TLS pin list, audit, boot trace, …). The canonical list is in developer-guide §2 — The context object <../developer-guide/02-the-context-object.md> and packages/bare-os-booter/CHANGELOG.md <../packages/bare-os-booter/CHANGELOG.md>.\n\nSECTIONS\n\n| Section | Content |\n| 1 | User commands — every name in COREUTILS_COMMANDS, including man itself. |\n| 1 | bare-os-shell — one manual for all interactive shell builtins (cd, export, …), so we do not maintain dozens of one-line stubs. |\n| 7 | Handbook — every *handbook/.md file is merged at build time as man(7) (POSIX “miscellaneous”). TOC: man handbook or man 7 bare-os-handbook (alias handbook). Chapters: man handbook-01-introduction, man 7 handbook-02-blueprints, … mermaid** diagrams are omitted in the terminal view; open the Markdown in the repo for figures. |\n| 7 | Developer guide — every *developer-guide/.md file is merged the same way. TOC: man devguide or man 7 bare-os-developer-guide (aliases developer-guide, devguide). Chapters: man devguide-01-two-runtimes-host-vs-image**, … |\n\ngit is not a /bin script (it is delegated in the booter to git-cli.js), but it still has a section 1 page git in the same database.\n\nCLI SURFACE (/BIN/MAN)\n\n| Invocation | Behavior |\n| man | Short usage and pointer to man -l. |\n| man name | Show manual for name (any section if the name is unique, e.g. man ls or man handbook). |\n| man 1 name / man 7 name | Require that section; fails if the page lives in another section (e.g. man 7 ls fails). |\n| man -l | List every page under category headings (/bin, git/shell, handbook, developer guide), then name(section) alphabetically within each group. |\n| man -k word | Apropos: pages whose keywords / title / name match word (substring, case-insensitive). |\n| man -f name | Whatis: one-line name(section) - title for an exact name match. |\n\nEnvironment\n\n| Variable | Effect |\n| MANWIDTH | Wrap width for prose (default 72, minimum 40). |\n\nExit status\n\n| Code | Meaning |\n| 0 | Success (page shown or list empty for man -k with no matches). |\n| 1 | Page not found or man.json missing on the system drive. |\n| 2 | Invalid usage. |\n\nJSON PAGE MODEL\n\nAuthoritative schema: packages/bare-os-coreutils/man/schema.json <../packages/bare-os-coreutils/man/schema.json>.\n\nEach man/pages/<name>.json describes one page:\n\n- name, section, title — NAME header.\n- synopsis — string array (usage lines).\n- description — multi-sentence DESCRIPTION.\n- options — { \"flag\": string, \"meaning\": string }[].\n- environment, files — optional string arrays.\n- exitStatus, diagnostics — optional string arrays.\n- seeAlso — { \"name\": string, \"section\": number }[].\n- bareOsNotes — optional string; POSIX / GNU divergence.\n- keywords — lowercase tokens for man -k.\n- aliases — optional alternate lookup names (e.g. sh-builtins → bare-os-shell).\n- stub — if true, the command is a stub or intentionally limited.\n- examples — optional array of { \"caption\"?: string, \"code\": string } (cheat.sh–style: short label + copy-paste command; code may use newlines for multi-line snippets). Rendered under an EXAMPLES heading after OPTIONS. bare-os-shell builtins may also carry per-builtin examples with the same shape.\n- descriptionMode — \"wrap\" (default) or \"preserve\". Handbook pages use preserve so line breaks and tables stay readable.\n\nman -k also indexes caption text from examples so searches like “clone” can surface git.\n\nThe merged man.json adds schemaVersion, generatedAt, pages, index (name → page index), and apropos (keyword → page indices) for fast lookup.\n\nBUILD PIPELINE\n\n1. npm run build -w bare-os-coreutils runs build.mjs, which calls scripts/build-man-db.mjs.\n2. build-man-db.mjs loads every man/pages/<cmd>.json for COREUTILS_COMMANDS, plus git.json and bare-os-shell.json, then scripts/ingest-handbook-for-man.mjs appends one man(7) page per *handbook/.md (Markdown → plain text). It validates everything, then writes kernel/share/man/man.json and mirrors to packages/bare-os-seeder/kernel/share/man/man.json**.\n3. The seeder stages kernel/ recursively; paths under kernel/share/... become /share/... on the system drive (packages/bare-os-seeder/index.js <../packages/bare-os-seeder/index.js>).\n4. /bin/man reads ctx.drive.get('/share/man/man.json'). There is no embedded fallback in v1 — the image must include the merged file.\n\nRELATIONSHIP TO HELP\n\n/bin/help prints a compact one-screen list of builtins and /bin names. man is the long-form reference. Users are encouraged to run man handbook for the full narrative handbook, man bare-os-shell for builtins, and man <command> for /bin utilities.\n\nAUTHORING WORKFLOW\n\n1. Add or edit packages/bare-os-coreutils/man/pages/<name>.json.\n2. Run npm run build -w bare-os-coreutils (or node packages/bare-os-coreutils/scripts/build-man-db.mjs).\n3. If a new /bin command is added, add name.json, add the name to lib/commands.mjs, and extend src/<name>.js — the build will fail until the page exists.\n\nFUTURE WORK\n\n- Interactive PAGER (keypress paging on TTY) beyond PAGER=bare-slice section breaks.\n- man -w is implemented (prints /share/man/man.json); per-page anchor paths remain future work.\n- HTML export for Pear / browser shells.\n- Section 7 overview pages and i18n.\n\n← Chapter 9 — POSIX utilities, shell, VFS <09-posix-utilities-shell-and-vfs.md> · Handbook home <README.md>",
"descriptionMode": "preserve",
"options": [],
"keywords": [
"handbook",
"bare-os",
"documentation",
"narrative",
"chapter",
"10",
"manpages",
"and",
"online",
"help",
"manual",
"pages",
"man"
],
"seeAlso": [
{ "name": "handbook-09-posix-utilities-shell-and-vfs", "section": 7 },
{ "name": "man", "section": 1 }
],
"bareOsNotes": "Generated at build time from handbook/10-manpages-and-online-help.md. Diagrams in ```mermaid blocks are omitted; open the Markdown in the repo for figures.",
"listCategory": "handbook"
},
{
"name": "bare-os-developer-guide",
"section": 7,
"title": "Bare OS developer guide — index and reading order",
"synopsis": [
"man 7 bare-os-developer-guide",
"Developer guide chapter (developer-guide/README.md)"
],
"description": "BARE OS — DEVELOPER GUIDE\n\nWelcome. This guide is the how-to companion for writing software on and for Bare OS: scripts that run inside the replicated system image, utilities under /bin, the session kernel, and—when you need full JavaScript modules—the host Pear packages that implement the booter and seeder.\n\nThe handbook <../handbook/README.md> explains _why_ the system is shaped the way it is (Hyperdrive, two drives, swarm boot). The DOCUMENTATION.md <../DOCUMENTATION.md> inventory lists _where_ every file lives. This guide focuses on _what you actually type_: entrypoint signatures, the ctx object, why import does not work in drive-resident scripts, and how the coreutils build turns sources into /bin commands.\n\nThis project is experimental research software. APIs described here follow the current code in packages/bare-os-booter and packages/bare-os-coreutils; when in doubt, read the cited paths.\n\nctx API versions: see packages/bare-os-booter/CHANGELOG.md <../packages/bare-os-booter/CHANGELOG.md> for bareOsCtxApiVersion history and booter alignment. TypeScript-oriented authors can reference lib/bare-os-ctx.d.ts <../packages/bare-os-booter/lib/bare-os-ctx.d.ts>.\n\nWHO THIS IS FOR\n\n- You want to drop a hello.js on your personal drive and run it from the shell without misunderstanding the execution model.\n- You plan to add or change a /bin utility and need the no-import contract and build steps.\n- You are modifying the booter or seeder Pear apps and need to separate “host ESM” from “in-image AsyncFunction.”\n- You are debugging async function run(ctx, argv) or start(ctx) and need a map of ctx.\n\nREADING ORDER\n\n| Chapter | Topic |\n| 01 — Two runtimes: host vs in-image <01-two-runtimes-host-vs-image.md> | Pear/Node packages vs Hyperdrive JS evaluated with AsyncFunction; trust boundaries |\n| 02 — The context object (ctx) <02-the-context-object.md> | vfs, drive, console, identity hooks, execLine, runBinCommand, … |\n| 03 — Kernel: /boot/init.js <03-kernel-boot-init.md> | async function start(ctx); readline loop; calling the shell |\n| 04 — User scripts and PATH resolution <04-user-scripts-and-path.md> | run(ctx, argv), shebangs, *.js in cwd, ./ paths, /bin |\n| 05 — Modules and import <05-modules-and-imports.md> | Why ESM does not apply to in-image scripts; bundling and alternatives |\n| 06 — Extending /bin (coreutils) <06-extending-bin-coreutils.md> | commands.mjs, build.mjs, preamble, man pages |\n| 07 — Apps beyond the shell <07-apps-beyond-the-shell.md> | What an “app” means here; initd, cron, git, custom kernels (overview) |\n| 08 — Testing and debugging <08-testing-and-debugging.md> | npm test, Brittle, Pear dev, common failure modes |\n| 09 — Security and trust <09-security-and-trust.md> | System vs personal drive; eval boundaries |\n| 10 — Glossary and FAQ <10-glossary-and-faq.md> | Quick definitions; frequent questions |\n| 11 — Kernel + Pear cookbook <11-kernel-pear-cookbook.md> | Boot allowlist, timers, socket IPC, vfs.watch, HDMS hooks, Git-in-Pear, release metadata |\n\nRELATED DOCS\n\n- Handbook home <../handbook/README.md>\n- Chapter 4 — Booter runtime <../handbook/04-the-booter-runtime.md>\n- Chapter 6 — Kernel and binaries <../handbook/06-kernel-and-binaries.md>\n- Chapter 7 — Operations and development <../handbook/07-operations-and-development.md>\n- Chapter 9 — POSIX utilities and shell <../handbook/09-posix-utilities-shell-and-vfs.md>\n- Chapter 11 — Kernel + Pear cookbook <11-kernel-pear-cookbook.md>\n- bare-os-coreutils README <../packages/bare-os-coreutils/README.md>\n- bare-os-booter README <../packages/bare-os-booter/README.md>\n\n_License: Apache-2.0 — see LICENSE <../LICENSE>._",
"descriptionMode": "preserve",
"options": [],
"keywords": [
"developer",
"devguide",
"develop",
"script",
"asyncfunction",
"ctx",
"bare-os",
"guide",
"bare",
"os",
"index",
"and",
"reading",
"order"
],
"seeAlso": [
{ "name": "devguide-01-two-runtimes-host-vs-image", "section": 7 },
{ "name": "man", "section": 1 },
{ "name": "bare-os-handbook", "section": 7 }
],
"bareOsNotes": "Generated at build time from developer-guide/README.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.",
"aliases": ["developer-guide", "devguide"],
"listCategory": "devguide"
},
{
"name": "devguide-01-two-runtimes-host-vs-image",
"section": 7,
"title": "Chapter 1 — Two runtimes: host (Pear/Node) vs in-image (AsyncFunction)",
"synopsis": [
"man 7 devguide-01-two-runtimes-host-vs-image",
"Developer guide chapter (developer-guide/01-two-runtimes-host-vs-image.md)"
],
"description": "CHAPTER 1 — TWO RUNTIMES: HOST (PEAR/NODE) VS IN-IMAGE (ASYNCFUNCTION)\n\nIf you only remember one thing from this guide, remember this: Bare OS runs two different kinds of JavaScript, and they follow different rules.\n\nTHE CONFUSION IN ONE SENTENCE\n\nYou might paste a file into your home directory on the personal Hyperdrive that starts with import fs from 'node:fs' and expect it to run like a Node script. It will not. That file is loaded as a string and executed with the JavaScript AsyncFunction constructor—not as an ES module. There is no module graph, no import resolution, and no automatic node_modules on the drive.\n\nThe booter and seeder Pear packages, by contrast, are normal ESM projects: they use import, npm dependencies, and Pear bundling. They run on the host and _host_ the environment that evaluates in-image code.\n\nWhen the bare-os npm module is available on that host, the booter may attach a read-only ctx.bareOsHostStats snapshot (loadavg, cpus, networkInterfaces, …)—still not a general “run Node in the image” escape hatch; see Chapter 2 <02-the-context-object.md>.\n\nMENTAL MODEL: WHO LOADS WHOM\n\n- Host code lives under packages/bare-os-booter/, packages/bare-os-seeder/, etc. It is trusted in the sense that you built or installed it; it opens Corestore, Hyperswarm, Hyperdrive, and constructs ctx.\n- In-image code is bytes on a drive (/boot/init.js, /bin/cat, ~/mytool.js). The booter reads those bytes as UTF-8 strings and passes them to new AsyncFunction(...) (see kernel-runner.js <../packages/bare-os-booter/lib/kernel-runner.js>).\n\nIN-IMAGE EXECUTION (THE ASYNCFUNCTION CONTRACT)\n\nTwo entry shapes matter:\n\n| Entry | Where it lives | Parameters | How it is invoked |\n| async function start(ctx) | /boot/init.js on the system drive | ctx | runKernelFromSource wraps the source and calls start(ctx) |\n| async function run(ctx, argv) | /bin/, or a .js file resolved from the shell | ctx, argv (string array) | runScriptFromSource wraps the source and calls run(ctx, argv) |\n\nThe booter injects ctx and argv; your source file must define the named function. Top-level import is invalid in that evaluated string because the engine is not loading an ES module—it is compiling a function body.\n\nShebang lines (#!/usr/bin/env bare) are stripped before compile (stripShebang <../packages/bare-os-booter/lib/kernel-runner.js>) so the first token the parser sees is valid JavaScript.\n\nHOST EXECUTION (PEAR / NODE PACKAGES)\n\nWhen you edit packages/bare-os-booter/index.js, you are writing normal JavaScript for Node or Bare under Pear:\n\n- Use import Hyperdrive from 'hyperdrive'.\n- Add dependencies in package.json.\n- Use async I/O against real host APIs.\n\nWeb Encoding globals: some Bare/Pear builds do not define global TextEncoder / TextDecoder. Booter and in-image code should use b4a for UTF-8 instead (e.g. b4a.from(str, 'utf8'), b4a.toString(buf, 'utf8')), matching curl-cli.js <../packages/bare-os-booter/lib/curl-cli.js>. Relying on new TextEncoder() in booter lib/*.js can break at runtime (for example when statting or reading pseudo files under /proc or /sys).\n\nThis code creates ctx and passes it into the kernel. It does not run inside the simulated /bin environment unless you explicitly call runBinCommand(ctx, argv) with the same ctx the shell uses.\n\nTRUST: SYSTEM DRIVE VS PERSONAL DRIVE\n\n- The system drive is the replicated OS image: /boot, /bin, /etc, /share. You should treat its contents as integrity-checked by replication from peers you chose to trust (same discovery key / topic as the rest of the project).\n- The personal drive holds $HOME, /.bare, user files, crontab, etc. It is writable by the session. User scripts you write live here by default.\n\nA script you place in ~/exploit.js is your code; the booter will still AsyncFunction-evaluate it with full ctx power. That is convenient and dangerous—see Chapter 9 <09-security-and-trust.md>.\n\nWHEN TO USE WHICH RUNTIME\n\n| Goal | Use |\n| Add a new /bin command shipped with the OS image | In-image pattern: coreutils src/*.js + build (Chapter 6) |\n| One-off automation in your home directory | In-image run(ctx, argv) script; no import (Chapters 4–5) |\n| Change how networking, HDMS, or the REPL works | Host booter package (ESM) |\n| Publish or replicate the system image | Host seeder package |\n\nSEE ALSO\n\n- Chapter 2 — The context object <02-the-context-object.md>\n- Handbook — Booter runtime <../handbook/04-the-booter-runtime.md>\n- Handbook — Kernel and binaries <../handbook/06-kernel-and-binaries.md>\n\n← Developer guide home <README.md> · Context object → <02-the-context-object.md>",
"descriptionMode": "preserve",
"options": [],
"keywords": [
"developer",
"devguide",
"develop",
"script",
"asyncfunction",
"ctx",
"bare-os",
"guide",
"01",
"two",
"runtimes",
"host",
"vs",
"image",
"chapter",
"pear",
"node"
],
"seeAlso": [
{ "name": "devguide-02-the-context-object", "section": 7 },
{ "name": "bare-os-developer-guide", "section": 7 },
{ "name": "man", "section": 1 },
{ "name": "bare-os-handbook", "section": 7 }
],
"bareOsNotes": "Generated at build time from developer-guide/01-two-runtimes-host-vs-image.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.",
"listCategory": "devguide"
},
{
"name": "devguide-02-the-context-object",
"section": 7,
"title": "Chapter 2 — The context object (ctx)",
"synopsis": [
"man 7 devguide-02-the-context-object",
"Developer guide chapter (developer-guide/02-the-context-object.md)"
],
"description": "CHAPTER 2 — THE CONTEXT OBJECT (CTX)\n\nEvery in-image entrypoint—start(ctx) for the kernel or run(ctx, argv) for commands—receives a single ctx object assembled by the booter before runKernelFromSource or runScriptFromSource runs. This chapter maps the fields you can rely on, how they behave, and where they are defined in source.\n\nAuthoritative construction happens in packages/bare-os-booter/index.js <../packages/bare-os-booter/index.js> inside executeKernel, then a few fields are replaced or augmented when the REPL session is created (readLine, console, execLine, writeScreen).\n\nDESIGN GOAL\n\nctx is the narrow interface between:\n\n- the host (Hyperdrive handles, swarm, identity, stdio adapters), and\n- unprivileged-looking session code (kernel loop, /bin utilities, user scripts).\n\nIt is intentionally not a full Node process object. Think of it as the “syscall table” for Bare OS userland.\n\nSTABLE FIELDS (TYPICAL SESSION)\n\nThe following are set on ctx before the kernel starts (unless noted as overwritten later):\n\n| Field | Role |\n| bareOsCtxApiVersion | String semver for the documented ctx contract (e.g. 1.5.0). Bump in bare-os-ctx-api.js <../packages/bare-os-booter/lib/bare-os-ctx-api.js> when you make breaking changes to stable fields. |\n| bareOsRuntimeCaps | Frozen snapshot from bare-os-runtime-caps.js <../packages/bare-os-booter/lib/bare-os-runtime-caps.js>: ctxApiVersion, simulated pipeline limits, pseudoFsPaths, and features (including jobControl, shellHereString, bootReadyPseudoFs, vfsChown, auditLog, initdRequiresWants, seederRpcExtended, …). |\n| bareOsPublishBootReady(patch) | Kernel-only: merge patch into the session boot-ready state exposed as /run/bare-os/boot.json and /run/bare-os/ready. The booter pre-seeds imageDigest, pearChannel, pearRelease from host env when set (see BARE_OS_IMAGE_DIGEST, BARE_OS_PEAR_CHANNEL, BARE_OS_PEAR_RELEASE, PEAR_CHANNEL). |\n| bareOsSessionStats | Mutable { execLineCount, pipelineBytesTotal } mirrored in /proc/bare_os_session_stats. |\n| bareOsBootStartedMs | Epoch milliseconds when the booter started building the session (used for synthetic /proc/uptime). |\n| bareOsSkipRepl | true when BARE_OS_SKIP_REPL=1 (non-interactive stdin); kernels may shorten banners. |\n| disk | Disk bundle used during boot (includes drives and helpers); advanced use |\n| drive | System Hyperdrive (ctx.drive is the OS image: /bin, /boot, …) |\n| personalDrive | Personal Hyperdrive (mutable per-user state; VFS maps $HOME to /.bare-os/home/<HOME-basename>/… and session /var/log to /.bare-os/var/log/<basename>/… so guest vs unlocked trees do not share the same keys) |\n| vfs | Path layer: resolves logical paths, routes to system vs personal drive, implements mkdir, readFile, etc. See vfs.js <../packages/bare-os-booter/lib/vfs.js> |\n| env | Shell environment object (HOME, PATH, USER, …), same object as vfs.env. Mutated by builtins (export, cd updates PWD, identity unlock updates user fields). After each execLine, BARE_OS_EXIT_STATUS holds the last command’s exit code as a decimal string (POSIX $? parity); use $? or ${?} in shell words for expansion. |\n| b4a | b4a module (byte helpers); used to convert Hyperdrive buffers to strings |\n| topic | Topic key helper from protocol package (rarely needed in user scripts) |\n| console | Initially the raw global; replaced with session-bound log/error that respect the REPL and fish-style UI |\n| readLine | Placeholder async function; replaced with session readLine(prompt) that reads a line from stdin (or returns null when session ends) |\n| writeScreen | REPL helper for screen-oriented output; starts as no-op, then wired |\n| runHdms(argv) | Entry for hdms CLI when HDMS controller is active |\n| onIdentityUnlocked / onIdentityGuest | Hooks for HDMS lifecycle (bootstrap nodes, teardown) |\n| requestBooterExit(code) | Ends the session from /bin/exit or equivalent |\n| applyUnlock / applyRegister / applyLogin / applyLogout / saveVault | Identity and vault operations used by login, logout, savevault |\n| shellAliases | Populated when the shell loads default or ~/.barerc aliases |\n| runBinCommand(argv) | Runs a command with the same resolution rules as the interactive shell (used by time, xargs, and similar) |\n| registerKernelShutdownHook(fn) | Register an async or sync function to run when the REPL session ends, before stopBareInitd and initd disposers. Pair with registerBareInitdDisposer(fn) in bare-initd.js <../packages/bare-os-booter/lib/bare-initd.js> when you need teardown after shutdown hooks but still inside stopBareInitd (intervals, sync cleanup). |\n| bareOsSubscribeBootEvent(fn) / bareOsEmitBootEvent(ev) | Subscribe to or emit structured boot lifecycle events (same shape as BARE_OS_BOOT_TRACE=ndjson records). |\n| bareOsSubscribeHdmsLifecycle(fn) | After HDMS activate / before deactivate, run callbacks with { kind, labels? }. |\n| bareOsAwaitInitdUnits(names, timeoutMs) | Resolves when all listed initd units are active (polls getBareServiceRuntime); returns false on timeout. |\n| bareOsGetResourceStatus() | Returns a plain object snapshot (pipeline limits, exec depth, IPC stats(), session counters, swarm peer count)—mirrors /proc/bare_os_resources. |\n| bareOsRegisterVirtualFile(name, reader) | Registers /run/bare-os/virtual/<name> content; reader may return string or Uint8Array (sync or async). Gated by runtime cap virtualRegisterFiles. |\n| bareOsSandboxRunScript() | Throws today—reserved for future worker/isolate execution; see Chapter 9 <09-security-and-trust.md>. |\n| bareOsRequestPearReload() | Returns { requested, hint, env } for Pear OTA integration (host must apply); not a host IPC call by itself. |\n| bareOsHostStats _(optional)_ | When the bare-os npm module loads on the host, a frozen snapshot: hostname, loadavg, cpus, networkInterfaces. |\n| httpFetch _(optional)_ | When Node/global fetch exists, the booter sets a fetch compatible function with optional HTTP allow/deny policy (BARE_OS_HTTP_ALLOWLIST, BARE_OS_HTTP_DENYLIST) and audit hooks when BARE_OS_AUDIT is on. |\n\nKernel boot composition lives on the system image (/boot/init.js, /etc/bare-os/rc, /etc/bare-os/rc.d/, optional /etc/bare-os/rc.local, optional /etc/bare-os/kernel.d/ (same digit-prefix rules as rc.d), optional /etc/bare-os/profile / *rc.profile., /etc/bare-os/onboot), not on ctx—extend the image or hooks like registerKernelShutdownHook rather than adding boot fields to the context object. The booter seeds ctx.env from the host for BARE_OS_PIPELINE_, 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 (set to 0 to disable fan-out), BARE_OS_IPC_JSON_MAX_BYTES, BARE_OS_HTTP_ALLOWLIST, BARE_OS_HTTP_DENYLIST, BARE_OS_TLS_PIN_SHA256 (comma-separated SHA-256 hints for delegated TLS; host httpFetch may honor init.bareOsCurlTls.pinnedSha256), BARE_OS_VFS_WATCH, BARE_OS_IMAGE_DIGEST, BARE_OS_PEAR_CHANNEL, BARE_OS_PEAR_RELEASE, and PEAR_CHANNEL when set; always sets BARE_OS_BOOT_PROFILE_RESOLVED and BARE_OS_SESSION_ID. When ctx.httpFetch handles curl, check optional init.bareOsCurlTls (insecure, caPem, pinnedSha256) for --cacert / -k* semantics.\n\nAfter createVfs <../packages/bare-os-booter/lib/vfs.js>, ctx.vfs.watch(logicalPath) returns a Hyperdrive watcher when BARE_OS_VFS_WATCH is not disabled. ctx.bareOsIpc exposes FIFO push/take, optional JSON-RPC pushJson/takeJson (max line size, optional RPC token), fanoutPublish/fanoutSubscribe, and stats (see bare-os-ipc.js <../packages/bare-os-booter/lib/bare-os-ipc.js>).\n\nAfter createKernelReplSession <../packages/bare-os-booter/lib/repl-session.js> returns:\n\n- ctx.execLine(line, opts?) runs a full shell line (tokenize, builtins, pipelines, /bin resolution). Optional opts: { signal?: AbortSignal, timeoutMs?: number } (deadline for the shell pipeline work).\n- ctx.readLine(prompt, opts?) prompts and reads user input; same optional opts for abort/timeout.\n- ctx.runBinCommand(argv, opts?) passes through abort/timeout to the delegated command runner.\n- ctx.vfs.readFile(path, opts?) and ctx.vfs.writeFile(path, buf, opts?) accept signal/timeoutMs in opts (writeFile merges with executable).\n- ctx.console is session-scoped.\n\n/run/bare-os/boot.json (via bareOsPublishBootReady) may include booterPhases: booter milestones (vfs, ctx, repl, initd, kernel_invoke) in addition to kernel phases from the stock kernel/init.js <../kernel/init.js>.\n\nFIELDS INTRODUCED DURING COMMAND EXECUTION\n\nWhen the shell runs an external command (or a pipeline stage), it may pass a shallow clone of ctx with extra fields:\n\n| Field | When |\n| shellStdin | String body for simulated stdin (pipelines and < redirection) |\n| exitCode | Utilities set ctx.exitCode for conditions (test, grep, …); the shell uses it for &&, logical OR lists, and ; sequencing (see shell.js <../packages/bare-os-booter/lib/shell.js>) |\n\nAlways use the ctx passed into run, not a global, so pipeline stdin works.\n\nWHAT IS _NOT_ ON CTX\n\n- No require, no import helper—the in-image script is not a CommonJS or ESM module.\n- No automatic fetch guarantee—depends on host/Pear globals; do not rely on it for portable /bin utilities.\n- process may exist on Bare/Node hosts but do not depend on it for utilities meant to run identically under Pear; use ctx.console and ctx.env.\n- bare-initd control is not a ctx method: use /bin/systemctl (or journalctl; bare-initctl is a legacy alias), which the booter handles via delegation—same pattern as git / curl.\n\nMINIMAL PATTERNS\n\nLog a message\n\n async function run(ctx, argv) {\n ctx.console.log('argv:', argv.join(' '))\n }\n\nRead a file via VFS\n\n async function run(ctx, argv) {\n const buf = await ctx.vfs.readFile(argv[1] || 'README.md')\n if (!buf) {\n ctx.console.error('missing file')\n return\n }\n ctx.console.log(ctx.b4a.toString(buf))\n }\n\nRun another command programmatically\n\n async function run(ctx, argv) {\n await ctx.runBinCommand(['ls', '-la', ctx.env.HOME || '.'])\n }\n\nSEE ALSO\n\n- Chapter 3 — Kernel <03-kernel-boot-init.md>\n- Chapter 4 — User scripts <04-user-scripts-and-path.md>\n- Handbook — Identity and vault <../handbook/05-identity-vault-and-hdms.md>\n\n← Two runtimes <01-two-runtimes-host-vs-image.md> · Kernel → <03-kernel-boot-init.md>",
"descriptionMode": "preserve",
"options": [],
"keywords": [
"developer",
"devguide",
"develop",
"script",
"asyncfunction",
"ctx",
"bare-os",
"guide",
"02",
"the",
"context",
"object",
"chapter"
],
"seeAlso": [
{ "name": "devguide-03-kernel-boot-init", "section": 7 },
{ "name": "devguide-01-two-runtimes-host-vs-image", "section": 7 },
{ "name": "man", "section": 1 },
{ "name": "bare-os-handbook", "section": 7 }
],
"bareOsNotes": "Generated at build time from developer-guide/02-the-context-object.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.",
"listCategory": "devguide"
},
{
"name": "devguide-03-kernel-boot-init",
"section": 7,
"title": "Chapter 3 — Kernel: /boot/init.js and start(ctx)",
"synopsis": [
"man 7 devguide-03-kernel-boot-init",
"Developer guide chapter (developer-guide/03-kernel-boot-init.md)"
],
"description": "CHAPTER 3 — KERNEL: /BOOT/INIT.JS AND START(CTX)\n\nThe kernel in Bare OS is not a microkernel and not a scheduler. It is a JavaScript file on the system Hyperdrive at /boot/init.js, loaded as UTF-8 text and executed with runKernelFromSource in kernel-runner.js <../packages/bare-os-booter/lib/kernel-runner.js>. The booter expects a top-level:\n\n async function start(ctx) {\n // ...\n }\n\nThere is no argv at the kernel layer—the session’s command line is whatever the interactive user types after boot, handled through ctx.readLine and ctx.execLine.\n\nWHAT THE STOCK KERNEL DOES\n\nThe repository’s default kernel (kernel/init.js <../kernel/init.js>) is intentionally small:\n\n1. Print /etc/os-release and optional /etc/motd (errors logged, not fatal).\n2. Optional profile snippet /etc/bare-os/rc.profile.<name> when BARE_OS_BOOT_PROFILE or the first line of /etc/bare-os/profile names a safe profile string.\n3. Run /etc/bare-os/rc, then sorted digit-prefixed */etc/bare-os/rc.d/, then optional /etc/bare-os/rc.local, then sorted digit-prefixed /etc/bare-os/kernel.d/ (same naming rules as rc.d*) (see Handbook ch.6 <../handbook/06-kernel-and-binaries.md>).\n4. Print session banner (from /etc/bare-os/banner, /etc/issue, or a built-in hint).\n5. If ctx.bareOsSkipRepl: run every non-empty, non-# line from BARE_OS_ONBOOT (newline-separated), or if that env is unset, the same from /etc/bare-os/onboot in file order, via execLine; then fall through to the loop (where readLine returns null immediately).\n6. Loop forever:\n- line = await ctx.readLine('')\n- If line == null, break (session end / EOF).\n- Skip empty lines.\n- status = await ctx.execLine(line) inside try/catch (console.error on failure).\n- If status === 'exit', break.\n\nSet BARE_OS_BOOT_TRACE=1 (or true) in the environment to log boot phase timings on stderr as [boot] phase: Nms. Use BARE_OS_BOOT_TRACE=json for one JSON object per phase ({\"phase\":\"…\",\"ms\":n}) on stderr. The same phases are also delivered to ctx.bareOsSubscribeBootEvent subscribers as NDJSON-shaped objects. The booter emits additional *booter: phases (vfs, ctx, repl, initd, kernel_invoke) and records them under booterPhases in /run/bare-os/boot.json. BARE_OS_BOOT_ALLOWLIST=1 with /etc/bare-os/boot.allow restricts the first token of lines in trusted rc/onboot snippets. Inspect ctx.bareOsRuntimeCaps for pipeline limits, quotas, pseudo paths, and features (including httpDelegate, gitDelegate, systemctlDelegate, vfsWatch, ipcFanout**).\n\nOptional BARE_OS_KERNEL_SELFTEST=1 runs built-in checks after boot snippets (add BARE_OS_SELFTEST_FORMAT=tap for CI). You can pass { signal, timeoutMs } as a second argument to ctx.execLine, ctx.readLine, ctx.runBinCommand, and VFS readFile/writeFile for bounded waits—see Chapter 2 <02-the-context-object.md>.\n\nSo the “OS personality” is mostly the shell (execShellLine behind execLine) plus /bin.\n\nWHY READLINE USES AN EMPTY PROMPT STRING\n\nThe stock kernel passes '' as the prompt. The actual prompt rendering (fish-style or plain) is owned by the REPL session implementation in repl-session.js <../packages/bare-os-booter/lib/repl-session.js>. If you build a custom kernel, you can pass a different prompt string, but many sessions ignore it in favor of their own UI.\n\nUSING EXECLINE VS CALLING RUNBINCOMMAND DIRECTLY\n\n| API | Behavior |\n| await ctx.execLine('ls -la') | Full shell semantics: tokenization, aliases, builtins (cd, export, …), ; / && / logical-OR lists, pipelines, redirections, then /bin |\n| await ctx.runBinCommand(['ls', '-la']) | Direct utility invocation—no shell parsing, no aliases |\n\nUse execLine when you want users to type natural shell commands from your kernel loop. Use runBinCommand when you already have an argv array and want to avoid re-parsing.\n\nSESSION TERMINATION\n\n- The exit builtin (or /bin/exit) ultimately calls ctx.requestBooterExit(code), which forces readLine to return null on subsequent calls and ends the loop.\n- BARE_OS_SKIP_REPL=1 makes readLine return null immediately—useful for non-interactive smoke tests. Pair with BARE_OS_ONBOOT (one or more newline-separated lines) or /etc/bare-os/onboot so the stock kernel runs trusted execLine snippets before idle exit.\n\nCUSTOM KERNELS: PRACTICAL TIPS\n\n1. Keep the loop async—never block on synchronous host APIs that might hang the Pear app.\n2. Catch errors around execLine so a typo does not tear down the whole session unless you want that.\n3. Do not assume import—the kernel source is the same AsyncFunction model as /bin (Chapter 1).\n4. To add startup services, prefer hooks already wired in the booter (startBareInitd) or a small kernel that calls runBinCommand after banner—see Chapter 7 <07-apps-beyond-the-shell.md>.\n5. To run code when the session ends, use ctx.registerKernelShutdownHook(fn) (runs before initd disposers); see Chapter 2 — ctx <02-the-context-object.md>.\n6. After login, ~/.barerc is reloaded automatically via applyUnlockedEnv—see Handbook — Identity <../handbook/05-identity-vault-and-hdms.md>. The stock init.js does not re-print the boot banner; use onIdentityUnlocked or a custom kernel loop if you want that.\n\nREPLACING THE KERNEL IN THE IMAGE\n\nKernel text is staged from the repo’s kernel/ tree when you run the seeder (or copied into packages/bare-os-seeder/kernel/ for Pear). After editing kernel/init.js, re-seed or rebuild the vendored tree so peers receive the new /boot/init.js.\n\nSEE ALSO\n\n- Chapter 2 — ctx <02-the-context-object.md>\n- Chapter 4 — User scripts <04-user-scripts-and-path.md>\n- Handbook — Kernel and binaries <../handbook/06-kernel-and-binaries.md>\n\n← Context object <02-the-context-object.md> · User scripts → <04-user-scripts-and-path.md>",
"descriptionMode": "preserve",
"options": [],
"keywords": [
"developer",
"devguide",
"develop",
"script",
"asyncfunction",
"ctx",
"bare-os",
"guide",
"03",
"kernel",
"boot",
"init",
"chapter",
"and",
"start"
],
"seeAlso": [
{ "name": "devguide-04-user-scripts-and-path", "section": 7 },
{ "name": "devguide-02-the-context-object", "section": 7 },
{ "name": "man", "section": 1 },
{ "name": "bare-os-handbook", "section": 7 }
],
"bareOsNotes": "Generated at build time from developer-guide/03-kernel-boot-init.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.",
"listCategory": "devguide"
},
{
"name": "devguide-04-user-scripts-and-path",
"section": 7,
"title": "Chapter 4 — User scripts and PATH resolution",
"synopsis": [
"man 7 devguide-04-user-scripts-and-path",
"Developer guide chapter (developer-guide/04-user-scripts-and-path.md)"
],
"description": "CHAPTER 4 — USER SCRIPTS AND PATH RESOLUTION\n\nThis chapter is the practical “how do I run my own .js file?” guide. Resolution logic lives in runBinCommand in kernel-runner.js <../packages/bare-os-booter/lib/kernel-runner.js>; the shell calls that function for non-builtin commands.\n\nTHE ENTRYPOINT CONTRACT (AGAIN)\n\nYour script file must define:\n\n async function run(ctx, argv) {\n // argv[0] is conventionally the script name or command word\n }\n\nThe booter wraps the file body in:\n\n new AsyncFunction(\n 'ctx',\n 'argv',\n source + '\\nif (typeof run !== \"function\") throw ...\\nreturn run(ctx, argv)\\n'\n )\n\nSo run must exist at the top level of the evaluated string—same as /bin utilities.\n\nRESOLUTION ORDER (SIMPLIFIED)\n\nWhen the user types a command, roughly:\n\n1. Git delegation — If the command is git (and not ./git), the booter runs the hosted git CLI instead of /bin/git bytes.\n2. Path with slash — If argv[0] contains /, treat as a path: resolve via ctx.vfs, read bytes from the routed drive, evaluate as script.\n3. Ends with .js — Resolve cmd as a logical path (e.g. foo.js in $PWD), read from VFS if found, evaluate.\n4. PATH search — For each directory in $PATH (default /bin), try unixPathResolve(dir, cmd) on the system drive only; first hit wins.\n\nImplications:\n\n- ./my.js and /home/user/my.js use VFS (personal or system as appropriate).\n- hello.js in the current directory is tried before /bin if the file exists on the routed drive.\n- ls resolves to /bin/ls on the system drive (unless shadowed by a same-named *.js in cwd—know this edge case).\n\nSHEBANG\n\nA leading line like #!/usr/bin/env bare is stripped before compilation. It is for human readers and future tooling; the booter does not exec a binary interpreter—it always uses AsyncFunction.\n\nSTDIN IN PIPELINES\n\nThe shell does not give your script a POSIX fd 0. For pipeline stages, stdin is simulated: the shell captures console.log output from the left stage as a string and passes ctx.shellStdin on a cloned ctx to the right stage. Utilities that want stdin read bareStdin(ctx) from the coreutils prelude—but user scripts on the home drive do not get that prelude unless you copy the helper into your file.\n\nMinimal stdin read in a user script:\n\n async function run(ctx, argv) {\n const stdin = typeof ctx.shellStdin === 'string' ? ctx.shellStdin : ''\n ctx.console.log('got bytes:', stdin.length)\n }\n\nENVIRONMENT AND CD\n\n- ctx.env is the same object mutated by export and cd (via vfs.chdir and PWD).\n- Paths like ~/doc are expanded by the VFS when you use vfs.readFile and friends—prefer ctx.vfs over raw drive access for user-level scripts.\n\nGIT AND SPECIAL CASES\n\n- Prefer the git command for version control; it is not the same as evaluating /bin/git as JS.\n- command -v / type use resolveBinInPath (system drive PATH only) plus builtin tables.\n\nDEBUGGING “NOT FOUND”\n\n1. unknown command: foo — Not in PATH on system drive and not a resolvable *.js / path.\n2. not found: ./foo.js — VFS could not read the path (typo, wrong drive, or missing file).\n3. Silent failure with stack in console.error — Runtime error inside run; fix the script logic.\n\nSEE ALSO\n\n- Chapter 5 — Modules <05-modules-and-imports.md>\n- Chapter 6 — Extending /bin <06-extending-bin-coreutils.md>\n- Handbook — POSIX utilities <../handbook/09-posix-utilities-shell-and-vfs.md>\n\n← Kernel <03-kernel-boot-init.md> · Modules → <05-modules-and-imports.md>",
"descriptionMode": "preserve",
"options": [],
"keywords": [
"developer",
"devguide",
"develop",
"script",
"asyncfunction",
"ctx",
"bare-os",
"guide",
"04",
"user",
"scripts",
"and",
"path",
"chapter",
"resolution"
],
"seeAlso": [
{ "name": "devguide-05-modules-and-imports", "section": 7 },
{ "name": "devguide-03-kernel-boot-init", "section": 7 },
{ "name": "man", "section": 1 },
{ "name": "bare-os-handbook", "section": 7 }
],
"bareOsNotes": "Generated at build time from developer-guide/04-user-scripts-and-path.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.",
"listCategory": "devguide"
},
{
"name": "devguide-05-modules-and-imports",
"section": 7,
"title": "Chapter 5 — Modules, import, and packaging (the honest version)",
"synopsis": [
"man 7 devguide-05-modules-and-imports",
"Developer guide chapter (developer-guide/05-modules-and-imports.md)"
],
"description": "CHAPTER 5 — MODULES, IMPORT, AND PACKAGING (THE HONEST VERSION)\n\nThis chapter answers the most common disappointment: “Why can’t I use import in my Bare OS script?”\n\nSHORT ANSWER\n\nIn-image scripts (/boot/init.js, /bin/*, ~/tool.js) are executed as AsyncFunction bodies, not as ES modules. The JavaScript engine never runs the ESM loader for those strings. Therefore:\n\n- import x from 'y' is a syntax error in that context (top-level import is only valid in modules).\n- require is likewise unavailable unless the host injected a global (do not rely on it for portable utilities).\n\nHOW /BIN UTILITIES STILL SHARE CODE\n\nThe bare-os-coreutils build concatenates:\n\n1. lib/runtime.js (shared helpers: bareStdin, mode formatting, …)\n2. Optional preamble files (sed-engine.js, awk-engine.js, man-render.js)\n3. src/<name>.js (must contain only async function run and helpers in the same string—no import)\n\nSo “modules” become one compiled file on the drive. That is the supported pattern for shared logic in tier-1 utilities.\n\nPATTERNS THAT WORK FOR USER AND KERNEL CODE\n\n1. INLINE HELPERS\n\nFor small scripts, define functions above run:\n\n function double(n) {\n return n * 2\n }\n async function run(ctx, argv) {\n ctx.console.log(String(double(21)))\n }\n\n2. COPY-PASTE PRELUDE SNIPPETS\n\nYou may copy minimal helpers (e.g. stdin reader) from runtime.js <../packages/bare-os-coreutils/lib/runtime.js> into your script. Keep the license header in mind if you redistribute.\n\n3. LOAD ANOTHER FILE FROM THE DRIVE (ADVANCED)\n\nYou _can_ readFile a second script as a string and… you should not eval arbitrary untrusted content. For your own modules stored as ~/lib/helpers.js, a pattern is:\n\n- Store function bodies only or data (JSON), not full import syntax.\n- Or concatenate at build time on the host before uploading to Hyperdrive.\n\nThere is no built-in import() dynamic loader wired to Hyperdrive in the stock booter.\n\n4. HOST-SIDE BUNDLING\n\nIf you generate a single bundle.js on your laptop with esbuild/rollup and upload it to ~/bundle.js, that file can use no external import at runtime because everything is already bundled. This is the closest to “npm on device” without changing the booter.\n\nHOST PACKAGES (BOOTER / SEEDER): FULL ESM\n\nWhen you edit packages/bare-os-booter/index.js, you are in module land:\n\n import { runBinCommand } from './lib/kernel-runner.js'\n\nUse this for new protocols, drive encryption, alternate kernels, etc. This is not the same as writing /bin/foo.\n\nPEAR AND BARE GLOBALS\n\nUnder Pear/Bare, some globals (e.g. Bare) may exist for host exit and lifecycle. In-image utilities should still prefer ctx for I/O to stay consistent when the same script pattern is tested under different harnesses.\n\nFAQ CORNER\n\nCan I add dynamic import to the booter for user scripts?\nPossible in theory (resolve specifiers from Hyperdrive) but not implemented, and it raises security and package format questions (where do dependencies live?).\n\nCan I put node_modules on my personal drive?\nEven if you replicated bytes, the in-image loader would not resolve them as Node does. You would need a host or kernel change to load from that tree.\n\nSEE ALSO\n\n- Chapter 6 — Extending /bin <06-extending-bin-coreutils.md>\n- Chapter 9 — Security <09-security-and-trust.md>\n- bare-os-coreutils README <../packages/bare-os-coreutils/README.md>\n\n← User scripts <04-user-scripts-and-path.md> · Extending /bin → <06-extending-bin-coreutils.md>",
"descriptionMode": "preserve",
"options": [],
"keywords": [
"developer",
"devguide",
"develop",
"script",
"asyncfunction",
"ctx",
"bare-os",
"guide",
"05",
"modules",
"and",
"imports",
"chapter",
"import",
"packaging",
"the",
"honest",
"version"
],
"seeAlso": [
{ "name": "devguide-06-extending-bin-coreutils", "section": 7 },
{ "name": "devguide-04-user-scripts-and-path", "section": 7 },
{ "name": "man", "section": 1 },
{ "name": "bare-os-handbook", "section": 7 }
],
"bareOsNotes": "Generated at build time from developer-guide/05-modules-and-imports.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.",
"listCategory": "devguide"
},
{
"name": "devguide-06-extending-bin-coreutils",
"section": 7,
"title": "Chapter 6 — Extending /bin (bare-os-coreutils)",
"synopsis": [
"man 7 devguide-06-extending-bin-coreutils",
"Developer guide chapter (developer-guide/06-extending-bin-coreutils.md)"
],
"description": "CHAPTER 6 — EXTENDING /BIN (BARE-OS-COREUTILS)\n\nShipping a new command in the system image means adding it to bare-os-coreutils, rebuilding, and re-seeding so /bin/<name> exists on the Hyperdrive. This is the only supported path for first-class OS utilities with shared prelude code.\n\nTHE CONTRACT (NON-NEGOTIABLE)\n\nEach command source under packages/bare-os-coreutils/src/<name>.js must:\n\n- Define async function run(ctx, argv).\n- Contain no top-level import or export—the file is concatenated into a single script string for AsyncFunction loading.\n\nShared helpers live in packages/bare-os-coreutils/lib/ and are prepended at build time, not imported.\n\nCHECKLIST FOR A NEW COMMAND FOO\n\n1. Implement packages/bare-os-coreutils/src/foo.js.\n2. Register the name in packages/bare-os-coreutils/lib/commands.mjs (COREUTILS_COMMANDS—keep sorted).\n3. Add a man page packages/bare-os-coreutils/man/pages/foo.json (build fails if missing).\n4. Optional: seed examples via scripts/seed-man-pages.mjs or edit JSON directly.\n5. Optional preamble: if foo needs a large engine file, add to preamble in build.mjs <../packages/bare-os-coreutils/build.mjs>:\n\n const preamble = {\n sed: ['sed-engine.js'],\n awk: ['awk-engine.js'],\n man: ['man-render.js'],\n foo: ['foo-engine.js']\n }\n\n6. Build\n\n npm run build -w bare-os-coreutils\n\nThis runs build-man-db.mjs (manual database) and writes kernel/bin/foo plus the seeder mirror.\n\n7. Re-seed / replicate so peers get the new /bin/foo.\n\nWHAT GETS CONCATENATED\n\nFrom build.mjs <../packages/bare-os-coreutils/build.mjs>:\n\n runtime.js + [preamble files...] + src/foo.js → kernel/bin/foo\n\nruntime.js begins with a BARE_OS_BIN_API version comment (e.g. */ BARE_OS_BIN_API 1.0.0 /). Staged kernel/bin/ must contain that string so scripts/verify-kernel-seeder-parity.mjs <../../scripts/verify-kernel-seeder-parity.mjs> can catch drift; hand-written stubs (systemctl, journalctl**) carry the same pragma.\n\nruntime.js defines helpers like bareStdin, listing time formatting, etc.—read it before reimplementing utilities.\n\nEXIT STATUS\n\nPOSIX-ish utilities set ctx.exitCode (number) when they want a non-zero status. The shell uses ctx.exitCode for &&, ||, and ; lists; utilities such as grep and test set it for conditions.\n\nTESTS\n\nAdd or extend tests under packages/bare-os-booter/test.js using runBinCommand with a Hyperdrive that has the built /bin/foo bytes—follow existing grep, ls, cat patterns.\n\nDOCUMENTATION\n\n- Update man page JSON (required by build).\n- Optional: handbook chapter 9 cross-links for POSIX alignment.\n- Optional: TypeScript shapes in packages/bare-os-booter/lib/bare-os-ctx.d.ts <../packages/bare-os-booter/lib/bare-os-ctx.d.ts> (BareOsKernelContext, BareOsBinRun) for host-side editors.\n\nSEE ALSO\n\n- Chapter 5 — Modules <05-modules-and-imports.md>\n- Chapter 8 — Testing <08-testing-and-debugging.md>\n- kernel/README.md <../kernel/README.md>\n\n← Modules <05-modules-and-imports.md> · Apps beyond shell → <07-apps-beyond-the-shell.md>",
"descriptionMode": "preserve",
"options": [],
"keywords": [
"developer",
"devguide",
"develop",
"script",
"asyncfunction",
"ctx",
"bare-os",
"guide",
"06",
"extending",
"bin",
"coreutils",
"chapter",
"bare"
],
"seeAlso": [
{ "name": "devguide-07-apps-beyond-the-shell", "section": 7 },
{ "name": "devguide-05-modules-and-imports", "section": 7 },
{ "name": "man", "section": 1 },
{ "name": "bare-os-handbook", "section": 7 }
],
"bareOsNotes": "Generated at build time from developer-guide/06-extending-bin-coreutils.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.",
"listCategory": "devguide"
},
{
"name": "devguide-07-apps-beyond-the-shell",
"section": 7,
"title": "Chapter 7 — “Apps” beyond the shell (what is realistic today)",
"synopsis": [
"man 7 devguide-07-apps-beyond-the-shell",
"Developer guide chapter (developer-guide/07-apps-beyond-the-shell.md)"
],
"description": "CHAPTER 7 — “APPS” BEYOND THE SHELL (WHAT IS REALISTIC TODAY)\n\nBare OS does not have an app store, sandboxed widgets, or a second GUI runtime inside the image. An application here is usually:\n\n- a workflow built from the shell, /bin tools, and files on the personal drive; or\n- a custom kernel + utilities; or\n- a host Pear app that changes boot behavior.\n\nThis chapter orients you without over-promising.\n\nTHE DEFAULT “APP”: SHELL + /BIN + GIT\n\nMost user goals are met by:\n\n- Scripts in $HOME (run(ctx, argv)).\n- Pipelines and redirection (simulated stdin/stdout).\n- git for repositories on the VFS (see Handbook ch.8 <../handbook/08-git-on-bare-os.md>).\n\nThat is the intended application platform for end users.\n\nINITD AND BACKGROUND FLAVOR\n\nThe booter registers initd-style disposers via bare-initd.js <../packages/bare-os-booter/lib/bare-initd.js>. The stock system uses this lightly (e.g. kernel logger). Extending this usually means host booter changes: register a start function during executeKernel, not from arbitrary /bin scripts.\n\nRead bare-initd.js <../packages/bare-os-booter/lib/bare-initd.js> before adding long-running tasks—teardown must be explicit (stopBareInitd).\n\nCRON AND TIMERS\n\nbare-cron reads /etc/bare-os/crontab on the system image (if present), then the user’s ~/.crontab on the personal drive; invalid lines are logged and skipped. crontab installs/lists/removes the user file (requires login). Timer drop-ins under *~/.config/bare-os/timers/.timer ([Timer] OnCalendar= + ExecLine=**) merge into the same minute scheduler. See Handbook ch.4 <../handbook/04-the-booter-runtime.md> and Developer guide ch.11 <11-kernel-pear-cookbook.md>.\n\nSocket-shaped activation: initd unit drop-ins can set SocketActivationIpc=<fifo-name> so a service’s start() runs when something first readFiles that logical FIFO under /run/bare-os/ipc/ (see bare-initd.js).\n\nHDMS AND /MNT\n\nAfter identity unlock, optional HDMS mounts may appear under /mnt. Utilities use ctx.vfs; HDMS integration is advanced and covered narratively in the handbook (identity + HDMS chapter). User scripts should prefer vfs.readFile / writeFile over hard-coding drive objects.\n\nREPLACING THE KERNEL\n\nA heavier “app” might ship a different /boot/init.js—for example a menu-driven UI using readLine or a non-interactive worker when BARE_OS_SKIP_REPL=1. You still have the single JavaScript realm per session; there is no fork into a second Bare process from inside the image.\n\nWHEN YOU ACTUALLY NEED A NEW PEAR APP\n\nIf you need multiple OS images, custom networking, or native addons not suitable for AsyncFunction utilities, create a new Pear application that embeds or forks the booter pattern—this is host development (Chapter 1), not /bin development.\n\nSEE ALSO\n\n- Chapter 3 — Kernel <03-kernel-boot-init.md>\n- Handbook — Booter runtime <../handbook/04-the-booter-runtime.md>\n- Handbook — Identity, vault, HDMS <../handbook/05-identity-vault-and-hdms.md>\n\n← Extending /bin <06-extending-bin-coreutils.md> · Testing → <08-testing-and-debugging.md>",
"descriptionMode": "preserve",
"options": [],
"keywords": [
"developer",
"devguide",
"develop",
"script",
"asyncfunction",
"ctx",
"bare-os",
"guide",
"07",
"apps",
"beyond",
"the",
"shell",
"chapter",
"what",
"realistic",
"today"
],
"seeAlso": [
{ "name": "devguide-08-testing-and-debugging", "section": 7 },
{ "name": "devguide-06-extending-bin-coreutils", "section": 7 },
{ "name": "man", "section": 1 },
{ "name": "bare-os-handbook", "section": 7 }
],
"bareOsNotes": "Generated at build time from developer-guide/07-apps-beyond-the-shell.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.",
"listCategory": "devguide"
},
{
"name": "devguide-08-testing-and-debugging",
"section": 7,
"title": "Chapter 8 — Testing and debugging",
"synopsis": [
"man 7 devguide-08-testing-and-debugging",
"Developer guide chapter (developer-guide/08-testing-and-debugging.md)"
],
"description": "CHAPTER 8 — TESTING AND DEBUGGING\n\nBare OS development mixes Node (fast iteration, Hyperdrive in tests), Bare (identity crypto and Pear parity), and Pear (production-like bundling). This chapter maps how tests are organized and how to debug in-image code.\n\nWORKSPACE TESTS\n\nFrom the repo root:\n\n npm ci\n npm test\n\npretest runs npm run build -w bare-os-coreutils and node scripts/verify-kernel-seeder-parity.mjs so *kernel/bin/, kernel/share/man/man.json, and packages/bare-os-seeder/kernel/** stay aligned before booter tests.\n\nKernel self-test: with BARE_OS_KERNEL_SELFTEST=1, the stock kernel runs built-in checks (including /proc/bare_os_resources and /proc/bare_os_features). Use BARE_OS_SELFTEST_FORMAT=tap for CI-friendly stderr.\n\nBRITTLE: BRITTLE-NODE VS BRITTLE-BARE\n\n- brittle-node runs most of packages/bare-os-booter/test.js—Hyperdrive, VFS, shell tokenizer, runBinCommand against real /bin bytes on disk.\n- brittle-bare runs test.identity.js and protocol tests that need the Bare runtime (e.g. bare-crypto native pieces).\n\nCI installs Bare globally for parity (see .github/workflows/ci.yml). If identity tests fail locally, ensure bare is installed and on PATH.\n\nDEBUGGING USER SCRIPTS AND UTILITIES\n\n1. ctx.console.log / error — Primary visibility; errors from AsyncFunction compilation are caught in runScriptFromSource and printed with a short stack snippet.\n2. Isolate — Run a one-line shell command: command node is not available; use runBinCommand from a tiny test or invoke your script path directly.\n3. Compare with known-good — Copy the pattern from packages/bare-os-booter/test.js (readBuiltBin, put /bin/ls, etc.).\n\nPEAR DEV WORKFLOW\n\nUse the root scripts (see README <../README.md>):\n\n- npm run os:seeder and npm run os:booter (separate terminals) after ensure-pear-node-modules.\n\nPear uses bundled node_modules; if resolution fails, run node scripts/ensure-pear-node-modules.mjs as documented in scripts/README.md.\n\nCI-STYLE KERNEL CHECKS\n\n- BARE_OS_KERNEL_SELFTEST=1 — stock kernel/init.js <../kernel/init.js> runs a short execLine checklist after boot snippets.\n- BARE_OS_SELFTEST_FORMAT=tap — same self-test emits TAP lines on stderr (for parsers in CI).\n- node scripts/verify-kernel-seeder-parity.mjs — after a coreutils build, asserts kernel/ and packages/bare-os-seeder/kernel/ match and every *kernel/bin/ file includes BARE_OS_BIN_API (root pretest** runs this).\n\nCOMMON FAILURE MODES\n\n| Symptom | Likely cause |\n| missing run() | Script lacks async function run(ctx, argv) top-level |\n| unknown command | Name not on system PATH and not a resolvable *.js |\n| invalid manual database | Forgot to build coreutils after changing commands list |\n| kernel/bin missing BARE_OS_BIN_API pragma | Rebuild coreutils or add pragma to hand-maintained *kernel/bin/** stubs |\n| Identity test skips / fails on Node only | Expected—run under brittle-bare |\n| Session exits immediately | BARE_OS_SKIP_REPL=1 or readLine returns null |\n\nSEE ALSO\n\n- Handbook ch.7 — Operations <../handbook/07-operations-and-development.md>\n- bare-os-booter README <../packages/bare-os-booter/README.md>\n\n← Apps beyond shell <07-apps-beyond-the-shell.md> · Security → <09-security-and-trust.md>",
"descriptionMode": "preserve",
"options": [],
"keywords": [
"developer",
"devguide",
"develop",
"script",
"asyncfunction",
"ctx",
"bare-os",
"guide",
"08",
"testing",
"and",
"debugging",
"chapter"
],
"seeAlso": [
{ "name": "devguide-09-security-and-trust", "section": 7 },
{ "name": "devguide-07-apps-beyond-the-shell", "section": 7 },
{ "name": "man", "section": 1 },
{ "name": "bare-os-handbook", "section": 7 }
],
"bareOsNotes": "Generated at build time from developer-guide/08-testing-and-debugging.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.",
"listCategory": "devguide"
},
{
"name": "devguide-09-security-and-trust",
"section": 7,
"title": "Chapter 9 — Security and trust (developer mindset)",
"synopsis": [
"man 7 devguide-09-security-and-trust",
"Developer guide chapter (developer-guide/09-security-and-trust.md)"
],
"description": "CHAPTER 9 — SECURITY AND TRUST (DEVELOPER MINDSET)\n\nBare OS is research software. It is not a hardened multi-tenant OS. Still, developers should understand what is trusted and what full ctx power implies.\n\nSYSTEM DRIVE TRUST MODEL\n\nThe system Hyperdrive is the OS image. You normally obtain it by replicating from peers that share the project’s discovery topology (see handbook protocol chapters). The codebase assumes you trust that image the same way you would trust an installer ISO from a vendor you chose.\n\n/bin and /boot bytes are executed as JavaScript. A malicious seeder could ship hostile /bin scripts. Mitigation is social and operational: use keys and peers you trust, verify releases, run your own seeder for development.\n\nBoot snippet tightening: with BARE_OS_BOOT_ALLOWLIST=1, the stock kernel only runs lines from trusted rc, rc.d, rc.local, kernel.d, and onboot whose first shell token appears in /etc/bare-os/boot.allow (plus builtins such as export, cd, :). Pair with BARE_OS_BOOT_STRICT=1 to exit the session on the first disallowed or failing line.\n\nAudit: BARE_OS_AUDIT=1 logs execLine activity to /var/log/bare-os/audit.log. BARE_OS_AUDIT_JSON=1 uses JSON lines; BARE_OS_AUDIT_REDACT=1 (or true) masks common secret-like VAR=value patterns; BARE_OS_AUDIT_REDACT=TOKEN,PASSWORD masks named keys.\n\nDelegated HTTP: when the booter sets ctx.httpFetch from the host fetch, BARE_OS_HTTP_ALLOWLIST and BARE_OS_HTTP_DENYLIST restrict http/https URLs for curl/wget (host-pattern globs). Failed checks throw before the request; with audit on, allow/deny outcomes can be logged.\n\nIPC JSON-RPC: when BARE_OS_IPC_RPC_TOKEN is set, pushJson payloads must include matching bareOsIpcToken or the push throws. Line size is capped (BARE_OS_IPC_JSON_MAX_BYTES, default 256 KiB).\n\nFuture isolation: ctx.bareOsSandboxRunScript() is reserved and throws today; real worker or Pear-isolate execution would narrow trust for untrusted scripts—see the handbook blueprints chapter for the architectural split.\n\nPERSONAL DRIVE AND USER SCRIPTS\n\nAnything you can write to $HOME can be executed if you run it—and you are the typical author. If you download a script from the network into your home directory and execLine it, you have effectively eval’d untrusted code with access to:\n\n- ctx.vfs (read/write personal tree),\n- identity hooks (if exposed through crafted shell lines),\n- runBinCommand (invoke all bundled utilities).\n\nThe stock shell does not sandbox run. Treat drive-resident JS like shell scripts with superpowers.\n\nWHY “ADD DYNAMIC IMPORT FROM THE INTERNET” IS DANGEROUS\n\nLoading modules from Hyperdrive or HTTP sounds convenient but creates:\n\n- Supply chain exposure (mutable remote code),\n- Ambiguous versioning (no lockfile on device),\n- Larger attack surface in the booter.\n\nThe project’s conservative stance: bundle on the host or ship utilities in the system image after review.\n\nGUEST VS UNLOCKED IDENTITY\n\nDefault guest sessions have predictable HOME=/home/guest and no Ed25519 identity. Login unlocks /.bare/account and changes ctx.vfs.env (user, home, keys). Applications that handle secrets should never log passphrases or raw keys; use existing login / logout flows.\n\nREPORTING ISSUES\n\nSecurity vulnerabilities in this repo should be reported through the project’s normal channels (maintainer contact / GitHub security advisories if enabled). Do not open public issues with exploit details until coordinated disclosure.\n\nSEE ALSO\n\n- Handbook — Blueprints / trust <../handbook/02-blueprints.md>\n- Chapter 5 — Modules <05-modules-and-imports.md>\n\n← Testing <08-testing-and-debugging.md> · Glossary → <10-glossary-and-faq.md>",
"descriptionMode": "preserve",
"options": [],
"keywords": [
"developer",
"devguide",
"develop",
"script",
"asyncfunction",
"ctx",
"bare-os",
"guide",
"09",
"security",
"and",
"trust",
"chapter",
"mindset"
],
"seeAlso": [
{ "name": "devguide-10-glossary-and-faq", "section": 7 },
{ "name": "devguide-08-testing-and-debugging", "section": 7 },
{ "name": "man", "section": 1 },
{ "name": "bare-os-handbook", "section": 7 }
],
"bareOsNotes": "Generated at build time from developer-guide/09-security-and-trust.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.",
"listCategory": "devguide"
},
{
"name": "devguide-10-glossary-and-faq",
"section": 7,
"title": "Chapter 10 — Glossary and FAQ",
"synopsis": [
"man 7 devguide-10-glossary-and-faq",
"Developer guide chapter (developer-guide/10-glossary-and-faq.md)"
],
"description": "CHAPTER 10 — GLOSSARY AND FAQ\n\nQuick reference and repeated questions.\n\nGLOSSARY\n\n| Term | Meaning |\n| AsyncFunction | Object.getPrototypeOf(async function () {}).constructor — used to compile in-image JS strings with parameters ctx / argv |\n| Booter | Pear/Node app (bare-os-booter) that joins Hyperswarm, replicates drives, builds ctx, runs kernel |\n| Coreutils | bare-os-coreutils package — builds /bin scripts from src/*.js + prelude |\n| ctx | Context object passed to start and run; see Chapter 2 <02-the-context-object.md> |\n| Guest | Pre-login session identity (BARE_OS_IDENTITY=guest) |\n| Hyperdrive | P2P writable/readable filesystem keyed by discovery secret |\n| In-image | Code whose source bytes live on system or personal drive and are eval’d via AsyncFunction |\n| Kernel | /boot/init.js — async function start(ctx) |\n| Personal drive | Per-session mutable Hyperdrive; $HOME, /.bare, user files |\n| Seeder | Pear/Node app that stages kernel/ into system Hyperdrive and serves MBR |\n| System drive | Replicated OS image (/bin, /boot, /etc, …) |\n| VFS | Virtual file system layer routing paths to drives + HDMS mounts |\n| IPC fan-out | bareOsIpc.fanoutPublish / fanoutSubscribe — multi-subscriber copies (bounded); disable with BARE_OS_IPC_FANOUT=0 |\n| HTTP policy | Optional BARE_OS_HTTP_ALLOWLIST / BARE_OS_HTTP_DENYLIST applied when the booter wraps ctx.httpFetch |\n| booterPhases | Milestones recorded in /run/bare-os/boot.json (vfs, ctx, repl, initd, kernel_invoke) alongside kernel phases |\n\nFAQ\n\nWhy doesn’t import work in my ~/script.js?\nIn-image scripts are not ES modules. Use inlining, bundling on the host, or the coreutils concat build. See Chapter 5 <05-modules-and-imports.md>.\n\nHow do I use npm packages on the device?\nYou generally don’t inside /bin or home scripts. Bundle on the host, or add code to the booter package with normal npm deps.\n\nWhat’s the difference between execLine and runBinCommand?\nexecLine runs the shell (aliases, builtins, pipelines). runBinCommand runs argv directly. See Chapter 3 <03-kernel-boot-init.md>.\n\nHow do I add a command to /bin?\nFollow Chapter 6 <06-extending-bin-coreutils.md>: src/foo.js, commands.mjs, man/pages/foo.json, build.\n\nCan I run TypeScript?\nNot natively on the drive. Compile to JS on the host, then ship the output.\n\nWhere is stdin for pipelines?\nShell sets ctx.shellStdin on a cloned context. Read it as a string. Coreutils use bareStdin(ctx) from prelude—user scripts must implement their own or copy the snippet. Chapter 4 <04-user-scripts-and-path.md>.\n\nHow do I exit the session from code?\nCall ctx.requestBooterExit(code) (same as exit builtin / /bin/exit).\n\nDoes ctx.exitCode control the host process exit?\nThe host exit code is managed by the booter after the kernel returns; utilities set ctx.exitCode for POSIX semantics inside the session. See booter executeKernel return path.\n\nWhat about Web APIs (fetch, localStorage)?\nNot part of the Bare OS contract for in-image code. Pear/Bare may provide some globals on the host; do not rely on them for portable /bin tools. When Node provides fetch, the booter may set ctx.httpFetch with outbound policy—see Chapter 2 <02-the-context-object.md>.\n\nWhat is bareOsSandboxRunScript?\nA reserved API that throws until a worker/isolate story lands; see Chapter 9 <09-security-and-trust.md>.\n\nSEE ALSO\n\n- Developer guide home <README.md>\n- Handbook home <../handbook/README.md>\n- DOCUMENTATION.md <../DOCUMENTATION.md>\n\n← Security <09-security-and-trust.md> · Developer guide home <README.md>",
"descriptionMode": "preserve",
"options": [],
"keywords": [
"developer",
"devguide",
"develop",
"script",
"asyncfunction",
"ctx",
"bare-os",
"guide",
"10",
"glossary",
"and",
"faq",
"chapter"
],
"seeAlso": [
{ "name": "devguide-11-kernel-pear-cookbook", "section": 7 },
{ "name": "devguide-09-security-and-trust", "section": 7 },
{ "name": "man", "section": 1 },
{ "name": "bare-os-handbook", "section": 7 }
],
"bareOsNotes": "Generated at build time from developer-guide/10-glossary-and-faq.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.",
"listCategory": "devguide"
},
{
"name": "devguide-11-kernel-pear-cookbook",
"section": 7,
"title": "Chapter 11 — Kernel extensions and Pear workflows",
"synopsis": [
"man 7 devguide-11-kernel-pear-cookbook",
"Developer guide chapter (developer-guide/11-kernel-pear-cookbook.md)"
],
"description": "CHAPTER 11 — KERNEL EXTENSIONS AND PEAR WORKFLOWS\n\nThis chapter ties the Hyperdrive-resident kernel (kernel/init.js <../kernel/init.js>), ctx <./02-the-context-object.md>, and Pear/Bare distribution patterns together.\n\nBOOT COMPOSITION\n\n1. Stock phases — os-release, motd, optional rc.profile.*, rc, rc.d, rc.local, kernel.d, banner, onboot (non-interactive), optional self-test.\n2. Strict boot — BARE_OS_BOOT_STRICT=1 stops on first execLine error in trusted snippets.\n3. Allowlist — BARE_OS_BOOT_ALLOWLIST=1 plus /etc/bare-os/boot.allow <../kernel/etc/bare-os/boot.allow.example> restricts the first word of each line in those snippets (builtins like export and cd stay allowed).\n\nINIT, TIMERS, AND SOCKETS\n\n- bare-initd — User drop-ins under ~/.config/bare-os/units/<name>.unit support SocketActivationIpc=<fifo>; the unit’s start runs after the first byte is read on that logical FIFO under /run/bare-os/ipc/….\n- Timers — Files in ~/.config/bare-os/timers/*.timer with a [Timer] section (OnCalendar= five cron fields, ExecLine=) are evaluated on the same minute tick as ~/.crontab.\n- System cron — Optional image file /etc/bare-os/crontab (see crontab.example <../kernel/etc/bare-os/crontab.example>) is merged with user crontab entries.\n\nOBSERVABILITY\n\n- ctx.bareOsSubscribeBootEvent — Same structured events as BARE_OS_BOOT_TRACE=ndjson (phase, ms, sessionId); the booter also emits *booter: phases (vfs, ctx, repl, initd, kernel_invoke**).\n- /proc/bare_os_quotas — Pipeline limits, BARE_OS_EXEC_MAX_DEPTH, IPC caps, session stats.\n- /proc/bare_os_resources / ctx.bareOsGetResourceStatus() — Unified snapshot for operators.\n- /proc/bare_os_features — Documented kernel-feature bitmask (see bare-os-protocol exports).\n- ctx.vfs.watch(path) — Hyperdrive-backed watch when BARE_OS_VFS_WATCH is not 0; returns { watcher, destroy, … }.\n\nPEAR / GIT / HTTP\n\n- Release metadata — Host can set BARE_OS_PEAR_CHANNEL, BARE_OS_PEAR_RELEASE, and BARE_OS_IMAGE_DIGEST; they appear in /run/bare-os/boot.json.\n- ctx.bareOsRequestPearReload() — Returns hints and env strings; the host pear-runtime / pear-runtime-updater must perform any real reload.\n- git-pear — /bin/git-pear help documents Git-in-Pear (gip-transport, gip-remote, git+pear:// remotes).\n- HTTP — Delegated curl/wget use ctx.httpFetch when the booter wrapped global fetch; BARE_OS_HTTP_ALLOWLIST, BARE_OS_HTTP_DENYLIST, and BARE_OS_TLS_PIN_SHA256 (passed as init.bareOsCurlTls.pinnedSha256 for delegated TLS) narrow outbound access. On minimal hosts, curl still tries bare-fetch / bare-https to install globalThis.fetch.\n\nBUILDING THE IMAGE\n\n- From the repo root, rebuild staged /bin utilities: node packages/bare-os-coreutils/build.mjs.\n- Keep kernel/ <../kernel/> and packages/bare-os-seeder/kernel/ <../packages/bare-os-seeder/kernel/> identical (node scripts/verify-kernel-seeder-parity.mjs).\n- Pear staging: use pear-build / app manifests in your Pear project; align pear.json channels with BARE_OS_PEAR_* env vars on the boot host.\n\nHDMS HOOKS\n\nUse ctx.bareOsSubscribeHdmsLifecycle to run logic when extra drives mount after unlock (kind: 'activate', labels) or before guest teardown (kind: 'deactivate').",
"descriptionMode": "preserve",
"options": [],
"keywords": [
"developer",
"devguide",
"develop",
"script",
"asyncfunction",
"ctx",
"bare-os",
"guide",
"11",
"kernel",
"pear",
"cookbook",
"chapter",
"extensions",
"and",
"workflows"
],
"seeAlso": [
{ "name": "devguide-10-glossary-and-faq", "section": 7 },
{ "name": "man", "section": 1 },
{ "name": "bare-os-handbook", "section": 7 }
],
"bareOsNotes": "Generated at build time from developer-guide/11-kernel-pear-cookbook.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.",
"listCategory": "devguide"
}
],
"index": {
"awk": 0,
"basename": 1,
"cat": 2,
"chgrp": 3,
"chmod": 4,
"chown": 5,
"cksum": 6,
"clear": 7,
"cp": 8,
"crontab": 9,
"cut": 10,
"date": 11,
"dirname": 12,
"du": 13,
"echo": 14,
"env": 15,
"exit": 16,
"false": 17,
"find": 18,
"getconf": 19,
"git-pear": 20,
"grep": 21,
"head": 22,
"hdms": 23,
"help": 24,
"hostname": 25,
"id": 26,
"jq": 27,
"ln": 28,
"login": 29,
"logout": 30,
"logname": 31,
"ls": 32,
"man": 33,
"mkdir": 34,
"mkfifo": 35,
"mktemp": 36,
"mv": 37,
"nl": 38,
"od": 39,
"pathchk": 40,
"printenv": 41,
"printf": 42,
"pwd": 43,
"readlink": 44,
"rm": 45,
"rmdir": 46,
"savevault": 47,
"sed": 48,
"seq": 49,
"sleep": 50,
"sort": 51,
"stat": 52,
"tail": 53,
"tee": 54,
"test": 55,
"time": 56,
"touch": 57,
"tr": 58,
"true": 59,
"tty": 60,
"uname": 61,
"wc": 62,
"which": 63,
"whoami": 64,
"xargs": 65,
"bare-os-shell": 66,
"sh-builtins": 66,
"systemctl": 67,
"bare-initctl": 67,
"curl": 68,
"git": 69,
"wget": 70,
"bare-os-handbook": 71,
"handbook": 71,
"bare-os-handbook-index": 71,
"handbook-01-introduction": 72,
"handbook-02-blueprints": 73,
"handbook-03-protocol-and-disk": 74,
"handbook-04-the-booter-runtime": 75,
"handbook-05-identity-vault-and-hdms": 76,
"handbook-06-kernel-and-binaries": 77,
"handbook-07-operations-and-development": 78,
"handbook-08-git-on-bare-os": 79,
"handbook-09-posix-utilities-shell-and-vfs": 80,
"handbook-10-manpages-and-online-help": 81,
"bare-os-developer-guide": 82,
"developer-guide": 82,
"devguide": 82,
"devguide-01-two-runtimes-host-vs-image": 83,
"devguide-02-the-context-object": 84,
"devguide-03-kernel-boot-init": 85,
"devguide-04-user-scripts-and-path": 86,
"devguide-05-modules-and-imports": 87,
"devguide-06-extending-bin-coreutils": 88,
"devguide-07-apps-beyond-the-shell": 89,
"devguide-08-testing-and-debugging": 90,
"devguide-09-security-and-trust": 91,
"devguide-10-glossary-and-faq": 92,
"devguide-11-kernel-pear-cookbook": 93
},
"apropos": [
{ "kw": "awk", "pageRef": 0 },
{ "kw": "pattern", "pageRef": 0 },
{ "kw": "field", "pageRef": 0 },
{ "kw": "script", "pageRef": 0 },
{ "kw": "scanning", "pageRef": 0 },
{ "kw": "and", "pageRef": 0 },
{ "kw": "processing", "pageRef": 0 },
{ "kw": "language", "pageRef": 0 },
{ "kw": "print", "pageRef": 0 },
{ "kw": "column", "pageRef": 0 },
{ "kw": "1", "pageRef": 0 },
{ "kw": "separator", "pageRef": 0 },
{ "kw": "sum", "pageRef": 0 },
{ "kw": "numbers", "pageRef": 0 },
{ "kw": "in", "pageRef": 0 },
{ "kw": "first", "pageRef": 0 },
{ "kw": "lines", "pageRef": 0 },
{ "kw": "matching", "pageRef": 0 },
{ "kw": "re", "pageRef": 0 },
{ "kw": "basename", "pageRef": 1 },
{ "kw": "bare-os", "pageRef": 1 },
{ "kw": "coreutils", "pageRef": 1 },
{ "kw": "strip", "pageRef": 1 },
{ "kw": "directory", "pageRef": 1 },
{ "kw": "and", "pageRef": 1 },
{ "kw": "suffix", "pageRef": 1 },
{ "kw": "from", "pageRef": 1 },
{ "kw": "pathnames", "pageRef": 1 },
{ "kw": "cat", "pageRef": 2 },
{ "kw": "bare-os", "pageRef": 2 },
{ "kw": "coreutils", "pageRef": 2 },
{ "kw": "concatenate", "pageRef": 2 },
{ "kw": "and", "pageRef": 2 },
{ "kw": "print", "pageRef": 2 },
{ "kw": "files", "pageRef": 2 },
{ "kw": "stdout", "pageRef": 2 },
{ "kw": "several", "pageRef": 2 },
{ "kw": "number", "pageRef": 2 },
{ "kw": "lines", "pageRef": 2 },
{ "kw": "use", "pageRef": 2 },
{ "kw": "nl", "pageRef": 2 },
{ "kw": "here-string", "pageRef": 2 },
{ "kw": "via", "pageRef": 2 },
{ "kw": "echo", "pageRef": 2 },
{ "kw": "pipe", "pageRef": 2 },
{ "kw": "chgrp", "pageRef": 3 },
{ "kw": "bare-os", "pageRef": 3 },
{ "kw": "coreutils", "pageRef": 3 },
{ "kw": "stub", "pageRef": 3 },
{ "kw": "change", "pageRef": 3 },
{ "kw": "file", "pageRef": 3 },
{ "kw": "group", "pageRef": 3 },
{ "kw": "ownership", "pageRef": 3 },
{ "kw": "not", "pageRef": 3 },
{ "kw": "supported", "pageRef": 3 },
{ "kw": "use", "pageRef": 3 },
{ "kw": "identity", "pageRef": 3 },
{ "kw": "model", "pageRef": 3 },
{ "kw": "chmod", "pageRef": 4 },
{ "kw": "mode", "pageRef": 4 },
{ "kw": "permission", "pageRef": 4 },
{ "kw": "octal", "pageRef": 4 },
{ "kw": "symbolic", "pageRef": 4 },
{ "kw": "change", "pageRef": 4 },
{ "kw": "file", "pageRef": 4 },
{ "kw": "bits", "pageRef": 4 },
{ "kw": "recursive-ish", "pageRef": 4 },
{ "kw": "run", "pageRef": 4 },
{ "kw": "find", "pageRef": 4 },
{ "kw": "per", "pageRef": 4 },
{ "kw": "user", "pageRef": 4 },
{ "kw": "all", "pageRef": 4 },
{ "kw": "read", "pageRef": 4 },
{ "kw": "owner", "pageRef": 4 },
{ "kw": "write", "pageRef": 4 },
{ "kw": "chown", "pageRef": 5 },
{ "kw": "bare-os", "pageRef": 5 },
{ "kw": "coreutils", "pageRef": 5 },
{ "kw": "stub", "pageRef": 5 },
{ "kw": "change", "pageRef": 5 },
{ "kw": "file", "pageRef": 5 },
{ "kw": "owner", "pageRef": 5 },
{ "kw": "and", "pageRef": 5 },
{ "kw": "group", "pageRef": 5 },
{ "kw": "not", "pageRef": 5 },
{ "kw": "supported", "pageRef": 5 },
{ "kw": "cksum", "pageRef": 6 },
{ "kw": "bare-os", "pageRef": 6 },
{ "kw": "coreutils", "pageRef": 6 },
{ "kw": "write", "pageRef": 6 },
{ "kw": "file", "pageRef": 6 },
{ "kw": "checksums", "pageRef": 6 },
{ "kw": "and", "pageRef": 6 },
{ "kw": "sizes", "pageRef": 6 },
{ "kw": "checksum", "pageRef": 6 },
{ "kw": "verify", "pageRef": 6 },
{ "kw": "pipeline", "pageRef": 6 },
{ "kw": "clear", "pageRef": 7 },
{ "kw": "bare-os", "pageRef": 7 },
{ "kw": "coreutils", "pageRef": 7 },
{ "kw": "the", "pageRef": 7 },
{ "kw": "terminal", "pageRef": 7 },
{ "kw": "screen", "pageRef": 7 },
{ "kw": "wipe", "pageRef": 7 },
{ "kw": "cp", "pageRef": 8 },
{ "kw": "bare-os", "pageRef": 8 },
{ "kw": "coreutils", "pageRef": 8 },
{ "kw": "copy", "pageRef": 8 },
{ "kw": "files", "pageRef": 8 },
{ "kw": "file", "pageRef": 8 },
{ "kw": "into", "pageRef": 8 },
{ "kw": "directory", "pageRef": 8 },
{ "kw": "preserve", "pageRef": 8 },
{ "kw": "implied", "pageRef": 8 },
{ "kw": "if", "pageRef": 8 },
{ "kw": "implemented", "pageRef": 8 },
{ "kw": "crontab", "pageRef": 9 },
{ "kw": "bare-os", "pageRef": 9 },
{ "kw": "coreutils", "pageRef": 9 },
{ "kw": "user", "pageRef": 9 },
{ "kw": "manipulation", "pageRef": 9 },
{ "kw": "list", "pageRef": 9 },
{ "kw": "jobs", "pageRef": 9 },
{ "kw": "install", "pageRef": 9 },
{ "kw": "from", "pageRef": 9 },
{ "kw": "file", "pageRef": 9 },
{ "kw": "remove", "pageRef": 9 },
{ "kw": "all", "pageRef": 9 },
{ "kw": "cut", "pageRef": 10 },
{ "kw": "bare-os", "pageRef": 10 },
{ "kw": "coreutils", "pageRef": 10 },
{ "kw": "out", "pageRef": 10 },
{ "kw": "selected", "pageRef": 10 },
{ "kw": "fields", "pageRef": 10 },
{ "kw": "of", "pageRef": 10 },
{ "kw": "each", "pageRef": 10 },
{ "kw": "line", "pageRef": 10 },
{ "kw": "by", "pageRef": 10 },
{ "kw": "delimiter", "pageRef": 10 },
{ "kw": "characters", "pageRef": 10 },
{ "kw": "date", "pageRef": 11 },
{ "kw": "bare-os", "pageRef": 11 },
{ "kw": "coreutils", "pageRef": 11 },
{ "kw": "display", "pageRef": 11 },
{ "kw": "or", "pageRef": 11 },
{ "kw": "set", "pageRef": 11 },
{ "kw": "and", "pageRef": 11 },
{ "kw": "time", "pageRef": 11 },
{ "kw": "rfc-ish", "pageRef": 11 },
{ "kw": "output", "pageRef": 11 },
{ "kw": "epoch", "pageRef": 11 },
{ "kw": "seconds", "pageRef": 11 },
{ "kw": "dirname", "pageRef": 12 },
{ "kw": "bare-os", "pageRef": 12 },
{ "kw": "coreutils", "pageRef": 12 },
{ "kw": "return", "pageRef": 12 },
{ "kw": "directory", "pageRef": 12 },
{ "kw": "portion", "pageRef": 12 },
{ "kw": "of", "pageRef": 12 },
{ "kw": "a", "pageRef": 12 },
{ "kw": "pathname", "pageRef": 12 },
{ "kw": "parent", "pageRef": 12 },
{ "kw": "path", "pageRef": 12 },
{ "kw": "compose", "pageRef": 12 },
{ "kw": "with", "pageRef": 12 },
{ "kw": "basename", "pageRef": 12 },
{ "kw": "du", "pageRef": 13 },
{ "kw": "bare-os", "pageRef": 13 },
{ "kw": "coreutils", "pageRef": 13 },
{ "kw": "estimate", "pageRef": 13 },
{ "kw": "file", "pageRef": 13 },
{ "kw": "space", "pageRef": 13 },
{ "kw": "usage", "pageRef": 13 },
{ "kw": "sizes", "pageRef": 13 },
{ "kw": "under", "pageRef": 13 },
{ "kw": "cwd", "pageRef": 13 },
{ "kw": "human", "pageRef": 13 },
{ "kw": "if", "pageRef": 13 },
{ "kw": "supported", "pageRef": 13 },
{ "kw": "echo", "pageRef": 14 },
{ "kw": "bare-os", "pageRef": 14 },
{ "kw": "coreutils", "pageRef": 14 },
{ "kw": "write", "pageRef": 14 },
{ "kw": "arguments", "pageRef": 14 },
{ "kw": "to", "pageRef": 14 },
{ "kw": "standard", "pageRef": 14 },
{ "kw": "output", "pageRef": 14 },
{ "kw": "literal", "pageRef": 14 },
{ "kw": "no", "pageRef": 14 },
{ "kw": "newline", "pageRef": 14 },
{ "kw": "if", "pageRef": 14 },
{ "kw": "-n", "pageRef": 14 },
{ "kw": "supported", "pageRef": 14 },
{ "kw": "env", "pageRef": 15 },
{ "kw": "bare-os", "pageRef": 15 },
{ "kw": "coreutils", "pageRef": 15 },
{ "kw": "set", "pageRef": 15 },
{ "kw": "the", "pageRef": 15 },
{ "kw": "environment", "pageRef": 15 },
{ "kw": "for", "pageRef": 15 },
{ "kw": "command", "pageRef": 15 },
{ "kw": "invocation", "pageRef": 15 },
{ "kw": "print", "pageRef": 15 },
{ "kw": "run", "pageRef": 15 },
{ "kw": "with", "pageRef": 15 },
{ "kw": "override", "pageRef": 15 },
{ "kw": "exit", "pageRef": 16 },
{ "kw": "bare-os", "pageRef": 16 },
{ "kw": "coreutils", "pageRef": 16 },
{ "kw": "the", "pageRef": 16 },
{ "kw": "shell", "pageRef": 16 },
{ "kw": "or", "pageRef": 16 },
{ "kw": "booter", "pageRef": 16 },
{ "kw": "session", "pageRef": 16 },
{ "kw": "leave", "pageRef": 16 },
{ "kw": "with", "pageRef": 16 },
{ "kw": "status", "pageRef": 16 },
{ "kw": "from", "pageRef": 16 },
{ "kw": "script", "pageRef": 16 },
{ "kw": "false", "pageRef": 17 },
{ "kw": "bare-os", "pageRef": 17 },
{ "kw": "coreutils", "pageRef": 17 },
{ "kw": "return", "pageRef": 17 },
{ "kw": "value", "pageRef": 17 },
{ "kw": "force", "pageRef": 17 },
{ "kw": "failure", "pageRef": 17 },
{ "kw": "in", "pageRef": 17 },
{ "kw": "pipeline", "pageRef": 17 },
{ "kw": "tests", "pageRef": 17 },
{ "kw": "find", "pageRef": 18 },
{ "kw": "directory", "pageRef": 18 },
{ "kw": "walk", "pageRef": 18 },
{ "kw": "search", "pageRef": 18 },
{ "kw": "files", "pageRef": 18 },
{ "kw": "by", "pageRef": 18 },
{ "kw": "name", "pageRef": 18 },
{ "kw": "glob", "pageRef": 18 },
{ "kw": "directories", "pageRef": 18 },
{ "kw": "only", "pageRef": 18 },
{ "kw": "max", "pageRef": 18 },
{ "kw": "depth", "pageRef": 18 },
{ "kw": "skip", "pageRef": 18 },
{ "kw": "top", "pageRef": 18 },
{ "kw": "level", "pageRef": 18 },
{ "kw": "gnu-like", "pageRef": 18 },
{ "kw": "-mindepth", "pageRef": 18 },
{ "kw": "2", "pageRef": 18 },
{ "kw": "or", "pageRef": 18 },
{ "kw": "names", "pageRef": 18 },
{ "kw": "getconf", "pageRef": 19 },
{ "kw": "limits", "pageRef": 19 },
{ "kw": "path_max", "pageRef": 19 },
{ "kw": "posix", "pageRef": 19 },
{ "kw": "bare-os", "pageRef": 19 },
{ "kw": "coreutils", "pageRef": 19 },
{ "kw": "get", "pageRef": 19 },
{ "kw": "configuration", "pageRef": 19 },
{ "kw": "values", "pageRef": 19 },
{ "kw": "path", "pageRef": 19 },
{ "kw": "length", "pageRef": 19 },
{ "kw": "limit", "pageRef": 19 },
{ "kw": "list", "pageRef": 19 },
{ "kw": "known", "pageRef": 19 },
{ "kw": "names", "pageRef": 19 },
{ "kw": "and", "pageRef": 19 },
{ "kw": "git", "pageRef": 20 },
{ "kw": "pear", "pageRef": 20 },
{ "kw": "gip", "pageRef": 20 },
{ "kw": "bare-os", "pageRef": 20 },
{ "kw": "git-pear", "pageRef": 20 },
{ "kw": "git-in-pear", "pageRef": 20 },
{ "kw": "hints", "pageRef": 20 },
{ "kw": "help", "pageRef": 20 },
{ "kw": "grep", "pageRef": 21 },
{ "kw": "search", "pageRef": 21 },
{ "kw": "regex", "pageRef": 21 },
{ "kw": "pattern", "pageRef": 21 },
{ "kw": "filter", "pageRef": 21 },
{ "kw": "matching", "pageRef": 21 },
{ "kw": "utility", "pageRef": 21 },
{ "kw": "recursive", "pageRef": 21 },
{ "kw": "feel", "pageRef": 21 },
{ "kw": "each", "pageRef": 21 },
{ "kw": "file", "pageRef": 21 },
{ "kw": "case", "pageRef": 21 },
{ "kw": "insensitive", "pageRef": 21 },
{ "kw": "invert", "pageRef": 21 },
{ "kw": "lines", "pageRef": 21 },
{ "kw": "without", "pageRef": 21 },
{ "kw": "fixed", "pageRef": 21 },
{ "kw": "string", "pageRef": 21 },
{ "kw": "no", "pageRef": 21 },
{ "kw": "count", "pageRef": 21 },
{ "kw": "matches", "pageRef": 21 },
{ "kw": "only", "pageRef": 21 },
{ "kw": "filenames", "pageRef": 21 },
{ "kw": "multiple", "pageRef": 21 },
{ "kw": "patterns", "pageRef": 21 },
{ "kw": "head", "pageRef": 22 },
{ "kw": "bare-os", "pageRef": 22 },
{ "kw": "coreutils", "pageRef": 22 },
{ "kw": "copy", "pageRef": 22 },
{ "kw": "the", "pageRef": 22 },
{ "kw": "first", "pageRef": 22 },
{ "kw": "part", "pageRef": 22 },
{ "kw": "of", "pageRef": 22 },
{ "kw": "files", "pageRef": 22 },
{ "kw": "10", "pageRef": 22 },
{ "kw": "lines", "pageRef": 22 },
{ "kw": "n", "pageRef": 22 },
{ "kw": "stdin", "pageRef": 22 },
{ "kw": "hdms", "pageRef": 23 },
{ "kw": "hyperswarm", "pageRef": 23 },
{ "kw": "map", "pageRef": 23 },
{ "kw": "distributed", "pageRef": 23 },
{ "kw": "store", "pageRef": 23 },
{ "kw": "when", "pageRef": 23 },
{ "kw": "booter", "pageRef": 23 },
{ "kw": "wires", "pageRef": 23 },
{ "kw": "otherwise", "pageRef": 23 },
{ "kw": "help", "pageRef": 24 },
{ "kw": "summary", "pageRef": 24 },
{ "kw": "builtins", "pageRef": 24 },
{ "kw": "commands", "pageRef": 24 },
{ "kw": "bare", "pageRef": 24 },
{ "kw": "os", "pageRef": 24 },
{ "kw": "quick", "pageRef": 24 },
{ "kw": "index", "pageRef": 24 },
{ "kw": "then", "pageRef": 24 },
{ "kw": "deep", "pageRef": 24 },
{ "kw": "dive", "pageRef": 24 },
{ "kw": "hostname", "pageRef": 25 },
{ "kw": "bare-os", "pageRef": 25 },
{ "kw": "coreutils", "pageRef": 25 },
{ "kw": "set", "pageRef": 25 },
{ "kw": "or", "pageRef": 25 },
{ "kw": "print", "pageRef": 25 },
{ "kw": "show", "pageRef": 25 },
{ "kw": "host", "pageRef": 25 },
{ "kw": "id", "pageRef": 26 },
{ "kw": "bare-os", "pageRef": 26 },
{ "kw": "coreutils", "pageRef": 26 },
{ "kw": "return", "pageRef": 26 },
{ "kw": "user", "pageRef": 26 },
{ "kw": "identity", "pageRef": 26 },
{ "kw": "who", "pageRef": 26 },
{ "kw": "am", "pageRef": 26 },
{ "kw": "i", "pageRef": 26 },
{ "kw": "numerically", "pageRef": 26 },
{ "kw": "jq", "pageRef": 27 },
{ "kw": "json", "pageRef": 27 },
{ "kw": "query", "pageRef": 27 },
{ "kw": "filter", "pageRef": 27 },
{ "kw": "jqjs", "pageRef": 27 },
{ "kw": "command-line", "pageRef": 27 },
{ "kw": "processor", "pageRef": 27 },
{ "kw": "language", "pageRef": 27 },
{ "kw": "subset", "pageRef": 27 },
{ "kw": "pretty-print", "pageRef": 27 },
{ "kw": "field", "pageRef": 27 },
{ "kw": "slurp", "pageRef": 27 },
{ "kw": "array", "pageRef": 27 },
{ "kw": "compact", "pageRef": 27 },
{ "kw": "ln", "pageRef": 28 },
{ "kw": "bare-os", "pageRef": 28 },
{ "kw": "coreutils", "pageRef": 28 },
{ "kw": "link", "pageRef": 28 },
{ "kw": "files", "pageRef": 28 },
{ "kw": "symlink", "pageRef": 28 },
{ "kw": "hard", "pageRef": 28 },
{ "kw": "if", "pageRef": 28 },
{ "kw": "supported", "pageRef": 28 },
{ "kw": "login", "pageRef": 29 },
{ "kw": "identity", "pageRef": 29 },
{ "kw": "passphrase", "pageRef": 29 },
{ "kw": "begin", "pageRef": 29 },
{ "kw": "a", "pageRef": 29 },
{ "kw": "session", "pageRef": 29 },
{ "kw": "on", "pageRef": 29 },
{ "kw": "the", "pageRef": 29 },
{ "kw": "system", "pageRef": 29 },
{ "kw": "unlock", "pageRef": 29 },
{ "kw": "existing", "pageRef": 29 },
{ "kw": "register", "pageRef": 29 },
{ "kw": "new", "pageRef": 29 },
{ "kw": "logout", "pageRef": 30 },
{ "kw": "session", "pageRef": 30 },
{ "kw": "end", "pageRef": 30 },
{ "kw": "save", "pageRef": 30 },
{ "kw": "vault", "pageRef": 30 },
{ "kw": "hint", "pageRef": 30 },
{ "kw": "logname", "pageRef": 31 },
{ "kw": "bare-os", "pageRef": 31 },
{ "kw": "coreutils", "pageRef": 31 },
{ "kw": "return", "pageRef": 31 },
{ "kw": "the", "pageRef": 31 },
{ "kw": "user", "pageRef": 31 },
{ "kw": "s", "pageRef": 31 },
{ "kw": "login", "pageRef": 31 },
{ "kw": "name", "pageRef": 31 },
{ "kw": "ls", "pageRef": 32 },
{ "kw": "list", "pageRef": 32 },
{ "kw": "directory", "pageRef": 32 },
{ "kw": "dir", "pageRef": 32 },
{ "kw": "contents", "pageRef": 32 },
{ "kw": "long", "pageRef": 32 },
{ "kw": "hidden", "pageRef": 32 },
{ "kw": "one", "pageRef": 32 },
{ "kw": "per", "pageRef": 32 },
{ "kw": "line", "pageRef": 32 },
{ "kw": "multiple", "pageRef": 32 },
{ "kw": "paths", "pageRef": 32 },
{ "kw": "man", "pageRef": 33 },
{ "kw": "manual", "pageRef": 33 },
{ "kw": "help", "pageRef": 33 },
{ "kw": "documentation", "pageRef": 33 },
{ "kw": "apropos", "pageRef": 33 },
{ "kw": "whatis", "pageRef": 33 },
{ "kw": "cheat", "pageRef": 33 },
{ "kw": "examples", "pageRef": 33 },
{ "kw": "display", "pageRef": 33 },
{ "kw": "on-line", "pageRef": 33 },
{ "kw": "pages", "pageRef": 33 },
{ "kw": "open", "pageRef": 33 },
{ "kw": "page", "pageRef": 33 },
{ "kw": "handbook", "pageRef": 33 },
{ "kw": "toc", "pageRef": 33 },
{ "kw": "section", "pageRef": 33 },
{ "kw": "7", "pageRef": 33 },
{ "kw": "chapter", "pageRef": 33 },
{ "kw": "by", "pageRef": 33 },
{ "kw": "all", "pageRef": 33 },
{ "kw": "narrow", "pageRef": 33 },
{ "kw": "terminal", "pageRef": 33 },
{ "kw": "mkdir", "pageRef": 34 },
{ "kw": "bare-os", "pageRef": 34 },
{ "kw": "coreutils", "pageRef": 34 },
{ "kw": "make", "pageRef": 34 },
{ "kw": "directories", "pageRef": 34 },
{ "kw": "one", "pageRef": 34 },
{ "kw": "dir", "pageRef": 34 },
{ "kw": "parents", "pageRef": 34 },
{ "kw": "mkfifo", "pageRef": 35 },
{ "kw": "bare-os", "pageRef": 35 },
{ "kw": "coreutils", "pageRef": 35 },
{ "kw": "stub", "pageRef": 35 },
{ "kw": "make", "pageRef": 35 },
{ "kw": "fifo", "pageRef": 35 },
{ "kw": "special", "pageRef": 35 },
{ "kw": "files", "pageRef": 35 },
{ "kw": "mktemp", "pageRef": 36 },
{ "kw": "bare-os", "pageRef": 36 },
{ "kw": "coreutils", "pageRef": 36 },
{ "kw": "create", "pageRef": 36 },
{ "kw": "a", "pageRef": 36 },
{ "kw": "temporary", "pageRef": 36 },
{ "kw": "file", "pageRef": 36 },
{ "kw": "or", "pageRef": 36 },
{ "kw": "directory", "pageRef": 36 },
{ "kw": "dir", "pageRef": 36 },
{ "kw": "mv", "pageRef": 37 },
{ "kw": "bare-os", "pageRef": 37 },
{ "kw": "coreutils", "pageRef": 37 },
{ "kw": "move", "pageRef": 37 },
{ "kw": "or", "pageRef": 37 },
{ "kw": "rename", "pageRef": 37 },
{ "kw": "files", "pageRef": 37 },
{ "kw": "into", "pageRef": 37 },
{ "kw": "dir", "pageRef": 37 },
{ "kw": "nl", "pageRef": 38 },
{ "kw": "bare-os", "pageRef": 38 },
{ "kw": "coreutils", "pageRef": 38 },
{ "kw": "line", "pageRef": 38 },
{ "kw": "numbering", "pageRef": 38 },
{ "kw": "utility", "pageRef": 38 },
{ "kw": "number", "pageRef": 38 },
{ "kw": "all", "pageRef": 38 },
{ "kw": "lines", "pageRef": 38 },
{ "kw": "od", "pageRef": 39 },
{ "kw": "bare-os", "pageRef": 39 },
{ "kw": "coreutils", "pageRef": 39 },
{ "kw": "octal", "pageRef": 39 },
{ "kw": "dump", "pageRef": 39 },
{ "kw": "hex", "pageRef": 39 },
{ "kw": "vibe", "pageRef": 39 },
{ "kw": "pathchk", "pageRef": 40 },
{ "kw": "bare-os", "pageRef": 40 },
{ "kw": "coreutils", "pageRef": 40 },
{ "kw": "check", "pageRef": 40 },
{ "kw": "pathname", "pageRef": 40 },
{ "kw": "portability", "pageRef": 40 },
{ "kw": "portable", "pageRef": 40 },
{ "kw": "path", "pageRef": 40 },
{ "kw": "printenv", "pageRef": 41 },
{ "kw": "bare-os", "pageRef": 41 },
{ "kw": "coreutils", "pageRef": 41 },
{ "kw": "print", "pageRef": 41 },
{ "kw": "environment", "pageRef": 41 },
{ "kw": "variables", "pageRef": 41 },
{ "kw": "one", "pageRef": 41 },
{ "kw": "variable", "pageRef": 41 },
{ "kw": "all", "pageRef": 41 },
{ "kw": "printf", "pageRef": 42 },
{ "kw": "bare-os", "pageRef": 42 },
{ "kw": "coreutils", "pageRef": 42 },
{ "kw": "format", "pageRef": 42 },
{ "kw": "and", "pageRef": 42 },
{ "kw": "print", "pageRef": 42 },
{ "kw": "no", "pageRef": 42 },
{ "kw": "newline", "pageRef": 42 },
{ "kw": "pwd", "pageRef": 43 },
{ "kw": "bare-os", "pageRef": 43 },
{ "kw": "coreutils", "pageRef": 43 },
{ "kw": "return", "pageRef": 43 },
{ "kw": "working", "pageRef": 43 },
{ "kw": "directory", "pageRef": 43 },
{ "kw": "name", "pageRef": 43 },
{ "kw": "where", "pageRef": 43 },
{ "kw": "am", "pageRef": 43 },
{ "kw": "i", "pageRef": 43 },
{ "kw": "readlink", "pageRef": 44 },
{ "kw": "bare-os", "pageRef": 44 },
{ "kw": "coreutils", "pageRef": 44 },
{ "kw": "print", "pageRef": 44 },
{ "kw": "symbolic", "pageRef": 44 },
{ "kw": "link", "pageRef": 44 },
{ "kw": "targets", "pageRef": 44 },
{ "kw": "symlink", "pageRef": 44 },
{ "kw": "target", "pageRef": 44 },
{ "kw": "rm", "pageRef": 45 },
{ "kw": "bare-os", "pageRef": 45 },
{ "kw": "coreutils", "pageRef": 45 },
{ "kw": "remove", "pageRef": 45 },
{ "kw": "files", "pageRef": 45 },
{ "kw": "file", "pageRef": 45 },
{ "kw": "tree", "pageRef": 45 },
{ "kw": "rmdir", "pageRef": 46 },
{ "kw": "bare-os", "pageRef": 46 },
{ "kw": "coreutils", "pageRef": 46 },
{ "kw": "remove", "pageRef": 46 },
{ "kw": "empty", "pageRef": 46 },
{ "kw": "directories", "pageRef": 46 },
{ "kw": "dir", "pageRef": 46 },
{ "kw": "savevault", "pageRef": 47 },
{ "kw": "vault", "pageRef": 47 },
{ "kw": "encrypt", "pageRef": 47 },
{ "kw": "backup", "pageRef": 47 },
{ "kw": "snapshot", "pageRef": 47 },
{ "kw": "of", "pageRef": 47 },
{ "kw": "personal", "pageRef": 47 },
{ "kw": "drive", "pageRef": 47 },
{ "kw": "encrypted", "pageRef": 47 },
{ "kw": "sed", "pageRef": 48 },
{ "kw": "stream", "pageRef": 48 },
{ "kw": "edit", "pageRef": 48 },
{ "kw": "substitute", "pageRef": 48 },
{ "kw": "editor", "pageRef": 48 },
{ "kw": "first", "pageRef": 48 },
{ "kw": "per", "pageRef": 48 },
{ "kw": "line", "pageRef": 48 },
{ "kw": "global", "pageRef": 48 },
{ "kw": "in-place", "pageRef": 48 },
{ "kw": "if", "pageRef": 48 },
{ "kw": "supported", "pageRef": 48 },
{ "kw": "print", "pageRef": 48 },
{ "kw": "5", "pageRef": 48 },
{ "kw": "only", "pageRef": 48 },
{ "kw": "delete", "pageRef": 48 },
{ "kw": "blank", "pageRef": 48 },
{ "kw": "lines", "pageRef": 48 },
{ "kw": "seq", "pageRef": 49 },
{ "kw": "bare-os", "pageRef": 49 },
{ "kw": "coreutils", "pageRef": 49 },
{ "kw": "print", "pageRef": 49 },
{ "kw": "sequences", "pageRef": 49 },
{ "kw": "of", "pageRef": 49 },
{ "kw": "numbers", "pageRef": 49 },
{ "kw": "1", "pageRef": 49 },
{ "kw": "10", "pageRef": 49 },
{ "kw": "step", "pageRef": 49 },
{ "kw": "sleep", "pageRef": 50 },
{ "kw": "bare-os", "pageRef": 50 },
{ "kw": "coreutils", "pageRef": 50 },
{ "kw": "suspend", "pageRef": 50 },
{ "kw": "execution", "pageRef": 50 },
{ "kw": "for", "pageRef": 50 },
{ "kw": "an", "pageRef": 50 },
{ "kw": "interval", "pageRef": 50 },
{ "kw": "pause", "pageRef": 50 },
{ "kw": "seconds", "pageRef": 50 },
{ "kw": "sort", "pageRef": 51 },
{ "kw": "bare-os", "pageRef": 51 },
{ "kw": "coreutils", "pageRef": 51 },
{ "kw": "lines", "pageRef": 51 },
{ "kw": "lexicographic", "pageRef": 51 },
{ "kw": "numeric", "pageRef": 51 },
{ "kw": "unique", "pageRef": 51 },
{ "kw": "stat", "pageRef": 52 },
{ "kw": "bare-os", "pageRef": 52 },
{ "kw": "coreutils", "pageRef": 52 },
{ "kw": "display", "pageRef": 52 },
{ "kw": "file", "pageRef": 52 },
{ "kw": "status", "pageRef": 52 },
{ "kw": "metadata", "pageRef": 52 },
{ "kw": "tail", "pageRef": 53 },
{ "kw": "bare-os", "pageRef": 53 },
{ "kw": "coreutils", "pageRef": 53 },
{ "kw": "copy", "pageRef": 53 },
{ "kw": "the", "pageRef": 53 },
{ "kw": "last", "pageRef": 53 },
{ "kw": "part", "pageRef": 53 },
{ "kw": "of", "pageRef": 53 },
{ "kw": "a", "pageRef": 53 },
{ "kw": "file", "pageRef": 53 },
{ "kw": "lines", "pageRef": 53 },
{ "kw": "follow", "pageRef": 53 },
{ "kw": "vibe", "pageRef": 53 },
{ "kw": "bare", "pageRef": 53 },
{ "kw": "poll", "pageRef": 53 },
{ "kw": "manually", "pageRef": 53 },
{ "kw": "tee", "pageRef": 54 },
{ "kw": "bare-os", "pageRef": 54 },
{ "kw": "coreutils", "pageRef": 54 },
{ "kw": "duplicate", "pageRef": 54 },
{ "kw": "standard", "pageRef": 54 },
{ "kw": "input", "pageRef": 54 },
{ "kw": "copy", "pageRef": 54 },
{ "kw": "stdout", "pageRef": 54 },
{ "kw": "to", "pageRef": 54 },
{ "kw": "file", "pageRef": 54 },
{ "kw": "test", "pageRef": 55 },
{ "kw": "bare-os", "pageRef": 55 },
{ "kw": "coreutils", "pageRef": 55 },
{ "kw": "evaluate", "pageRef": 55 },
{ "kw": "a", "pageRef": 55 },
{ "kw": "condition", "pageRef": 55 },
{ "kw": "file", "pageRef": 55 },
{ "kw": "exists", "pageRef": 55 },
{ "kw": "directory", "pageRef": 55 },
{ "kw": "string", "pageRef": 55 },
{ "kw": "equal", "pageRef": 55 },
{ "kw": "time", "pageRef": 56 },
{ "kw": "bare-os", "pageRef": 56 },
{ "kw": "coreutils", "pageRef": 56 },
{ "kw": "a", "pageRef": 56 },
{ "kw": "simple", "pageRef": 56 },
{ "kw": "command", "pageRef": 56 },
{ "kw": "wall", "pageRef": 56 },
{ "kw": "touch", "pageRef": 57 },
{ "kw": "bare-os", "pageRef": 57 },
{ "kw": "coreutils", "pageRef": 57 },
{ "kw": "change", "pageRef": 57 },
{ "kw": "file", "pageRef": 57 },
{ "kw": "timestamps", "pageRef": 57 },
{ "kw": "or", "pageRef": 57 },
{ "kw": "create", "pageRef": 57 },
{ "kw": "files", "pageRef": 57 },
{ "kw": "empty", "pageRef": 57 },
{ "kw": "refresh", "pageRef": 57 },
{ "kw": "mtime", "pageRef": 57 },
{ "kw": "tr", "pageRef": 58 },
{ "kw": "bare-os", "pageRef": 58 },
{ "kw": "coreutils", "pageRef": 58 },
{ "kw": "translate", "pageRef": 58 },
{ "kw": "or", "pageRef": 58 },
{ "kw": "delete", "pageRef": 58 },
{ "kw": "characters", "pageRef": 58 },
{ "kw": "uppercase", "pageRef": 58 },
{ "kw": "chars", "pageRef": 58 },
{ "kw": "true", "pageRef": 59 },
{ "kw": "bare-os", "pageRef": 59 },
{ "kw": "coreutils", "pageRef": 59 },
{ "kw": "return", "pageRef": 59 },
{ "kw": "value", "pageRef": 59 },
{ "kw": "always", "pageRef": 59 },
{ "kw": "success", "pageRef": 59 },
{ "kw": "tty", "pageRef": 60 },
{ "kw": "bare-os", "pageRef": 60 },
{ "kw": "coreutils", "pageRef": 60 },
{ "kw": "return", "pageRef": 60 },
{ "kw": "user", "pageRef": 60 },
{ "kw": "s", "pageRef": 60 },
{ "kw": "terminal", "pageRef": 60 },
{ "kw": "name", "pageRef": 60 },
{ "kw": "am", "pageRef": 60 },
{ "kw": "i", "pageRef": 60 },
{ "kw": "a", "pageRef": 60 },
{ "kw": "uname", "pageRef": 61 },
{ "kw": "bare-os", "pageRef": 61 },
{ "kw": "coreutils", "pageRef": 61 },
{ "kw": "return", "pageRef": 61 },
{ "kw": "operating", "pageRef": 61 },
{ "kw": "system", "pageRef": 61 },
{ "kw": "name", "pageRef": 61 },
{ "kw": "kernel-ish", "pageRef": 61 },
{ "kw": "info", "pageRef": 61 },
{ "kw": "wc", "pageRef": 62 },
{ "kw": "bare-os", "pageRef": 62 },
{ "kw": "coreutils", "pageRef": 62 },
{ "kw": "word", "pageRef": 62 },
{ "kw": "line", "pageRef": 62 },
{ "kw": "and", "pageRef": 62 },
{ "kw": "byte", "pageRef": 62 },
{ "kw": "or", "pageRef": 62 },
{ "kw": "character", "pageRef": 62 },
{ "kw": "count", "pageRef": 62 },
{ "kw": "lines", "pageRef": 62 },
{ "kw": "words", "pageRef": 62 },
{ "kw": "bytes", "pageRef": 62 },
{ "kw": "stdin", "pageRef": 62 },
{ "kw": "only", "pageRef": 62 },
{ "kw": "which", "pageRef": 63 },
{ "kw": "bare-os", "pageRef": 63 },
{ "kw": "coreutils", "pageRef": 63 },
{ "kw": "locate", "pageRef": 63 },
{ "kw": "a", "pageRef": 63 },
{ "kw": "command", "pageRef": 63 },
{ "kw": "resolve", "pageRef": 63 },
{ "kw": "on", "pageRef": 63 },
{ "kw": "path", "pageRef": 63 },
{ "kw": "whoami", "pageRef": 64 },
{ "kw": "bare-os", "pageRef": 64 },
{ "kw": "coreutils", "pageRef": 64 },
{ "kw": "display", "pageRef": 64 },
{ "kw": "effective", "pageRef": 64 },
{ "kw": "user", "pageRef": 64 },
{ "kw": "id", "pageRef": 64 },
{ "kw": "xargs", "pageRef": 65 },
{ "kw": "arguments", "pageRef": 65 },
{ "kw": "bare-os", "pageRef": 65 },
{ "kw": "coreutils", "pageRef": 65 },
{ "kw": "construct", "pageRef": 65 },
{ "kw": "argument", "pageRef": 65 },
{ "kw": "lists", "pageRef": 65 },
{ "kw": "and", "pageRef": 65 },
{ "kw": "invoke", "pageRef": 65 },
{ "kw": "utility", "pageRef": 65 },
{ "kw": "pass", "pageRef": 65 },
{ "kw": "lines", "pageRef": 65 },
{ "kw": "as", "pageRef": 65 },
{ "kw": "one", "pageRef": 65 },
{ "kw": "per", "pageRef": 65 },
{ "kw": "run", "pageRef": 65 },
{ "kw": "workaround", "pageRef": 65 },
{ "kw": "for", "pageRef": 65 },
{ "kw": "complex", "pageRef": 65 },
{ "kw": "scripts", "pageRef": 65 },
{ "kw": "shell", "pageRef": 66 },
{ "kw": "builtin", "pageRef": 66 },
{ "kw": "cd", "pageRef": 66 },
{ "kw": "export", "pageRef": 66 },
{ "kw": "alias", "pageRef": 66 },
{ "kw": "bare-os-shell", "pageRef": 66 },
{ "kw": "sh-builtins", "pageRef": 66 },
{ "kw": "bare", "pageRef": 66 },
{ "kw": "os", "pageRef": 66 },
{ "kw": "interactive", "pageRef": 66 },
{ "kw": "builtins", "pageRef": 66 },
{ "kw": "pipeline", "pageRef": 66 },
{ "kw": "simulated", "pageRef": 66 },
{ "kw": "redirect", "pageRef": 66 },
{ "kw": "out", "pageRef": 66 },
{ "kw": "append", "pageRef": 66 },
{ "kw": "use", "pageRef": 66 },
{ "kw": "for", "pageRef": 66 },
{ "kw": "children", "pageRef": 66 },
{ "kw": "temp", "pageRef": 66 },
{ "kw": "var", "pageRef": 66 },
{ "kw": "one", "pageRef": 66 },
{ "kw": "command", "pageRef": 66 },
{ "kw": "bare-initd", "pageRef": 67 },
{ "kw": "initctl", "pageRef": 67 },
{ "kw": "service", "pageRef": 67 },
{ "kw": "supervisor", "pageRef": 67 },
{ "kw": "cron", "pageRef": 67 },
{ "kw": "systemd", "pageRef": 67 },
{ "kw": "systemctl", "pageRef": 67 },
{ "kw": "control", "pageRef": 67 },
{ "kw": "systemd-like", "pageRef": 67 },
{ "kw": "subset", "pageRef": 67 },
{ "kw": "list", "pageRef": 67 },
{ "kw": "units", "pageRef": 67 },
{ "kw": "restart", "pageRef": 67 },
{ "kw": "scheduler", "pageRef": 67 },
{ "kw": "tail", "pageRef": 67 },
{ "kw": "errors", "pageRef": 67 },
{ "kw": "curl", "pageRef": 68 },
{ "kw": "http", "pageRef": 68 },
{ "kw": "https", "pageRef": 68 },
{ "kw": "fetch", "pageRef": 68 },
{ "kw": "download", "pageRef": 68 },
{ "kw": "transfer", "pageRef": 68 },
{ "kw": "a", "pageRef": 68 },
{ "kw": "url", "pageRef": 68 },
{ "kw": "fetch-based", "pageRef": 68 },
{ "kw": "client", "pageRef": 68 },
{ "kw": "not", "pageRef": 68 },
{ "kw": "libcurl", "pageRef": 68 },
{ "kw": "git", "pageRef": 69 },
{ "kw": "version control", "pageRef": 69 },
{ "kw": "repository", "pageRef": 69 },
{ "kw": "clone", "pageRef": 69 },
{ "kw": "commit", "pageRef": 69 },
{ "kw": "isomorphic-git", "pageRef": 69 },
{ "kw": "bare", "pageRef": 69 },
{ "kw": "os", "pageRef": 69 },
{ "kw": "front-end", "pageRef": 69 },
{ "kw": "new", "pageRef": 69 },
{ "kw": "repo", "pageRef": 69 },
{ "kw": "status", "pageRef": 69 },
{ "kw": "over", "pageRef": 69 },
{ "kw": "http", "pageRef": 69 },
{ "kw": "needs", "pageRef": 69 },
{ "kw": "remote", "pageRef": 69 },
{ "kw": "fetch", "pageRef": 69 },
{ "kw": "config", "pageRef": 69 },
{ "kw": "local", "pageRef": 69 },
{ "kw": "log", "pageRef": 69 },
{ "kw": "one", "pageRef": 69 },
{ "kw": "line", "pageRef": 69 },
{ "kw": "wget", "pageRef": 70 },
{ "kw": "download", "pageRef": 70 },
{ "kw": "http", "pageRef": 70 },
{ "kw": "https", "pageRef": 70 },
{ "kw": "fetch", "pageRef": 70 },
{ "kw": "mirror", "pageRef": 70 },
{ "kw": "non-interactive", "pageRef": 70 },
{ "kw": "network", "pageRef": 70 },
{ "kw": "fetch-based", "pageRef": 70 },
{ "kw": "not", "pageRef": 70 },
{ "kw": "gnu", "pageRef": 70 },
{ "kw": "wget2", "pageRef": 70 },
{ "kw": "save", "pageRef": 70 },
{ "kw": "with", "pageRef": 70 },
{ "kw": "default", "pageRef": 70 },
{ "kw": "name", "pageRef": 70 },
{ "kw": "in", "pageRef": 70 },
{ "kw": "cwd", "pageRef": 70 },
{ "kw": "choose", "pageRef": 70 },
{ "kw": "output", "pageRef": 70 },
{ "kw": "path", "pageRef": 70 },
{ "kw": "directory", "pageRef": 70 },
{ "kw": "prefix", "pageRef": 70 },
{ "kw": "stdout", "pageRef": 70 },
{ "kw": "resume", "pageRef": 70 },
{ "kw": "partial", "pageRef": 70 },
{ "kw": "file", "pageRef": 70 },
{ "kw": "handbook", "pageRef": 71 },
{ "kw": "bare-os", "pageRef": 71 },
{ "kw": "documentation", "pageRef": 71 },
{ "kw": "narrative", "pageRef": 71 },
{ "kw": "chapter", "pageRef": 71 },
{ "kw": "bare", "pageRef": 71 },
{ "kw": "os", "pageRef": 71 },
{ "kw": "table", "pageRef": 71 },
{ "kw": "contents", "pageRef": 71 },
{ "kw": "and", "pageRef": 71 },
{ "kw": "reading", "pageRef": 71 },
{ "kw": "order", "pageRef": 71 },
{ "kw": "bare-os-handbook", "pageRef": 71 },
{ "kw": "of", "pageRef": 71 },
{ "kw": "handbook", "pageRef": 72 },
{ "kw": "bare-os", "pageRef": 72 },
{ "kw": "documentation", "pageRef": 72 },
{ "kw": "narrative", "pageRef": 72 },
{ "kw": "chapter", "pageRef": 72 },
{ "kw": "01", "pageRef": 72 },
{ "kw": "introduction", "pageRef": 72 },
{ "kw": "what", "pageRef": 72 },
{ "kw": "bare", "pageRef": 72 },
{ "kw": "handbook-01-introduction", "pageRef": 72 },
{ "kw": "1", "pageRef": 72 },
{ "kw": "os", "pageRef": 72 },
{ "kw": "is", "pageRef": 72 },
{ "kw": "handbook", "pageRef": 73 },
{ "kw": "bare-os", "pageRef": 73 },
{ "kw": "documentation", "pageRef": 73 },
{ "kw": "narrative", "pageRef": 73 },
{ "kw": "chapter", "pageRef": 73 },
{ "kw": "02", "pageRef": 73 },
{ "kw": "blueprints", "pageRef": 73 },
{ "kw": "architecture", "pageRef": 73 },
{ "kw": "and", "pageRef": 73 },
{ "kw": "trust", "pageRef": 73 },
{ "kw": "handbook-02-blueprints", "pageRef": 73 },
{ "kw": "2", "pageRef": 73 },
{ "kw": "handbook", "pageRef": 74 },
{ "kw": "bare-os", "pageRef": 74 },
{ "kw": "documentation", "pageRef": 74 },
{ "kw": "narrative", "pageRef": 74 },
{ "kw": "chapter", "pageRef": 74 },
{ "kw": "03", "pageRef": 74 },
{ "kw": "protocol", "pageRef": 74 },
{ "kw": "and", "pageRef": 74 },
{ "kw": "disk", "pageRef": 74 },
{ "kw": "mbr", "pageRef": 74 },
{ "kw": "swarmdisk", "pageRef": 74 },
{ "kw": "handbook-03-protocol-and-disk", "pageRef": 74 },
{ "kw": "3", "pageRef": 74 },
{ "kw": "handbook", "pageRef": 75 },
{ "kw": "bare-os", "pageRef": 75 },
{ "kw": "documentation", "pageRef": 75 },
{ "kw": "narrative", "pageRef": 75 },
{ "kw": "chapter", "pageRef": 75 },
{ "kw": "04", "pageRef": 75 },
{ "kw": "the", "pageRef": 75 },
{ "kw": "booter", "pageRef": 75 },
{ "kw": "runtime", "pageRef": 75 },
{ "kw": "ctx", "pageRef": 75 },
{ "kw": "vfs", "pageRef": 75 },
{ "kw": "shell", "pageRef": 75 },
{ "kw": "kernel", "pageRef": 75 },
{ "kw": "services", "pageRef": 75 },
{ "kw": "handbook-04-the-booter-runtime", "pageRef": 75 },
{ "kw": "4", "pageRef": 75 },
{ "kw": "handbook", "pageRef": 76 },
{ "kw": "bare-os", "pageRef": 76 },
{ "kw": "documentation", "pageRef": 76 },
{ "kw": "narrative", "pageRef": 76 },
{ "kw": "chapter", "pageRef": 76 },
{ "kw": "05", "pageRef": 76 },
{ "kw": "identity", "pageRef": 76 },
{ "kw": "vault", "pageRef": 76 },
{ "kw": "and", "pageRef": 76 },
{ "kw": "hdms", "pageRef": 76 },
{ "kw": "handbook-05-identity-vault-and-hdms", "pageRef": 76 },
{ "kw": "5", "pageRef": 76 },
{ "kw": "handbook", "pageRef": 77 },
{ "kw": "bare-os", "pageRef": 77 },
{ "kw": "documentation", "pageRef": 77 },
{ "kw": "narrative", "pageRef": 77 },
{ "kw": "chapter", "pageRef": 77 },
{ "kw": "06", "pageRef": 77 },
{ "kw": "kernel", "pageRef": 77 },
{ "kw": "and", "pageRef": 77 },
{ "kw": "binaries", "pageRef": 77 },
{ "kw": "bin", "pageRef": 77 },
{ "kw": "utilities", "pageRef": 77 },
{ "kw": "handbook-06-kernel-and-binaries", "pageRef": 77 },
{ "kw": "6", "pageRef": 77 },
{ "kw": "handbook", "pageRef": 78 },
{ "kw": "bare-os", "pageRef": 78 },
{ "kw": "documentation", "pageRef": 78 },
{ "kw": "narrative", "pageRef": 78 },
{ "kw": "chapter", "pageRef": 78 },
{ "kw": "07", "pageRef": 78 },
{ "kw": "operations", "pageRef": 78 },
{ "kw": "and", "pageRef": 78 },
{ "kw": "development", "pageRef": 78 },
{ "kw": "release", "pageRef": 78 },
{ "kw": "handbook-07-operations-and-development", "pageRef": 78 },
{ "kw": "7", "pageRef": 78 },
{ "kw": "handbook", "pageRef": 79 },
{ "kw": "bare-os", "pageRef": 79 },
{ "kw": "documentation", "pageRef": 79 },
{ "kw": "narrative", "pageRef": 79 },
{ "kw": "chapter", "pageRef": 79 },
{ "kw": "08", "pageRef": 79 },
{ "kw": "git", "pageRef": 79 },
{ "kw": "on", "pageRef": 79 },
{ "kw": "bare", "pageRef": 79 },
{ "kw": "os", "pageRef": 79 },
{ "kw": "handbook-08-git-on-bare-os", "pageRef": 79 },
{ "kw": "handbook", "pageRef": 80 },
{ "kw": "bare-os", "pageRef": 80 },
{ "kw": "documentation", "pageRef": 80 },
{ "kw": "narrative", "pageRef": 80 },
{ "kw": "chapter", "pageRef": 80 },
{ "kw": "09", "pageRef": 80 },
{ "kw": "posix", "pageRef": 80 },
{ "kw": "utilities", "pageRef": 80 },
{ "kw": "shell", "pageRef": 80 },
{ "kw": "and", "pageRef": 80 },
{ "kw": "vfs", "pageRef": 80 },
{ "kw": "style", "pageRef": 80 },
{ "kw": "builtins", "pageRef": 80 },
{ "kw": "alignment", "pageRef": 80 },
{ "kw": "handbook-09-posix-utilities-shell-and-vfs", "pageRef": 80 },
{ "kw": "9", "pageRef": 80 },
{ "kw": "posix-style", "pageRef": 80 },
{ "kw": "handbook", "pageRef": 81 },
{ "kw": "bare-os", "pageRef": 81 },
{ "kw": "documentation", "pageRef": 81 },
{ "kw": "narrative", "pageRef": 81 },
{ "kw": "chapter", "pageRef": 81 },
{ "kw": "10", "pageRef": 81 },
{ "kw": "manpages", "pageRef": 81 },
{ "kw": "and", "pageRef": 81 },
{ "kw": "online", "pageRef": 81 },
{ "kw": "help", "pageRef": 81 },
{ "kw": "manual", "pageRef": 81 },
{ "kw": "pages", "pageRef": 81 },
{ "kw": "man", "pageRef": 81 },
{ "kw": "handbook-10-manpages-and-online-help", "pageRef": 81 },
{ "kw": "developer", "pageRef": 82 },
{ "kw": "devguide", "pageRef": 82 },
{ "kw": "develop", "pageRef": 82 },
{ "kw": "script", "pageRef": 82 },
{ "kw": "asyncfunction", "pageRef": 82 },
{ "kw": "ctx", "pageRef": 82 },
{ "kw": "bare-os", "pageRef": 82 },
{ "kw": "guide", "pageRef": 82 },
{ "kw": "bare", "pageRef": 82 },
{ "kw": "os", "pageRef": 82 },
{ "kw": "index", "pageRef": 82 },
{ "kw": "and", "pageRef": 82 },
{ "kw": "reading", "pageRef": 82 },
{ "kw": "order", "pageRef": 82 },
{ "kw": "bare-os-developer-guide", "pageRef": 82 },
{ "kw": "developer", "pageRef": 83 },
{ "kw": "devguide", "pageRef": 83 },
{ "kw": "develop", "pageRef": 83 },
{ "kw": "script", "pageRef": 83 },
{ "kw": "asyncfunction", "pageRef": 83 },
{ "kw": "ctx", "pageRef": 83 },
{ "kw": "bare-os", "pageRef": 83 },
{ "kw": "guide", "pageRef": 83 },
{ "kw": "01", "pageRef": 83 },
{ "kw": "two", "pageRef": 83 },
{ "kw": "runtimes", "pageRef": 83 },
{ "kw": "host", "pageRef": 83 },
{ "kw": "vs", "pageRef": 83 },
{ "kw": "image", "pageRef": 83 },
{ "kw": "chapter", "pageRef": 83 },
{ "kw": "pear", "pageRef": 83 },
{ "kw": "node", "pageRef": 83 },
{ "kw": "devguide-01-two-runtimes-host-vs-image", "pageRef": 83 },
{ "kw": "1", "pageRef": 83 },
{ "kw": "in-image", "pageRef": 83 },
{ "kw": "developer", "pageRef": 84 },
{ "kw": "devguide", "pageRef": 84 },
{ "kw": "develop", "pageRef": 84 },
{ "kw": "script", "pageRef": 84 },
{ "kw": "asyncfunction", "pageRef": 84 },
{ "kw": "ctx", "pageRef": 84 },
{ "kw": "bare-os", "pageRef": 84 },
{ "kw": "guide", "pageRef": 84 },
{ "kw": "02", "pageRef": 84 },
{ "kw": "the", "pageRef": 84 },
{ "kw": "context", "pageRef": 84 },
{ "kw": "object", "pageRef": 84 },
{ "kw": "chapter", "pageRef": 84 },
{ "kw": "devguide-02-the-context-object", "pageRef": 84 },
{ "kw": "2", "pageRef": 84 },
{ "kw": "developer", "pageRef": 85 },
{ "kw": "devguide", "pageRef": 85 },
{ "kw": "develop", "pageRef": 85 },
{ "kw": "script", "pageRef": 85 },
{ "kw": "asyncfunction", "pageRef": 85 },
{ "kw": "ctx", "pageRef": 85 },
{ "kw": "bare-os", "pageRef": 85 },
{ "kw": "guide", "pageRef": 85 },
{ "kw": "03", "pageRef": 85 },
{ "kw": "kernel", "pageRef": 85 },
{ "kw": "boot", "pageRef": 85 },
{ "kw": "init", "pageRef": 85 },
{ "kw": "chapter", "pageRef": 85 },
{ "kw": "and", "pageRef": 85 },
{ "kw": "start", "pageRef": 85 },
{ "kw": "devguide-03-kernel-boot-init", "pageRef": 85 },
{ "kw": "3", "pageRef": 85 },
{ "kw": "js", "pageRef": 85 },
{ "kw": "developer", "pageRef": 86 },
{ "kw": "devguide", "pageRef": 86 },
{ "kw": "develop", "pageRef": 86 },
{ "kw": "script", "pageRef": 86 },
{ "kw": "asyncfunction", "pageRef": 86 },
{ "kw": "ctx", "pageRef": 86 },
{ "kw": "bare-os", "pageRef": 86 },
{ "kw": "guide", "pageRef": 86 },
{ "kw": "04", "pageRef": 86 },
{ "kw": "user", "pageRef": 86 },
{ "kw": "scripts", "pageRef": 86 },
{ "kw": "and", "pageRef": 86 },
{ "kw": "path", "pageRef": 86 },
{ "kw": "chapter", "pageRef": 86 },
{ "kw": "resolution", "pageRef": 86 },
{ "kw": "devguide-04-user-scripts-and-path", "pageRef": 86 },
{ "kw": "4", "pageRef": 86 },
{ "kw": "developer", "pageRef": 87 },
{ "kw": "devguide", "pageRef": 87 },
{ "kw": "develop", "pageRef": 87 },
{ "kw": "script", "pageRef": 87 },
{ "kw": "asyncfunction", "pageRef": 87 },
{ "kw": "ctx", "pageRef": 87 },
{ "kw": "bare-os", "pageRef": 87 },
{ "kw": "guide", "pageRef": 87 },
{ "kw": "05", "pageRef": 87 },
{ "kw": "modules", "pageRef": 87 },
{ "kw": "and", "pageRef": 87 },
{ "kw": "imports", "pageRef": 87 },
{ "kw": "chapter", "pageRef": 87 },
{ "kw": "import", "pageRef": 87 },
{ "kw": "packaging", "pageRef": 87 },
{ "kw": "the", "pageRef": 87 },
{ "kw": "honest", "pageRef": 87 },
{ "kw": "version", "pageRef": 87 },
{ "kw": "devguide-05-modules-and-imports", "pageRef": 87 },
{ "kw": "5", "pageRef": 87 },
{ "kw": "developer", "pageRef": 88 },
{ "kw": "devguide", "pageRef": 88 },
{ "kw": "develop", "pageRef": 88 },
{ "kw": "script", "pageRef": 88 },
{ "kw": "asyncfunction", "pageRef": 88 },
{ "kw": "ctx", "pageRef": 88 },
{ "kw": "bare-os", "pageRef": 88 },
{ "kw": "guide", "pageRef": 88 },
{ "kw": "06", "pageRef": 88 },
{ "kw": "extending", "pageRef": 88 },
{ "kw": "bin", "pageRef": 88 },
{ "kw": "coreutils", "pageRef": 88 },
{ "kw": "chapter", "pageRef": 88 },
{ "kw": "bare", "pageRef": 88 },
{ "kw": "devguide-06-extending-bin-coreutils", "pageRef": 88 },
{ "kw": "6", "pageRef": 88 },
{ "kw": "bare-os-coreutils", "pageRef": 88 },
{ "kw": "developer", "pageRef": 89 },
{ "kw": "devguide", "pageRef": 89 },
{ "kw": "develop", "pageRef": 89 },
{ "kw": "script", "pageRef": 89 },
{ "kw": "asyncfunction", "pageRef": 89 },
{ "kw": "ctx", "pageRef": 89 },
{ "kw": "bare-os", "pageRef": 89 },
{ "kw": "guide", "pageRef": 89 },
{ "kw": "07", "pageRef": 89 },
{ "kw": "apps", "pageRef": 89 },
{ "kw": "beyond", "pageRef": 89 },
{ "kw": "the", "pageRef": 89 },
{ "kw": "shell", "pageRef": 89 },
{ "kw": "chapter", "pageRef": 89 },
{ "kw": "what", "pageRef": 89 },
{ "kw": "realistic", "pageRef": 89 },
{ "kw": "today", "pageRef": 89 },
{ "kw": "devguide-07-apps-beyond-the-shell", "pageRef": 89 },
{ "kw": "7", "pageRef": 89 },
{ "kw": "is", "pageRef": 89 },
{ "kw": "developer", "pageRef": 90 },
{ "kw": "devguide", "pageRef": 90 },
{ "kw": "develop", "pageRef": 90 },
{ "kw": "script", "pageRef": 90 },
{ "kw": "asyncfunction", "pageRef": 90 },
{ "kw": "ctx", "pageRef": 90 },
{ "kw": "bare-os", "pageRef": 90 },
{ "kw": "guide", "pageRef": 90 },
{ "kw": "08", "pageRef": 90 },
{ "kw": "testing", "pageRef": 90 },
{ "kw": "and", "pageRef": 90 },
{ "kw": "debugging", "pageRef": 90 },
{ "kw": "chapter", "pageRef": 90 },
{ "kw": "devguide-08-testing-and-debugging", "pageRef": 90 },
{ "kw": "8", "pageRef": 90 },
{ "kw": "developer", "pageRef": 91 },
{ "kw": "devguide", "pageRef": 91 },
{ "kw": "develop", "pageRef": 91 },
{ "kw": "script", "pageRef": 91 },
{ "kw": "asyncfunction", "pageRef": 91 },
{ "kw": "ctx", "pageRef": 91 },
{ "kw": "bare-os", "pageRef": 91 },
{ "kw": "guide", "pageRef": 91 },
{ "kw": "09", "pageRef": 91 },
{ "kw": "security", "pageRef": 91 },
{ "kw": "and", "pageRef": 91 },
{ "kw": "trust", "pageRef": 91 },
{ "kw": "chapter", "pageRef": 91 },
{ "kw": "mindset", "pageRef": 91 },
{ "kw": "devguide-09-security-and-trust", "pageRef": 91 },
{ "kw": "9", "pageRef": 91 },
{ "kw": "developer", "pageRef": 92 },
{ "kw": "devguide", "pageRef": 92 },
{ "kw": "develop", "pageRef": 92 },
{ "kw": "script", "pageRef": 92 },
{ "kw": "asyncfunction", "pageRef": 92 },
{ "kw": "ctx", "pageRef": 92 },
{ "kw": "bare-os", "pageRef": 92 },
{ "kw": "guide", "pageRef": 92 },
{ "kw": "10", "pageRef": 92 },
{ "kw": "glossary", "pageRef": 92 },
{ "kw": "and", "pageRef": 92 },
{ "kw": "faq", "pageRef": 92 },
{ "kw": "chapter", "pageRef": 92 },
{ "kw": "devguide-10-glossary-and-faq", "pageRef": 92 },
{ "kw": "developer", "pageRef": 93 },
{ "kw": "devguide", "pageRef": 93 },
{ "kw": "develop", "pageRef": 93 },
{ "kw": "script", "pageRef": 93 },
{ "kw": "asyncfunction", "pageRef": 93 },
{ "kw": "ctx", "pageRef": 93 },
{ "kw": "bare-os", "pageRef": 93 },
{ "kw": "guide", "pageRef": 93 },
{ "kw": "11", "pageRef": 93 },
{ "kw": "kernel", "pageRef": 93 },
{ "kw": "pear", "pageRef": 93 },
{ "kw": "cookbook", "pageRef": 93 },
{ "kw": "chapter", "pageRef": 93 },
{ "kw": "extensions", "pageRef": 93 },
{ "kw": "and", "pageRef": 93 },
{ "kw": "workflows", "pageRef": 93 },
{ "kw": "devguide-11-kernel-pear-cookbook", "pageRef": 93 }
]
}
Reference in New Issue View Git Blame Copy Permalink