bare-operating-system/packages/bare-os-coreutils/man/pages/bare-os-shell.json

{
  "name": "bare-os-shell",
  "section": 1,
  "title": "Bare OS interactive shell (Issue 7–inspired subset)",
  "synopsis": [
    "# Interactive session: builtins + /bin via ctx.execLine (see handbook §9)",
    "# /bin/sh is a separate script runner — see man sh"
  ],
  "description": "The interactive shell runs in the booter: tokenization, pipelines (simulated capture), redirection, AND-OR lists (; && ||), bounded compound commands (if/fi, while/for/case), background jobs (&), optional command substitution ($(…)) when BARE_OS_SHELL_CMDSUBST=1, globbing, and subsets of errexit (-e), nounset (-u), and pipefail. There are no forked subshells and no full POSIX sh grammar. Canonical narrative: handbook ch.9; completion/REPL: docs/reference/shell-completion-and-repl-editor.md.",
  "options": [],
  "aliases": [
    "sh-builtins"
  ],
  "keywords": [
    "shell",
    "builtin",
    "pipeline",
    "jobs",
    "execLine",
    "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": "set",
      "synopsis": [
        "set -o",
        "set +o",
        "set -e | +e | -u | +u | -f | +f",
        "set -o errexit|nounset|pipefail",
        "set +o errexit|nounset|pipefail"
      ],
      "description": "Toggle errexit (BARE_OS_SHELL_ERREXIT), nounset (BARE_OS_SHELL_NOUNSET), pipefail (BARE_OS_SHELL_PIPEFAIL), noglob (BARE_OS_SHELL_NOGLOB). Use set -o / set +o alone to print current shell options (subset)."
    },
    {
      "name": "command",
      "synopsis": [
        "command -v|-V NAME",
        "command ARGV..."
      ],
      "description": "Resolve or run a command; -v/-V skip aliases."
    },
    {
      "name": "type",
      "synopsis": [
        "type NAME"
      ],
      "description": "Report whether NAME is a builtin or a path under PATH."
    },
    {
      "name": "jobs",
      "synopsis": [
        "jobs [-l] [-p]"
      ],
      "description": "List logical background jobs. -p prints pgid only; -l includes pgid/sid in the listing."
    },
    {
      "name": "fg / bg / wait",
      "synopsis": [
        "fg [%job]",
        "bg [%job]",
        "wait [n | %n]",
        "wait -n  (with BARE_OS_SHELL_POSIX_MODE=1)"
      ],
      "description": "Cooperative job control: fg awaits a job; bg resumes stopped jobs; wait waits for jobs by id or all."
    },
    {
      "name": "suspend-job",
      "synopsis": [
        "suspend-job [%job]"
      ],
      "description": "Mark a running background job stopped (logical); resume with fg or bg."
    },
    {
      "name": "disown",
      "synopsis": [
        "disown [%job]"
      ],
      "description": "Remove a job from the jobs table without cancelling its async work (still runs to completion)."
    },
    {
      "name": "trap",
      "synopsis": [
        "trap -l",
        "trap -p",
        "trap CMD SIGNAL"
      ],
      "description": "List signals, print handlers, or register synthetic trap handlers (ctx.shellTrapHandlers)."
    },
    {
      "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)."
    },
    {
      "name": "read",
      "synopsis": [
        "read [-r] [NAME ...]"
      ],
      "description": "Optional when BARE_OS_SHELL_READ_BUILTIN=1; bounded line from shell stdin or readLine."
    }
  ],
  "seeAlso": [
    {
      "name": "sh",
      "section": 1
    },
    {
      "name": "help",
      "section": 1
    },
    {
      "name": "man",
      "section": 1
    }
  ],
  "bareOsNotes": "Pipelines use simulated capture (not OS pipes). kill and wait accept %n job specs when shellBackgroundJobs is populated. Full UX (history file, tab menu, Ctrl+R) uses BARE_OS_FISH≠0 on a TTY; see shell-completion-and-repl-editor.md.",
  "examples": [
    {
      "caption": "pipeline (simulated)",
      "code": "ls -1 /bin | grep man"
    },
    {
      "caption": "errexit + compound",
      "code": "set -e\nif true; then echo ok; fi"
    },
    {
      "caption": "background job",
      "code": "sleep 1 &\njobs"
    },
    {
      "caption": "redirect out",
      "code": "echo hi > ~/hello.txt"
    },
    {
      "caption": "alias + use",
      "code": "alias ll='ls -la'\nll ~"
    }
  ]
}