# shell(1)

    NAME
        shell - MontaukOS interactive command shell

    DESCRIPTION
        The MontaukOS shell is a command interpreter launched by init
        after system services have started. It provides command
        execution, file navigation, shell variables, command chaining,
        tab completion, and command history.

        Commands are either shell builtins or external programs. When
        a command is not a builtin, the shell searches for a matching
        ELF binary and executes it as a child process.

    COMMAND RESOLUTION
        When a non-builtin command is entered, the shell searches for
        a matching binary in the following order:

            1. <cwd>/<command>         (exact name, e.g. "hello.elf")
            2. <cwd>/<command>.elf
            3. 0:/os/<command>.elf
            4. 0:/os/<command>          (no extension)
            5. If on a non-zero drive, the drive root: <drive>:/<command>[.elf]

        A command containing a "/" (or an explicit drive prefix, or a
        leading "." or "/") is instead treated as a direct path and
        resolved by the kernel against the process CWD, trying the
        path as-is and then with ".elf" appended.

        The first match is spawned and the shell waits for it to exit.
        If no match is found, the shell prints:

            <command>: command not found

        Arguments after the command name are passed to the spawned
        process.

    BUILTINS

       help
        Display a categorized list of available commands.

       ls [dir]
        List files in the current directory, or in the specified
        directory. Directory entries are shown with a trailing slash.
        Examples: ls, ls man, ls os

       cd [dir]
        Change the working directory. With no argument, returns to the
        logged-in user's home directory (0:/users/<user>); with /,
        returns to the drive root. Use cd .. to go up one level.
        The shell prompt reflects the current directory.
        Examples: cd os, cd .., cd

       pwd
        Print the current working directory as an absolute path
        (e.g. "0:/os").

       echo [-n] ...
        Print the arguments. -n suppresses the trailing newline.

       set [VAR=value]
        With no argument, list all shell variables (built-in and
        user-defined). With VAR=value, set a variable. With a bare
        name, print that variable's value.

       unset VAR
        Remove a user-defined shell variable.

       true / false
        Return exit status 0 / 1 without doing anything. Useful with
        && and ||.

       N:
        A bare "<number>:" (e.g. "1:") switches the current drive to
        drive N and resets the working directory to that drive's root.

       exit
        Terminate the shell process (with the last command's exit code).

    SYNTAX
       Variables
        NAME=value          Set a shell variable (no leading $)
        $VAR or ${VAR}       Expand a variable's value
        $?                   Exit status of the last command
        $USER, $HOME, $PWD   Built-in dynamic variables (session user,
                            home directory, current directory)
        \$                   Escape a literal '$'

       Tilde expansion
        A leading ~ expands to the session home directory
        (0:/users/<user>) when followed by end-of-string, '/', or a
        space.

       Command chaining
        cmd1 ; cmd2          Run cmd2 unconditionally after cmd1
        cmd1 && cmd2         Run cmd2 only if cmd1 succeeded (exit 0)
        cmd1 || cmd2         Run cmd2 only if cmd1 failed (nonzero exit)

        Single and double quotes protect ;, &&, and || from being
        treated as separators.

       Comments
        A '#' outside of quotes starts a comment; the rest of the line
        is ignored.

    EXTERNAL COMMANDS
        All external commands live in 0:/os/ (see COMMAND RESOLUTION).
        Where a dedicated man page exists it is noted below; run
        'man <command>' for details.

       File commands
        cat <file>          Display file contents
        edit [file]         Text editor -- see edit(1)
        copy <src> <dst>    Copy a file
        move <src> <dst>    Move/rename a file
        rm <file>           Remove a file
        touch <file>        Create an empty file

       System commands
        man <topic>         View manual pages -- see man(1)
        whoami              Print the current username
        info / mtkfetch     Show system information
        date                Show current date and time
        uptime              Show system uptime
        proclist            List running processes
        power               CPU power/thermal status (power [watch [secs]])
        clear               Clear the screen and framebuffer
        fontscale [n]       Get or set terminal font scale -- see fontscale(1)
        lua                 Lua interpreter
        tcc                 TinyCC (in-system C compiler)
        reset               Reboot the system
        shutdown            Shut down the system

       Network commands
        ping <host>         Send ICMP echo requests -- see ping(1)
        nslookup <host>     DNS lookup -- see nslookup(1)
        ifconfig            Show/set network configuration
        tcpconnect <host> <port>  Interactive TCP client
        irc                 IRC client
        dhcp                DHCP client -- see dhcp(1)
        fetch <url>         HTTP/HTTPS client (TLS 1.2) -- see fetch(1)
        wiki <title>        Wikipedia article viewer -- see wiki(1)
        httpd               HTTP server

        Network commands accept both IP addresses and hostnames.
        Hostnames are resolved via the configured DNS server.

       Bluetooth
        btlist              List connected Bluetooth devices
        btbonds              List bonded (paired) Bluetooth devices

       Software-defined radio
        sdr [freqMHz [rateHz]]  Receive and report basic signal
                            statistics from an attached RTL-SDR dongle

        GUI applications (window server programs, not run from the
        shell prompt as text commands) live under 0:/apps/, one bundle
        per app -- e.g. doom, terminal, texteditor, spreadsheet,
        wordprocessor, paint, calculator, network, bluetooth, audio,
        disks, devexplorer, procmgr, powermgr, printers, timezone,
        weather, wikipedia. There is no 0:/games/ directory.

    TAB COMPLETION
        Pressing Tab completes the word under the cursor against, in
        order: executable names in 0:/os/, shell builtins, and file/
        directory entries in the current directory. A single match is
        completed inline; multiple matches are listed below the prompt.

    INPUT
        The shell uses non-blocking keyboard input via SYS_GETKEY (with
        SYS_INPUT_WAIT to sleep between events) to support arrow key
        detection. Lines are limited to 255 characters.

       Editing
        Backspace       Delete character before cursor
        Tab             Tab-complete the current word
        Enter           Execute the command line

       History
        The shell stores the last 32 unique commands. Duplicate
        consecutive entries are suppressed.

        Up Arrow        Recall previous command
        Down Arrow      Recall next command (or clear line)

    PROMPT
        The prompt displays the current drive and working directory:

            0:/> _              (at root of drive 0)
            0:/os> _            (in os/ directory)
            1:/> _              (at root of drive 1)

    SEE ALSO
        man(1), intro(1), syscalls(2)

Back to Documentation Index