Built-in commands

. back to top ↑

Read and execute commands from file (alias for source).

No detailed man page yet — see the one-line summary above.

[ back to top ↑

Evaluate a conditional expression (test, requires a closing ]).

No detailed man page yet — see the one-line summary above.

@ back to top ↑

Arithmetic assignment (csh-style)

No detailed man page yet — see the one-line summary above.

about back to top ↑

show the CSHW About dialog

Synopsis

    about [/min | /minimal | /nerdy | /nerd | /lyrical]

Description

Displays a modal About dialog showing the CSHW version and copyright
information. The dialog appears on the UI thread, falling back to a
self-contained modal pump when CSHW is running in non-interactive mode.

Options

    /lyrical    (default) Short tagline + credits.
    /min        Minimal -- title, version, and copyright only.
    /minimal    Same as /min.
    /nerdy      Verbose -- build date/time, compiler, architecture,
                bundled library versions.
    /nerd       Same as /nerdy.

Examples

    about
        Show the default (lyrical) variant.

    about /nerdy
        Show build details for diagnostic / bug-report purposes.

Exit status

    0       Always (the dialog closes silently).

See also

version, splash, passworddlg

addcontrol back to top ↑

add a child control to a script-owned window

Synopsis

    addcontrol <type> <parent_hwnd> [<text>]
               [/pos:x,y] [/size:w,h] [/id:<n>] [/style:extra]

Description

Creates a standard Win32 child control inside a parent window (typically
one made by `createwindow`). Type-aware defaults handle the class name
and the common style bits; you only specify position, size, id, and
text. The created control is auto-subclassed so `bindevent` against it
Just Works.

Options

    <type>      One of:
                  button     -- BS_PUSHBUTTON | WS_TABSTOP
                  defbutton  -- BS_DEFPUSHBUTTON | WS_TABSTOP
                  checkbox   -- BS_AUTOCHECKBOX | WS_TABSTOP
                  radio      -- BS_AUTORADIOBUTTON | WS_TABSTOP
                  groupbox   -- BS_GROUPBOX
                  label      -- STATIC SS_LEFT
                  edit       -- EDIT ES_AUTOHSCROLL | WS_BORDER | WS_TABSTOP
                  textarea   -- EDIT multi-line, vertical scroll
                  listbox    -- LISTBOX LBS_NOTIFY | WS_VSCROLL
                  combobox   -- COMBOBOX CBS_DROPDOWNLIST | WS_VSCROLL
                  progress   -- msctls_progress32
    <parent_hwnd>
                Parent window HWND (hex or decimal).
    <text>      Initial text / button label.
    /pos:x,y    Position relative to parent client area. Default: 0,0.
    /size:w,h   Control size. Default: 100x24.
    /id:<n>     Control id (the LOWORD of wParam in WM_COMMAND). Default 0.
    /style:extra
                Additional WS_* / BS_* / ES_* etc. bits to OR in.
                WS_CHILD | WS_VISIBLE are always set automatically.

Examples

    createwindow "" "Form" /size:300,200
    set w = $result
    addcontrol label    $w "Name:"  /pos:10,10  /size:60,20
    addcontrol edit     $w ""       /pos:80,10  /size:200,20 /id:1
    addcontrol button   $w "&OK"    /pos:100,150 /size:80,25  /id:100

    proc on_ok
        echo "OK clicked"
    endproc
    bindevent $w command 100 on_ok

Exit status

    0       Success; $result is the new control HWND in hex.
    1       Unknown control type, bad args, or UI thread unavailable.

See also

createwindow, bindevent, unbindevent

alias back to top ↑

create command aliases

Synopsis

    alias
    alias NAME=COMMAND
    alias NAME COMMAND

Description

Creates a shortcut name for a command or displays existing aliases. Aliases
allow you to create shorter or more memorable names for frequently used
commands or command sequences.

When a command is entered, CSHW first checks if it's an alias before looking
for built-in commands or external programs. This allows aliases to override
default behavior.

Options

    NAME            The alias name to create.
    COMMAND         The command the alias expands to.

Examples

    alias
        Display all defined aliases.

    alias ll=dir
        Create 'll' as an alias for 'dir'.

    alias la="dir /a"
        Create 'la' for 'dir /a' (show all including hidden).

    alias cls=clear
        Make 'clear' work like 'cls'.

    alias ..="cd .."
        Create '..' to go up one directory.

    alias ...="cd ..\.."
        Create '...' to go up two directories.

    alias h=history
        Short alias for history command.

    alias g=grep
        Short alias for grep command.

    alias projects="cd C:\Users\Me\Projects"
        Quick navigation alias.

Exit status

    0       Success
    1       Invalid alias name
    2       Syntax error

Notes

Alias Persistence:
Aliases are not persisted across shell sessions. To make aliases permanent,
add them to your shell startup script. On interactive startup, CSHW loads
%USERPROFILE%\.cshrc first; if it is missing, it falls back to
%APPDATA%\cshw\cshwrc.

Alias Expansion:
Aliases are expanded before command execution. An alias can include
switches and arguments.

Recursive Aliases:
Be careful not to create recursive alias loops (alias x=x).

Overriding Commands:
Aliases take precedence over built-in commands. To run the original
command, use its full path or unalias it first.

See also

unalias, set, history

array back to top ↑

create or manipulate an indexed array variable

Synopsis

    array <name>
    array <name> <value1> <value2> ... <valueN>

Description

Creates an indexed array variable. With only a name, creates an empty
array. With trailing values, initializes the array with those elements
at indices 0, 1, 2, ...

Once declared, array elements are read with `$name[<i>]` and written
with `set name[<i>] = <value>`. Appending uses the AppendArrayElement
helper (also reachable via `set name[] = <value>` in some forms).

Options

    <name>      Array name. Same rules as scalar variable names.
    <values>    Optional initial elements.

Examples

    array colors red green blue
    echo "first is $colors[0]"        # red

    array empty
    set empty[0] = "first"
    set empty[1] = "second"
    echo "count = $#empty"            # 2

    # Iteration:
    foreach c ($colors)
        echo $c
    end

Exit status

    0       Array declared / updated.
    1       Bad name or syntax error.

Notes

For string-keyed (associative) arrays, see `hash`. Both styles are
distinct: an indexed array uses integer indices in [], a hash uses
string keys in {}.

See also

hash, set, unset, declare, foreach

attrib back to top ↑

display or change file attributes

Synopsis

    attrib FILE
    attrib [+|-]ATTR FILE

Description

Displays or modifies file attributes. Windows files have several attributes
that control visibility, backup status, and system protection.

Options

    FILE            File(s) to examine or modify.

    Attributes (prefix with + to set, - to clear):
    R               Read-only - prevents modification
    H               Hidden - not shown in normal listings
    S               System - marks as system file
    A               Archive - file needs backup

    /s              Process files in subdirectories.
    /d              Process directories as well as files.

Examples

    attrib file.txt
        Display attributes of file.txt.

    attrib +R important.doc
        Make file read-only.

    attrib -R important.doc
        Remove read-only attribute.

    attrib +H secret.txt
        Hide a file.

    attrib -H -S file.txt
        Remove hidden and system attributes.

    attrib -R /s *.txt
        Remove read-only from all .txt files recursively.

    attrib +A /s *.*
        Mark all files as needing backup.

Exit status

    0       Success
    1       File not found
    2       Access denied

Notes

Attribute Meanings:
    R (Read-only) - Prevents file modification. Must be cleared
                    before editing or deleting the file.
    H (Hidden)    - File won't appear in normal dir listings.
                    Use 'dir /ah' to show hidden files.
    S (System)    - Marks file as system file. Often combined
                    with Hidden for Windows system files.
    A (Archive)   - Indicates file has changed since last backup.
                    Backup software uses this to detect changes.

Combining Attributes:
You can set or clear multiple attributes at once:
    attrib +R +H file.txt

Protected System Files:
Some system files have both +S and +H and may require special
handling to modify.

See also

stat, dir, chmod

awk back to top ↑

pattern-scanning and text-processing language

Synopsis

    awk [OPTIONS]... 'PROGRAM' [FILE]...
    awk [OPTIONS]... -f SCRIPT-FILE [FILE]...
    command | awk [OPTIONS]... 'PROGRAM'

Description

awk reads text from one or more input files (or standard input), splits
each line into fields, and runs a program of pattern-action rules
against every line. It is the classic Unix tool for column-oriented
text processing -- extracting columns, computing sums, reformatting
delimited data, and producing reports.

cshw's awk implements a substantial POSIX awk subset, with PCRE2 as the
regex engine (so lookahead, lookbehind, and Unicode classes all work)
and dual Windows-style and Unix-style switch spellings. Programs run
top-to-bottom over each input record: the BEGIN block fires once before
input, the END block fires once after, and rule patterns select which
records each action applies to.

Options

    -F SEP, --field-separator=SEP, /F:SEP
                Set the input field separator. SEP can be a single
                character, a regex, or the special value " " (default,
                which splits on runs of whitespace AND trims leading/
                trailing whitespace from each record).

    -f FILE, --file=FILE, /f:FILE
                Read the awk program from FILE instead of from the
                command line. Multiple -f options are accepted; their
                contents are concatenated.

    -v VAR=VALUE, --assign VAR=VALUE, /v:VAR=VALUE
                Predefine an awk variable before execution. Repeatable.
                The assignment happens after BEGIN's first variable
                lookup, so -v sets variables visible to BEGIN.

Switch aliases:
    cshw accepts both Unix-style (-x / --xxx) and Windows-style (/x:val)
    spellings everywhere. So `-F,`, `--field-separator=,`, and
    `/F:,` are all equivalent.

.AWK PROGRAM LANGUAGE

An awk program is one or more pattern-action rules of the form:

    PATTERN { ACTION }

Both PATTERN and ACTION are optional. A bare pattern with no action
defaults to `{ print }`. A bare action with no pattern runs on every
record. Rules are separated by newlines or semicolons.

Patterns

    BEGIN           Runs once, before any input is read.
    END             Runs once, after all input is consumed.
    /REGEX/         Matches when the current record matches REGEX.
    EXPR            Matches when EXPR evaluates to a true value (any
                    non-zero number or non-empty string).
    EXPR1, EXPR2    Range pattern: matches from a record where EXPR1
                    is true through the next record where EXPR2 is
                    true (inclusive). Ranges latch.
    !PATTERN        Negation: matches when PATTERN does not.

.FIELDS AND RECORDS
    A record is a line by default. The record is split into fields by FS:
        $0      The whole record.
        $1, $2... Individual fields, 1-indexed.
        $NF     The last field.
        $(NF-1) Second-to-last field, etc.

    Assigning to a field updates $0 (joined with OFS); assigning to NF
    truncates or pads the field list.

.BUILT-IN VARIABLES
    NR          Total record number across all inputs.
    FNR         Record number within the current file (resets on each).
    NF          Field count of the current record.
    FS          Input field separator (default: " ").
    OFS         Output field separator for `print` (default: " ").
    ORS         Output record separator for `print` (default: "\n").
    RS          Input record separator (default: "\n").
    FILENAME    Name of the current input file ("-" for stdin).
    RSTART      Position of last regex match (set by match()).
    RLENGTH     Length of last regex match (-1 if no match).

.BUILT-IN FUNCTIONS
    String:
        length(s)               Length in characters.
        substr(s, start [, n])  Substring (1-indexed).
        index(haystack, needle) 1-indexed position, 0 if not found.
        split(s, arr [, sep])   Split into array, return field count.
        sub(re, repl [, target])  Replace first match in target (default $0).
        gsub(re, repl [, target]) Replace all matches.
        match(s, re)            Set RSTART/RLENGTH; return position.
        tolower(s), toupper(s)
        sprintf(fmt, ...)       printf-style formatting; returns string.

    Numeric:
        int(x)                  Truncate to integer.
        sqrt(x), exp(x), log(x)
        sin(x), cos(x), atan2(y, x)
        rand()                  Pseudo-random in [0, 1).
        srand([seed])           Seed rand; default is wall-clock.

    Time:
        systime()               Seconds since the Unix epoch.

    I/O:
        print [arg, arg, ...]   Output args joined by OFS, terminated by ORS.
        printf fmt, args...     printf-style; no trailing ORS unless in fmt.

Statements

    Control flow: if/else, while, do/while, for(init;cond;step),
    for (key in array), break, continue, next, exit [N], return.

    Arrays: associative; created by first reference. `delete arr[k]`
    removes a single element; `delete arr` clears the whole array.

    Comments: `# ...` runs to end of line.

Examples

    awk '{ print $2 }' file.txt
        Print the second whitespace-separated field of each line.

    awk -F, '{ print $1, $3 }' data.csv
        Print the first and third columns of a CSV file.

    awk '/ERROR/ { print NR, $0 }' log.txt
        Print line number and content for every line containing ERROR.

    awk 'BEGIN { sum = 0 } { sum += $1 } END { print sum }' nums.txt
        Sum the first column.

    awk 'NR == 1 { next } { print }' file.txt
        Skip the header row.

    awk '{ count[$1]++ } END { for (k in count) print k, count[k] }' words.txt
        Frequency table of the first column.

    awk -F: '$3 >= 1000' /etc/passwd
        Lines (entire record) where the third colon-separated field is >= 1000.
        (Bare expression as pattern, no action: defaults to { print }.)

    awk 'length($0) > 80' file.txt
        Print lines longer than 80 characters.

    awk 'BEGIN { OFS = "\t" } { print $2, $1 }' file.txt
        Swap first two fields, output tab-separated.

    awk -v threshold=100 '$1 > threshold' nums.txt
        Filter using a command-line variable.

    type access.log | awk '{ ip[$1]++ } END { for (i in ip) print ip[i], i }' | sort -rn
        Top requesting IPs from a web log.

Exit status

    0       Successful completion.
    1       At least one input file could not be opened.
    2       awk program syntax error.
    N       The exit N statement exited with status N.

Notes

Regex flavor:
    cshw's awk uses PCRE2 (Perl Compatible Regular Expressions).
    Anything you'd expect from `awk` plus features like lookahead /
    lookbehind, named groups, and Unicode classes all work.

Field separator:
    The default FS = " " is special: it splits on runs of any
    whitespace (spaces and tabs) AND trims leading/trailing
    whitespace from the record before splitting. Any other FS value
    is used literally; multi-character FS is treated as a regex.

Numeric vs string comparison:
    awk types are dynamic. A value compares numerically if both
    operands look numeric (a numeric literal, or a string that fully
    parses as a number), otherwise comparison is lexicographic.
    To force string comparison, concatenate with the empty string:
        if (a "" == b "")   # always string compare

Limitations in this version:
    * User-defined functions are parsed but execution support is
      limited; complex recursion and closures may not work.
    * `getline` is parsed but not yet wired to read from arbitrary
      file or command sources at runtime.
    * Output redirection (`> file`, `>> file`, `| command`) is
      parsed but writes go to the standard output regardless.
    * BEGINFILE / ENDFILE / nextfile are not implemented.
    * Locale-sensitive character classes follow PCRE2's defaults,
      not POSIX awk's.

Encoding:
    Input files are read as UTF-8 (with optional BOM stripped) and
    treated as wide-character internally. Programs that treat input
    as bytes (e.g. via length() on a multi-byte sequence) get
    character counts, not byte counts.

See also

sed, grep, cut, sort, uniq, type

base64 back to top ↑

encode or decode base64 data

Synopsis

    base64 [options] FILE
    command | base64 [options]

Description

Encodes binary data to base64 text or decodes base64 text back to binary.
Base64 is commonly used for encoding binary data in text-based formats
like JSON, XML, email attachments, and data URIs.

Options

    FILE            File to encode/decode.

    -d, --decode    Decode base64 input to binary output.
    -w N            Wrap lines at N characters (default: 76, 0 for no wrap).

Examples

    base64 image.png
        Encode image.png to base64.

    base64 -d encoded.txt > decoded.bin
        Decode base64 file to binary.

    echo "Hello World" | base64
        Encode text to base64.

    echo "SGVsbG8gV29ybGQ=" | base64 -d
        Decode base64 text.

    base64 -w 0 file.bin
        Encode without line wrapping.

    type file.bin | base64 > file.b64
        Encode binary file.

Exit status

    0       Success
    1       Invalid base64 data (decode mode)
    2       File not found or read error

Notes

Character Set:
Base64 uses A-Z, a-z, 0-9, +, / and = for padding.
URL-safe base64 uses - and _ instead of + and /.

Size Increase:
Base64 encoding increases data size by approximately 33%.

Binary Safety:
Base64 ensures binary data can be safely transmitted through
text-only channels.

Common Uses:
- Embedding images in HTML/CSS (data URIs)
- Encoding credentials for HTTP Basic Auth
- Encoding binary data in JSON
- Email attachments (MIME)

See also

hexdump, md5sum, sha256sum

basename back to top ↑

strip directory and suffix from a path

Synopsis

    basename <path> [suffix]

Description

Print <path> with any leading directory components removed. Both
forward slashes and backslashes are recognized as path separators, and
trailing separators are ignored.

If a second argument is given it is treated as a suffix: when the
result ends with that suffix, the suffix is removed as well -- but only
when doing so still leaves a non-empty name.

basename does not touch the filesystem; it is a pure text operation on
the path you give it.

Examples

    basename /usr/lib/file.txt
        Prints: file.txt

    basename /usr/lib/file.txt .txt
        Prints: file

    basename C:\Tools\cshw\cshw.exe .exe
        Prints: cshw

    basename /usr/lib/
        Prints: lib  (the trailing slash is ignored)

Exit status

Zero on success. basename with no path argument is a usage error.

See also

dirname, realpath

bg back to top ↑

move job to background

Synopsis

    bg [%JOBID]

Description

Resumes a stopped job and runs it in the background. If no job ID is
specified, operates on the current job.

Options

    %JOBID          Job number (from jobs command).

Examples

    bg
        Resume current job in background.

    bg %1
        Resume job 1 in background.

    # Common workflow:
    longcommand
    # Press Ctrl+Z to stop
    bg
        # Now it runs in background

Exit status

    0       Success
    1       No such job
    2       Job cannot be backgrounded

Notes

Typical Workflow:
1. Start a command
2. Press Ctrl+Z to suspend it
3. Type 'bg' to continue in background
4. Use 'fg' later to bring back to foreground

Output:
Backgrounded processes may still produce output to the terminal.
Consider redirecting output when backgrounding.

See also

fg, jobs, kill, stop

bindevent back to top ↑

bind a script proc as a window event handler

Synopsis

    bindevent <hwnd> <kind> [<args>] <procname>

Description

Records a script-proc handler for a Win32 message on a given window.
Whitelisted messages are routed through CSHW's dispatcher; on the next
matching event, the bound proc runs.

All handlers except `close` fire as coroutines (off the UI thread,
so the UI stays responsive). `close` handlers run synchronously on
the UI thread -- returning a truthy $result vetoes the close.

`$hwnd` is set to the originating window for the handler's duration.

Options

    <hwnd>      Target HWND in hex or decimal. Must satisfy IsWindow().
    <kind>      One of:
                  command <ctlId>      WM_COMMAND from <ctlId>
                                       $1=ctlId  $2=notifyCode
                  notify  <ctlId>      WM_NOTIFY  from <ctlId>
                                       $1=ctlId  $2=notifyCode
                  timer   <timerId>    WM_TIMER
                                       $1=timerId
                  close                WM_CLOSE  (SYNCHRONOUS, $result vetoes)
                  destroy              WM_DESTROY
                  lbuttondown          WM_LBUTTONDOWN  $1=x $2=y
                  lbuttonup            WM_LBUTTONUP    $1=x $2=y
                  keydown <vk>         WM_KEYDOWN      $1=vk
                  size                 WM_SIZE         $1=width $2=height
    <procname>  Proc to invoke. Must already be defined via `proc`.

Examples

    proc on_ok
        echo "OK clicked"
    endproc
    bindevent $w command 100 on_ok

    proc veto_close
        share user_clicked_x = 1
        return 1            # veto -- window stays open
    endproc
    bindevent $w close veto_close

    proc on_size
        echo "resized to ${1}x${2}"
    endproc
    bindevent $w size on_size

Exit status

    0       Binding installed.
    1       Bad HWND, unknown kind, missing args, or undefined proc.

Notes

WM_CLOSE handlers run synchronously on the UI thread. Slow handlers
stall the UI; do not call dialog APIs (passworddlg, messagebox, etc.)
from a close handler -- it deadlocks.

For windows NOT created by `createwindow` (e.g., one returned by a
future `findwindow`, or a plugin-class window), CSHW installs a
SetWindowSubclass shim on first bind so the binding actually receives
messages.

See also

unbindevent, createwindow, addcontrol, sendmessage, postmessage

bugreport back to top ↑

compose and send a bug report to bugs@tropibyte.com

Synopsis

    bugreport
    bugreport "subject"
    bugreport "subject" "details"

Description

Open a bug-report email composed in your default mail client, addressed
to bugs@tropibyte.com. With no arguments, presents a modal dialog to
collect a subject line and free-text details. With one or two string
arguments, skips the dialog and goes straight to the mail client.

Nothing is sent until you click Send. cshw only opens the composer --
you remain in control of the final message.

By default, three diagnostic lines are appended to the body:
    - cshw version (from the binary's VS_VERSION_INFO resource)
    - Windows version + build number
    - Last shell error code, if any

The dialog has a checkbox to suppress those. The two- and three-argument
forms always include them.

Arguments

    "subject"
        Short summary of the bug. Used as the email Subject line, with
        "cshw bug: " prepended.
    "details"
        Free-text body. Multi-line OK. Pre-formatted; mail clients
        respect the line breaks.

Examples

    bugreport
        Open the modal dialog.

    bugreport "foreach hangs on empty list"
        Compose with just a subject. Body will contain only the
        diagnostics tail.

    bugreport "sed -i fails" "sed -i s/a/b/ file.txt returns error 5"
        Subject + body, no dialog.

Exit status

    0       Mail client opened successfully.
    1       Dialog cancelled, or ShellExecute failed.

Notes

The mail client is selected by the system's default mailto: handler --
typically Outlook, Thunderbird, the Windows Mail app, or a webmail
handler that registered itself. If no handler is registered, the
command fails with a hint pointing at bugs@tropibyte.com directly.

The web equivalent (no cshw installed) is https://tropibyte.com/bugs.html
which presents the same fill-in-the-blanks mailto: template.

See also

version, ver, about

cat back to top ↑

concatenate file(s) (or stdin) to standard output

Synopsis

    cat [options] [file...]
    cat [options] - [file...]
    command | cat [options]

Description

Concatenates one or more files (or standard input) to standard output. With
no file argument, or when file is '-', cat reads from standard input.

cshw's cat folds together the GNU coreutils, BSD, AIX, and Solaris feature
sets so users moving between shells keep their muscle memory. Long-form
(--number), short-form (-n), and cshw-style (/n) switches are all accepted.

cat is encoding-aware on input: UTF-16 LE/BE and UTF-8 BOMs are detected
and decoded automatically; otherwise input is read as the active code page.

Options

    -n  --number               Number all output lines, right-justified in 6
                               columns followed by a TAB.
    -b  --number-nonblank      Number non-empty lines only. Overrides -n.
    -s  --squeeze-blank        Collapse runs of consecutive blank lines into
                               a single blank line.
    -E  --show-ends            Print '$' at the end of each line.
    -T  --show-tabs            Print TAB characters as '^I'.
    -v  --show-nonprinting     Print control characters and high-bit bytes
                               using ^X / M-X notation. LF and TAB are not
                               affected unless -E or -T is also given.
    -A  --show-all             Equivalent to -vET.
    -e                         Equivalent to -vE.
    -t                         Equivalent to -vT.
    -q  --quiet                Silent on missing files (AIX behavior).
    -u                         Accepted for POSIX compatibility (no-op:
                               cshw's stdout is line-buffered already).
    -                          Read standard input at this position.
    --                         End of options; remaining tokens are files.

Examples

    cat file.txt
        Print the file to stdout.

    cat file1.txt file2.txt > combined.txt
        Concatenate two files into a third via redirection.

    cat -n script.cshw
        Number every line.

    cat -b notes.md
        Number only non-blank lines.

    cat -s log.txt
        Squeeze consecutive blank lines so the output is denser.

    cat -A weird.txt
        Reveal all non-printing structure: tabs as ^I, line ends as $,
        control bytes as ^X / M-X.

    ls | cat -n
        Number a piped stream.

    cat - file.txt
        Read from stdin first, then file.txt.

    cat -q maybe_missing.txt always_present.txt
        Don't error if maybe_missing.txt isn't there (AIX-style).

Exit status

    0       Success
    >0      One or more files could not be read (unless -q was given)

Notes

Encoding:
Input files with a UTF-16 LE BOM, UTF-16 BE BOM, or UTF-8 BOM are decoded
into wide characters. Files without a BOM are interpreted as the active
code page (CP_ACP). The output stream is wide-aware so redirection and
piping preserve characters.

Stream order:
Files are emitted in the order given on the command line. With -n or -b,
line numbers continue across file boundaries (one logical concatenated
stream), matching standard cat behavior.

-s with non-empty lines:
-s only collapses fully empty lines (or CR-only lines). It does not strip
whitespace from non-empty lines.

Difference from type:
'type' is cshw's DOS-style file-display command and takes no options.
'cat' is the Unix-style equivalent with the full option surface above.

See also

type, head, tail, grep, wc, awk

cd back to top ↑

change the current working directory

Synopsis

    cd [directory]
    cd [options]
    chdir [directory]

Description

Aliases: chdir

Changes the shell's current working directory. If no directory is specified,
displays the current directory path. The cd command supports both absolute
and relative paths, as well as several special keywords.

When changing to a new directory, CSHW maintains a per-drive directory cache,
allowing you to return to the last directory on each drive by specifying just
the drive letter.

The cd command also integrates with the shell's alias system, so you can
create shortcuts to frequently accessed directories.

Options

    directory       The path to change to. Can be absolute or relative.

    Special values:
    -               Change to the previous directory (like UNIX cd -)
    ~               Change to the user's home directory (%USERPROFILE%)
    ..              Change to the parent directory
    ...             Change to the grandparent directory (two levels up)
    ....            Change to three levels up (and so on)
    system          Change to %SystemRoot% (usually C:\Windows)
    windows         Change to %SystemRoot% (usually C:\Windows)

    Drive letters:
    D:              Change to drive D: and restore the last directory on that drive

Examples

    cd
        Display the current working directory.

    cd C:\Users\Public
        Change to an absolute path.

    cd ..
        Change to the parent directory.

    cd ...
        Change up two directory levels.

    cd ~
        Change to your home directory (%USERPROFILE%).

    cd -
        Return to the previous working directory.

    cd system
        Change to the Windows system directory (C:\Windows).

    cd D:
        Switch to drive D: and restore the last working directory on that drive.

    cd "Program Files"
        Change to a directory with spaces in the name (quoted).

Exit status

    0       Success - directory was changed
    1       Directory not found
    2       Invalid argument or syntax error

Environment

    USERPROFILE     Used when cd ~ is invoked
    SystemRoot      Used when cd system or cd windows is invoked

Notes

CSHW maintains a separate current directory for each drive letter. When you
switch drives using just the drive letter (e.g., cd D:), the shell restores
your previous position on that drive.

The command 'chdir' is an alias for 'cd' and works identically.

Unlike cmd.exe, CSHW's cd command supports the UNIX-style cd - to return to
the previous directory.

See also

pushd, popd, pwd, dirs

chdir back to top ↑

change the current working directory (alias for cd)

Synopsis

    chdir [directory]

Description

`chdir` is identical to `cd`. See `man cd` for full documentation,
options, and examples.

See also

cd, pwd, pushd, popd

chmod back to top ↑

change file permissions

Synopsis

    chmod MODE FILE
    chmod [options] MODE FILE...

Description

Changes file permissions. On Windows, this primarily maps to file
attributes (read-only) and NTFS ACLs. Provides UNIX-style syntax for
familiarity, mapped to Windows concepts.

Options

    MODE            Permission mode (numeric or symbolic).
    FILE            File(s) to modify.

    Numeric mode (octal):
    400             Owner read
    200             Owner write
    100             Owner execute
    040             Group read
    020             Group write
    010             Group execute
    004             Others read
    002             Others write
    001             Others execute

    Symbolic mode:
    u               User (owner)
    g               Group
    o               Others
    a               All (ugo)
    +               Add permission
    -               Remove permission
    =               Set exact permission
    r               Read
    w               Write
    x               Execute

    Options:
    -R, --recursive Apply recursively.
    -v, --verbose   Verbose output.

Examples

    chmod 644 file.txt
        Owner read/write, others read-only.

    chmod 755 script.exe
        Owner full, others read/execute.

    chmod +x script.bat
        Add execute permission.

    chmod -w readonly.txt
        Remove write permission (make read-only).

    chmod u+w,go-w file.txt
        Owner writable, others not.

    chmod -R 755 directory/
        Recursively set permissions.

Exit status

    0       Success
    1       File not found
    2       Access denied
    3       Invalid mode

Notes

Windows Mapping:
UNIX permissions don't map directly to Windows. chmod primarily:
- Sets/clears read-only attribute (write permission)
- Modifies NTFS ACLs where possible

Read-Only:
The most common use is toggling read-only:
    chmod -w file.txt   # Make read-only
    chmod +w file.txt   # Make writable

Execute Permission:
On Windows, execute permission is determined by file extension,
not a permission bit. chmod +x has limited effect.

NTFS ACLs:
For full Windows permission control, use icacls or the attrib
command for attributes.

Scripts:
chmod is useful for cross-platform scripts that expect UNIX
permission syntax.

See also

chown, attrib, stat

chown back to top ↑

change file owner

Synopsis

    chown OWNER FILE
    chown OWNER:GROUP FILE
    chown [options] OWNER FILE...

Description

Changes the owner of files and directories. On Windows, this modifies
the file's security descriptor to set a new owner.

Options

    OWNER           New owner (username or SID).
    GROUP           New group (optional, after colon).
    FILE            File(s) to modify.

    -R, --recursive Apply changes recursively to directories.
    -v, --verbose   Show files as they're processed.

Examples

    chown Administrator file.txt
        Change owner to Administrator.

    chown DOMAIN\User document.docx
        Change owner to domain user.

    chown -R Administrator C:\Data
        Recursively change owner of directory tree.

    chown "NT AUTHORITY\SYSTEM" service.exe
        Change owner to SYSTEM account.

Exit status

    0       Success
    1       File not found
    2       Access denied (need Administrator)
    3       Invalid owner

Notes

Administrator Required:
Changing file ownership typically requires Administrator privileges
or SeRestorePrivilege/SeTakeOwnershipPrivilege.

Taking Ownership:
Administrators can take ownership of any file even if current
permissions deny access.

Windows vs UNIX:
- UNIX chown: Changes owner and optionally group
- Windows: Owner is part of security descriptor, groups work differently

Security Descriptors:
File ownership is part of Windows NTFS security. The owner has
special privileges including the ability to modify permissions.

SIDs:
You can specify owners by Security Identifier (SID) instead of name:
    chown S-1-5-18 file.txt   # SYSTEM

See also

chmod, attrib, stat

clip back to top ↑

copy to clipboard

Synopsis

    clip < FILE
    command | clip
    clip [options]

Description

Copies text from standard input to the Windows clipboard. The copied
content can then be pasted into any application.

Options

    Standard input is copied to clipboard.

    /p              Paste clipboard contents to stdout (read clipboard).

Examples

    dir | clip
        Copy directory listing to clipboard.

    type file.txt | clip
        Copy file contents to clipboard.

    echo "Hello" | clip
        Copy text to clipboard.

    clip /p
        Display current clipboard contents.

    clip /p > saved.txt
        Save clipboard to file.

    grep error log.txt | clip
        Copy matching lines to clipboard.

Exit status

    0       Success
    1       Clipboard access error

Notes

Text Only:
clip works with text data. Binary data will be treated as text
and may not produce expected results.

Unicode:
Unicode text is supported and preserved.

Integration:
clip is useful for copying command output to paste elsewhere:
- Copy file paths for email
- Copy command output for documentation
- Copy error messages for searching

See also

type, echo

cls back to top ↑

clear the console screen

Synopsis

    cls [/scroll]

Description

Clears the console screen and moves the cursor to the home position
(top-left corner).

By default, cls erases the entire console buffer including all
scrollback history. The screen is completely cleared.

Options

    /scroll, /s, -scroll, -s
        Preserve scrollback buffer. Instead of erasing the buffer,
        content is scrolled up and filled with blank lines. You can
        still scroll back to see previous output.

Examples

    cls
        Clear the screen and erase all scrollback history.

    cls /scroll
        Clear the visible screen but preserve scrollback buffer.

    cls /s
        Same as cls /scroll.

Exit status

    0       Success

Notes

Alternative Names:
    Some systems use 'clear' instead of 'cls'. CSHW supports both.

Windows 10+ Required:
    The default erase behavior uses VT100 escape sequences which
    require Windows 10 or later. On older systems, the behavior
    may fall back to scroll mode.

See also

echo, clear

cmdliblist back to top ↑

list loaded command libraries

Synopsis

    cmdliblist
    cmdliblist /verbose

Description

Displays information about all currently loaded command libraries.
Shows library name, version, prefix, path, and command count.

With the /verbose option, also lists all commands provided by
each library and indicates which ones shadow intrinsic commands.

Options

    /verbose    Show detailed command list for each library.
    /v          Short form of /verbose.

Examples

    cmdliblist
        List all loaded libraries with basic info.

    cmdliblist /v
        List libraries with all their commands.

Output

For each library, displays:
    - Library name (or path if no name)
    - Version (if specified by plugin)
    - Prefix and whether it's required
    - Full DLL path
    - Number of commands registered

With /verbose, also shows:
    - Each command name
    - Command description
    - Whether it shadows an intrinsic command

Exit status

    0       Always succeeds

See also

rcl, urcl

complete back to top ↑

define tab completion rules

Synopsis

    complete COMMAND PATTERN
    complete COMMAND TYPE

Description

Defines custom tab completion rules for commands. When you press Tab after
a command, the shell uses these rules to suggest completions.

Options

    COMMAND         Command to define completion for.
    PATTERN         Glob pattern for completions.
    TYPE            Completion type:
                    f   Files (default)
                    d   Directories only
                    c   Commands
                    e   Environment variables
                    a   Aliases
                    v   Variables

Examples

    complete cd d
        Complete cd with directories only.

    complete type f
        Complete type with files.

    complete kill p
        Complete kill with process IDs.

    complete set v
        Complete set with variable names.

    complete source "*.csh"
        Complete source with .csh files.

    complete git "(add|commit|push|pull|status)"
        Complete git with subcommands.

Exit status

    0       Success
    1       Invalid pattern

Notes

Tab Completion:
When you type a command and press Tab, the shell:
1. Checks for 'complete' rules for that command
2. Uses the rule to filter/suggest completions for the current token
3. Inserts the next match inline when there is a single match (or a shared prefix)
4. Displays a list of matches when multiple results exist
5. Falls back to default (file) completion if no rule

Interactive Behavior:
- Tab completes the current word at the cursor (end-of-line)
- If multiple matches exist, the shell prints them and redraws the prompt
- Completion types support files, directories, commands, aliases, variables, and environment variables

Default Behavior:
Without custom rules, Tab completes filenames.

Multiple Arguments:
Completion rules can vary by argument position:
    complete command (dir file file)

Listing Rules:
Use 'complete' without arguments to list all defined completions.

See also

uncomplete, alias

copy back to top ↑

copy files

Synopsis

    copy SOURCE DESTINATION
    copy SOURCE... DIRECTORY

Description

Aliases: cp

Copies one or more files to a destination. If the destination is a directory,
files are copied into that directory preserving their original names. If
copying a single file to a non-directory destination, the file is copied
with the new name.

The copy command uses the Windows CopyFile API, which preserves file
attributes and handles large files efficiently.

Options

    SOURCE          The file(s) to copy. Wildcards (* and ?) are supported.

    DESTINATION     The target file or directory.

    /y              Suppress confirmation prompt when overwriting.

    /v              Verify that new files are written correctly.

Examples

    copy file.txt backup.txt
        Copy file.txt to backup.txt in the same directory.

    copy document.docx D:\Backup\
        Copy document.docx to the D:\Backup directory.

    copy *.txt TextFiles\
        Copy all .txt files to the TextFiles subdirectory.

    copy "My File.doc" "My Backup.doc"
        Copy a file with spaces in the name.

    copy src\*.cpp backup\src\
        Copy all C++ source files to a backup location.

Exit status

    0       Success - all files copied
    1       Source file not found
    2       Destination access denied or disk full
    3       Syntax error

Notes

Overwriting:
If the destination file already exists, copy will overwrite it without
prompting (use /y to explicitly suppress any prompts).

Large Files:
The copy command handles files of any size, including files larger than 4GB.

Network Paths:
UNC paths (\\server\share\file) are fully supported.

Preserving Attributes:
File attributes (read-only, hidden, system, archive) are preserved during
the copy operation.

See also

mv, del, rm, type

cp back to top ↑

copy files (alias for copy)

Synopsis

    cp [-r | -R | --recursive] <source> <dest>

Description

`cp` is identical to `copy`. See `man copy` for full documentation,
options, and examples.

See also

copy, mv, rm

createwindow back to top ↑

create a script-owned window on the UI thread

Synopsis

    createwindow [<class>] [<title>] [/style:a,b,...] [/exstyle:a,b,...]
                 [/pos:x,y] [/size:w,h] [/parent:<hwnd>] [/id:<n>]

Description

Creates a Win32 window on the CSHW UI thread and returns its HWND in
$result (hex), plus a monotonic per-window cookie in $result_cookie
that scripts can use to guard against the HWND-reuse window.

The window's whitelisted messages (WM_COMMAND, WM_NOTIFY, WM_TIMER,
WM_LBUTTONDOWN/UP, WM_KEYDOWN, WM_SIZE, WM_CLOSE, WM_DESTROY) are
routed back to bound script procs via `bindevent`.

Options

    <class>     Window class. Default: CSHWScriptWindowClass (the built-in
                generic script window). Plugin-registered classes are
                also accepted by name.
    <title>     Window text. Default: empty.
    /style:..   Comma-separated WS_* flags. Accepts symbolic names
                (overlapped, visible, sysmenu, thickframe, tabstop,
                child, popup, ...) and hex/decimal literals.
                Default: WS_OVERLAPPEDWINDOW|WS_VISIBLE for top-levels,
                WS_CHILD|WS_VISIBLE when /parent is given.
    /exstyle:.. WS_EX_* flags (topmost, toolwindow, clientedge, ...).
                Same comma-list syntax.
    /pos:x,y    Top-left position. Default: CW_USEDEFAULT.
    /size:w,h   Window size. Default: CW_USEDEFAULT.
    /parent:<hwnd>
                Parent HWND for child windows.
    /id:<n>     HMENU / child-id slot.

Examples

    createwindow "" "My window" /size:400,300
    set w = $result
    # Add a child button:
    addcontrol button $w "&OK" /pos:10,10 /size:80,25 /id:100
    # React to its click:
    proc on_ok
        echo "ok clicked, ctlId=$1 code=$2"
    endproc
    bindevent $w command 100 on_ok

Exit status

    0       Success; $result is the HWND in hex, $result_cookie the cookie.
    1       UI thread unavailable, unknown class, or bad style/pos/size.

Notes

The built-in CSHWScriptWindowClass has its dispatcher wired directly
into its WndProc. For any OTHER class (plugin class, system control,
foreign HWND), CSHW installs a SetWindowSubclass shim on top so the
window is bindable-by-default.

See also

addcontrol, bindevent, unbindevent, sendmessage, postmessage

crond back to top ↑

cron daemon control

Synopsis

    crond start
    crond stop
    crond status
    crond restart

Description

Controls the cron daemon that executes scheduled jobs defined in crontab.
The daemon runs in the background, checking every minute for jobs to run.

Options

    start           Start the cron daemon.
    stop            Stop the cron daemon.
    status          Show daemon status.
    restart         Stop then start the daemon.

Examples

    crond start
        Start the cron daemon.

    crond status
        Check if daemon is running.

    crond stop
        Stop the daemon.

    crond restart
        Restart after crontab changes.

Exit status

    0       Success
    1       Daemon already running/stopped
    2       Error starting/stopping

Notes

Background Process:
crond runs as a background thread within CSHW. It continues running
as long as the shell is open.

Auto-Start:
To have crond start automatically, add 'crond start' to your
shell startup script.

Job Execution:
Jobs run in separate processes. Their output goes to a log file
or is discarded depending on configuration.

Missed Jobs:
If crond is not running when a job is scheduled, that execution
is missed. crond does not run missed jobs.

Windows Task Scheduler:
For persistent scheduled tasks that survive logoff/reboot, consider
using Windows Task Scheduler instead:
    schtasks /create ...

See also

crontab, jobs, service

crontab back to top ↑

manage scheduled cron jobs

Synopsis

    crontab -l
    crontab -e
    crontab -r
    crontab FILE

Description

Manages the cron job schedule for the current user. Cron jobs are commands
that run automatically at specified times. CSHW provides a UNIX-compatible
cron implementation on Windows.

Options

    -l, --list      List current cron jobs.
    -e, --edit      Edit crontab (opens in editor).
    -r, --remove    Remove all cron jobs.
    FILE            Install cron jobs from FILE.

Examples

    crontab -l
        List all scheduled jobs.

    crontab -e
        Edit cron schedule in text editor.

    crontab jobs.txt
        Install jobs from file.

    crontab -r
        Remove all scheduled jobs.

Crontab file format (5 time fields + command):
    # minute hour day month weekday command
    0 * * * * echo "Runs every hour"
    30 9 * * 1-5 backup.bat
    0 0 1 * * monthly_report.exe
    */15 * * * * check_status.bat

Exit status

    0       Success
    1       Error reading/writing crontab
    2       Syntax error in crontab

Notes

Time Field Format:
    Field       Values      Special
    ─────       ──────      ───────
    Minute      0-59        * (any), */n (every n)
    Hour        0-23        , (list), - (range)
    Day         1-31
    Month       1-12
    Weekday     0-6 (0=Sun)

Special Characters:
    *       Any value
    */n     Every n units (*/15 = every 15)
    ,       List (1,3,5)
    -       Range (1-5)

Examples:
    0 * * * *       Every hour at :00
    */15 * * * *    Every 15 minutes
    0 9 * * 1-5     9 AM on weekdays
    0 0 1 * *       Midnight on 1st of month
    30 4 * * 0      4:30 AM on Sundays

Cron Daemon:
Jobs only run if crond is running. Start with 'crond start'.

Storage:
Crontab is stored in %APPDATA%\cshw\crontab.

See also

crond, time, sleep

cut back to top ↑

remove sections from each line

Synopsis

    cut -d DELIM -f FIELDS [FILE]
    cut -c CHARS [FILE]
    command | cut [options]

Description

Extracts selected portions of each line from files or standard input.
Useful for processing delimited data like CSV files or extracting
specific columns from command output.

Options

    FILE            File to process (default: stdin).

    -d DELIM        Use DELIM as field delimiter (default: tab).
    -f FIELDS       Select fields (columns). Examples:
                    -f 1        First field
                    -f 1,3      Fields 1 and 3
                    -f 1-3      Fields 1 through 3
                    -f 2-       Field 2 to end

    -c CHARS        Select characters by position.
                    -c 1-10     Characters 1-10
                    -c 5        Character 5 only

    -s              Suppress lines without delimiters.

Examples

    cut -d, -f1 data.csv
        Extract first column from CSV file.

    cut -d, -f1,3,5 data.csv
        Extract columns 1, 3, and 5.

    cut -d: -f1 /etc/passwd
        Extract usernames (UNIX password file format).

    echo "hello world" | cut -c1-5
        Extract "hello".

    processlist | cut -c1-40
        Truncate process list output.

    dir /b | cut -d. -f1
        Extract filenames without extensions.

Exit status

    0       Success
    1       Error

Notes

Delimiters:
Common delimiters:
- Comma: -d,
- Tab: -d$'\t' (or default)
- Colon: -d:
- Space: -d' '

Field vs Character:
- Use -f for delimited data (CSV, TSV)
- Use -c for fixed-width data

One Delimiter Only:
cut uses a single character as delimiter. For multi-character
delimiters or complex parsing, consider using grep or scripting.

See also

grep, sort, wc, tr

date back to top ↑

display or format the current date and time

Synopsis

    date [options]
    date +FORMAT

Description

Displays the current date and time. By default, shows the local date and
time in a readable format. Various options control the output format.

Options

    -u, --utc       Display time in UTC (Coordinated Universal Time)
    -I, --iso       Display in ISO 8601 format (YYYY-MM-DDTHH:MM:SS)
    -R, --rfc       Display in RFC 2822 format (for email headers)
    +FORMAT         Custom format string (see FORMAT SPECIFIERS)

Format Specifiers

    %Y    Four-digit year (e.g., 2024)
    %m    Month as two digits (01-12)
    %d    Day of month as two digits (01-31)
    %H    Hour in 24-hour format (00-23)
    %M    Minute (00-59)
    %S    Second (00-59)
    %j    Day of year (001-366)
    %w    Day of week (0-6, Sunday=0)
    %W    Week number of year (00-53)
    %a    Abbreviated weekday name (Sun, Mon, ...)
    %A    Full weekday name (Sunday, Monday, ...)
    %b    Abbreviated month name (Jan, Feb, ...)
    %B    Full month name (January, February, ...)
    %p    AM or PM
    %Z    Timezone name
    %%    Literal percent sign

Examples

    date
        Wed Jan 08 14:30:45 2025

    date -u
        Wed Jan 08 19:30:45 2025 UTC

    date -I
        2025-01-08T14:30:45

    date -R
        Wed, 08 Jan 2025 14:30:45 -0500

    date +%Y-%m-%d
        2025-01-08

    date "+%H:%M:%S"
        14:30:45

    date "+Today is %A, %B %d"
        Today is Wednesday, January 08

Notes

Unlike Unix date, this command cannot set the system date/time.
Use Windows 'control timedate.cpl' to change the system time.

See also

time, uptime

declare back to top ↑

declare a variable with optional type / scope flags

Synopsis

    declare [-r] [-l] [-a] [-A] <name> [= <value>]

Description

Declares one variable, optionally marking it read-only (-r), local to
the current proc (-l), an indexed array (-a), or an associative array
(-A). Without flags, behaves like `set`.

The flags can be combined (e.g., `declare -lr CONST = 42` declares a
local read-only constant inside a proc).

Options

    -r          Mark the variable read-only (same as `readonly`).
    -l          Declare in the local proc scope (same as `local`).
    -a          Declare as an indexed array.
    -A          Declare as an associative array (hash).
    <name>      Variable name.
    <value>     Optional initial value.

Examples

    declare -r MAX = 100
        # Read-only global.

    declare -lr loop_count = 0
        # Read-only local (only meaningful inside a proc).

    declare -a colors
    set colors[0] = "red"
    set colors[1] = "green"

    declare -A users
    set users{alice} = "admin"
    set users{bob}   = "user"

Exit status

    0       Declaration succeeded.
    1       Bad flag combination, syntax error, or read-only violation.

Notes

`declare` is the unified form for the related single-purpose commands:
  declare -r ...   <=>  readonly ...
  declare -l ...   <=>  local ...
  declare -a ...   <=>  array <name>
  declare -A ...   <=>  hash <name>

The single-purpose commands remain available; pick whichever reads
more naturally in your script.

See also

set, local, readonly, array, hash, share

del back to top ↑

delete files

Synopsis

    del <file> [<file> ...]
    del /secure  <file> [<file> ...]
    del /recycle <file> [<file> ...]

Description

Deletes one or more files. 'del' and 'rm' are aliases for the same
handler; see rm(1) for the full description.

By default del permanently deletes the named files. Use /recycle to send
them to the Recycle Bin (recoverable), or /secure to overwrite the file
contents with zeros before deletion.

cshw accepts both Windows-style and Unix-style switch spellings. See
rm(1) and rmdir(1) for the full set.

Options

    <file>          File(s) to delete.

    /secure, --secure
                    Overwrite the file contents with zeros before
                    deletion. Mutually exclusive with /recycle.

    /recycle, --recycle
                    Send to the Recycle Bin. Fails (rather than silently
                    permanent-deleting) when the bin is unavailable; see
                    NOTES on rmdir(1).

Examples

    del temp.txt
        Permanently delete temp.txt.

    del /recycle scratch.bin
        Send scratch.bin to the Recycle Bin.

    del /secure passwords.txt
        Zero out and then delete.

See also

rm, rmdir

df back to top ↑

display disk free space

Synopsis

    df
    df [DRIVE]
    df [options]

Description

Reports file system disk space usage. Shows total, used, and available
space on mounted drives.

Options

    DRIVE           Show info for specific drive (e.g., C:).

    -h, --human-readable
                    Print sizes in human readable format (KB, MB, GB).
    -a, --all       Include all drives (including network/removable).

Examples

    df
        Show disk usage for all local drives.

    df C:
        Show disk usage for C: drive only.

    df -h
        Human-readable format (1K, 234M, 2G).

    df -a
        Include network and removable drives.

Exit status

    0       Success
    1       Error (invalid drive)

Notes

Output Columns:
- Filesystem: Drive letter or mount point
- Size: Total capacity
- Used: Space in use
- Avail: Space available
- Use%: Percentage used
- Mounted on: Drive description

Windows Drives:
Shows all available drive letters including:
- Fixed drives (HDD, SSD)
- Removable drives (USB)
- Network drives (if -a specified)
- Optical drives

See also

du, dir, stat

diff back to top ↑

compare files line by line

Synopsis

    diff FILE1 FILE2
    diff [options] FILE1 FILE2

Description

Compares two files line by line and displays the differences. Output shows
which lines need to be added, removed, or changed to transform FILE1 into
FILE2.

Options

    FILE1           First file to compare.
    FILE2           Second file to compare.

    -u, --unified   Output in unified diff format (shows context).
    -c, --context   Output in context diff format.
    -i, --ignore-case
                    Ignore case differences.
    -w, --ignore-whitespace
                    Ignore all whitespace.
    -b              Ignore changes in amount of whitespace.
    -B              Ignore blank lines.
    -q, --brief     Report only whether files differ.

Examples

    diff old.txt new.txt
        Compare two files and show differences.

    diff -u original.cpp modified.cpp
        Unified diff format (commonly used for patches).

    diff -i file1.txt file2.txt
        Case-insensitive comparison.

    diff -q dir1/file dir2/file
        Quick check if files differ.

    diff -w config.old config.new
        Ignore whitespace differences.

Exit status

    0       Files are identical
    1       Files differ
    2       Error (file not found, etc.)

Notes

Output Format:
Default output uses traditional diff format:
- Lines with < are from FILE1
- Lines with > are from FILE2
- Numbers indicate line positions

Unified Format (-u):
- Lines with - are removed
- Lines with + are added
- Context lines are shown with space prefix

Use Cases:
- Comparing code versions
- Checking configuration changes
- Creating patches

Binary Files:
diff is designed for text files. Binary files will be reported as
different but content won't be meaningfully shown.

See also

type, wc, grep

dir back to top ↑

display directory contents

Synopsis

    dir [path] [options]
    dir [path] [/switches]

Description

Displays a list of files and subdirectories in a directory. Similar to the
Windows DIR command but with additional formatting options and UNIX-style
switch support.

By default, dir displays filenames, sizes, dates, and attributes. The output
can be customized using various switches to show different information, sort
results, filter by attributes, and control formatting.

Options

    path            Directory or file pattern to list (default: current directory)
                    Supports wildcards: * (any characters) and ? (single character)

    Attribute filters:
    /a              Show all files including hidden and system
    /ah             Show only hidden files
    /as             Show only system files
    /ar             Show only read-only files
    /aa             Show only files with archive attribute
    /ad             Show only directories
    /a-h            Exclude hidden files
    /a-s            Exclude system files
    /a-d            Exclude directories (files only)

    Sorting options:
    /o              Sort by name (ascending)
    /o-             Sort by name (descending)
    /on             Sort by name
    /os             Sort by size (smallest first)
    /o-s            Sort by size (largest first)
    /oe             Sort by extension
    /od             Sort by date/time (oldest first)
    /o-d            Sort by date/time (newest first)
    /og             Group directories first

    Display options:
    /b              Bare format (names only, no header/footer)
    /w              Wide format (multiple columns)
    /p              Pause after each screenful
    /l              Use lowercase for filenames
    /n              Use long list format with new format
    /q              Show file owner
    /r              Include alternate data streams
    /s              Recurse into subdirectories
    /x              Show short (8.3) filenames

    Time display:
    /tc             Show creation time
    /ta             Show last access time
    /tw             Show last write time (default)

    Format options:
    /4              Use 4-digit years in dates
    /24             Use 24-hour time format
    /-c             Disable thousand separators in sizes
    /attr           Show file attributes column

Examples

    dir
        List contents of current directory.

    dir C:\Users
        List contents of C:\Users directory.

    dir *.txt
        List all text files in current directory.

    dir /s *.exe
        Recursively find all .exe files.

    dir /ah
        Show only hidden files.

    dir /ad
        Show only directories.

    dir /o-s
        Sort by size, largest first.

    dir /o-d /s
        Recursively list, newest files first.

    dir /b > filelist.txt
        Export bare file listing to a file.

    dir /b /s *.cpp
        Recursively list all .cpp files (paths only).

    dir /q
        Show file owners.

    dir /attr
        Show detailed file attributes.

    dir /w
        Wide format listing (multiple columns).

Exit status

    0       Success
    1       Directory not found or access denied
    2       Invalid argument

Notes

The dir command automatically formats file sizes with thousand separators
for readability (e.g., 1,234,567 bytes). Use /-c to disable this.

For very large directories, consider using /p to pause between screens,
or redirect output to a file or grep command.

File sizes are shown in bytes by default. Very large files (>1TB) may
show approximate sizes.

See also

cd, find, grep, ls, stat

dirname back to top ↑

strip the last component from a path

Synopsis

    dirname <path>

Description

Print <path> with its last component removed, leaving the directory
portion. Both forward slashes and backslashes are recognized as path
separators, and trailing separators are ignored.

When <path> contains no directory component, dirname prints "." --
the current directory.

dirname does not touch the filesystem; it is a pure text operation on
the path you give it.

Examples

    dirname /usr/lib/file.txt
        Prints: /usr/lib

    dirname file.txt
        Prints: .

    dirname /usr/lib/
        Prints: /usr  (the trailing slash is ignored)

Exit status

Zero on success. dirname with no path argument is a usage error.

See also

basename, realpath

dirs back to top ↑

display directory stack

Synopsis

    dirs
    dirs [options]

Description

Displays the directory stack maintained by pushd and popd commands.
The stack shows directories in order from most recent (top) to oldest.

Options

    -c, --clear     Clear the directory stack.
    -l, --long      Show full paths (don't abbreviate home directory).
    -p              Print one directory per line.
    -v              Print with index numbers.

Examples

    dirs
        Show directory stack.

    pushd C:\Projects
    pushd C:\Temp
    pushd C:\Users
    dirs
        # C:\Users C:\Temp C:\Projects C:\OriginalDir

    dirs -v
        # 0  C:\Users
        # 1  C:\Temp
        # 2  C:\Projects
        # 3  C:\OriginalDir

    dirs -c
        Clear the stack.

Exit status

    0       Success

Notes

Stack Order:
- Index 0 is the current directory
- Higher indexes are older entries
- pushd adds to stack, popd removes

Empty Stack:
If no directories have been pushed, dirs shows only the current
directory.

Navigation:
Use pushd/popd for efficient navigation between multiple working
directories.

See also

pushd, popd, cd

dllimport back to top ↑

load DLL for function calls

Synopsis

    dllimport PATH
    dllimport PATH ALIAS

Description

Loads a Dynamic Link Library (DLL) into the shell process for later use
with rundllproc. The DLL remains loaded until explicitly unloaded or the
shell exits.

Options

    PATH            Path to the DLL file.
    ALIAS           Optional short name to reference the DLL.

Examples

    dllimport C:\MyApp\helper.dll
        Load DLL by path.

    dllimport C:\MyApp\helper.dll myhelper
        Load DLL with alias "myhelper".

    dllimport kernel32.dll
        Load system DLL.

    dllimport "C:\Program Files\App\plugin.dll" plugin
        Load DLL with spaces in path.

    # Then use with rundllproc:
    rundllproc myhelper DoSomething

Exit status

    0       Success
    1       DLL not found
    2       Load failed (dependencies missing, wrong architecture)
    3       Alias already in use

Notes

Dependencies:
The DLL and all its dependencies must be available. Check with
peinfo or Dependency Walker if loading fails.

Architecture:
32-bit DLLs can only be loaded by 32-bit CSHW.
64-bit DLLs can only be loaded by 64-bit CSHW.

Persistence:
Loaded DLLs remain in memory until:
- Explicitly unloaded with dllunload
- Shell exits

Use Cases:
- Calling custom DLL functions
- Automation with COM objects
- Extending shell functionality
- Testing DLL code

Security:
Only load DLLs you trust. Malicious DLLs can execute arbitrary code
in the shell process.

See also

dllunload, dlllist, rundllproc

dlllist back to top ↑

list imported DLLs

Synopsis

    dlllist

Description

Lists all DLLs currently loaded via dllimport. Shows the alias (if any)
and full path for each loaded DLL.

Examples

    dlllist
        # myhelper    C:\MyApp\helper.dll
        # plugin      C:\Program Files\App\plugin.dll
        # kernel32    C:\Windows\System32\kernel32.dll

    dllimport C:\test.dll test
    dlllist
        # test        C:\test.dll

Exit status

    0       Success (always)

Notes

Empty List:
If no DLLs have been imported, dlllist shows nothing.

System DLLs:
Only DLLs explicitly loaded with dllimport are shown, not DLLs
loaded automatically by the shell or Windows.

Management:
Use dlllist to see what's loaded before:
- Calling rundllproc
- Unloading with dllunload
- Debugging DLL issues

See also

dllimport, dllunload, rundllproc

dllunload back to top ↑

unload a previously imported DLL

Synopsis

    dllunload ALIAS
    dllunload PATH

Description

Unloads a DLL that was previously loaded with dllimport. Frees the DLL
from memory and removes it from the import cache.

Options

    ALIAS           Alias assigned during dllimport.
    PATH            Original path used in dllimport.

Examples

    dllunload myhelper
        Unload DLL by alias.

    dllunload C:\MyApp\helper.dll
        Unload DLL by path.

    dlllist
    # helper (C:\MyApp\helper.dll)
    dllunload helper
    dlllist
    # (empty)

Exit status

    0       Success
    1       DLL not found in cache

Notes

Reference Counting:
If other code still holds references to the DLL, it may not be
fully unloaded from memory until all references are released.

Cleanup:
It's good practice to unload DLLs when done, but they're automatically
cleaned up when the shell exits.

Error Handling:
Unloading a DLL while code is executing from it can cause crashes.
Ensure no operations are in progress.

See also

dllimport, dlllist, rundllproc

du back to top ↑

estimate file space usage

Synopsis

    du [path]
    du [options] [path]

Description

Estimates and displays the disk space used by files and directories.
Useful for finding large files or directories consuming disk space.

Options

    path            Directory to analyze (default: current directory).

    -h, --human-readable
                    Print sizes in human readable format (KB, MB, GB).
    -s, --summarize Show only total for each argument.
    -a, --all       Show sizes for all files, not just directories.
    -d N, --max-depth=N
                    Show totals for directories N levels deep.

Examples

    du
        Show disk usage for current directory tree.

    du -h
        Human-readable output.

    du -s *
        Summary of each item in current directory.

    du -h -s C:\Users
        Total size of Users directory.

    du -d 1
        Show only immediate subdirectories.

    du -h -d 2 C:\Projects
        Show projects with 2 levels of detail.

    du -a | sort -n | tail -20
        Find 20 largest items.

Exit status

    0       Success
    1       Path not found
    2       Access denied to some directories

Notes

Performance:
du must traverse the entire directory tree, which can be slow for
large directories or network drives.

Access Denied:
Some directories may be inaccessible. du continues with accessible
directories and reports errors for inaccessible ones.

Symbolic Links:
Symbolic links are not followed by default to prevent counting
the same files multiple times.

Finding Large Directories:
    du -h -d 1 | sort -h | tail -10

See also

df, dir, stat

echo back to top ↑

display text or variable values

Synopsis

    echo [text...]
    echo $variable
    echo "text with $variable expansion"

Description

Displays a line of text or the value of variables to standard output.
The echo command performs variable expansion, substituting $variable
references with their actual values.

echo is fundamental for shell scripts, debugging, and creating output.
It supports both simple text display and complex variable interpolation.

Options

    text            The text to display. Multiple arguments are separated
                    by spaces in the output.

    Variables are expanded:
    $name           Expands to the value of shell variable 'name'
    $?              Expands to the last command's exit code
    $:              Expands to the current working directory
    $$              Expands to the shell's process ID

Examples

    echo Hello World
        Displays: Hello World

    echo $PATH
        Displays the value of the PATH environment variable.

    echo "Current directory: $:"
        Shows current directory with label.

    echo "Last exit code was $?"
        Shows the previous command's exit code.

    echo The answer is $answer
        Variable expansion in unquoted text.

    echo "Hello, $name! Welcome to $:"
        Multiple variable expansions in one string.

    echo
        Outputs an empty line.

    echo "Line 1" > file.txt
        Redirect echo output to a file.

    echo "Another line" >> file.txt
        Append echo output to a file.

Exit status

    0       Success (always, unless I/O error)

Notes

Variable Expansion:
Variables prefixed with $ are automatically expanded. To display a literal
dollar sign, you can escape it or use single quotes in scripts.

Unlike UNIX echo, CSHW's echo does not support -n (no newline) or -e
(escape sequences) flags. Each echo command outputs a newline.

Empty Variables:
If a variable is not defined, $variable expands to an empty string
without generating an error.

Quoting:
Use double quotes to preserve spaces and ensure proper variable expansion.
Without quotes, multiple spaces between words may collapse to single spaces.

See also

set, type, printf

endsplash back to top ↑

dismiss the modeless splash dialog

Synopsis

    endsplash

Description

Dismisses the modeless splash dialog put up by `splash`. Safe to call
when no splash is showing -- it's a clean no-op.

Examples

    splash
    # ... long-running work ...
    endsplash

Exit status

    0       Always (success even when no splash is showing).

See also

splash, progressdlg

env back to top ↑

display or modify environment

Synopsis

    env
    env NAME=VALUE... COMMAND
    env -u NAME COMMAND

Description

Displays all environment variables or runs a command with a modified
environment. Useful for temporarily changing environment variables for
a single command without affecting the shell's environment.

Options

    Without arguments, displays all environment variables.

    NAME=VALUE      Set variable for the command.
    -u NAME         Unset variable for the command.
    -i              Start with empty environment.
    COMMAND         Command to run with modified environment.

Examples

    env
        Display all environment variables.

    env | grep PATH
        Show PATH-related variables.

    env DEBUG=1 myprogram.exe
        Run program with DEBUG=1 set.

    env -u PROXY myprogram.exe
        Run program with PROXY unset.

    env PATH="C:\Tools;%PATH%" tool.exe
        Run with modified PATH.

    env -i TERM=xterm program.exe
        Run with minimal environment.

Exit status

    0       Success (or command's exit code)
    1       Error

Notes

Temporary Changes:
env changes don't affect the shell. After the command completes,
the environment is unchanged:
    env DEBUG=1 program.exe
    # DEBUG is NOT set here

Display Format:
Variables are shown as NAME=VALUE, one per line.

Sorting:
Output is typically sorted alphabetically by name.

Comparison:
- env: Display or temporarily modify environment
- setenv: Permanently set in current shell
- printenv: Display only (no modification)

See also

setenv, unsetenv, printenv, set

eval back to top ↑

concatenate arguments and run the result as a command

Synopsis

    eval [argument ...]

Description

Join the arguments together with single spaces and run the resulting
string as a command in the current shell. The arguments have already
been through one round of the shell's tokenizing and expansion; running
the joined string back through the shell triggers a second round.

That second round is the whole point of eval. Use it when:
    - a command line has been built up inside a variable
    - variable or command-substitution expansion must be deferred until
      the moment eval runs, rather than when the line was first parsed

eval runs in the current shell, so any variable assignments, cd, or
other state changes made by the evaluated command persist.

Examples

    set cmd = "echo hello"
    eval $cmd
        Runs: echo hello

    eval 'echo $HOME'
        The single quotes stop $HOME from expanding when the line is
        first read; eval expands it on the second pass.

    set assign = "set count = 5"
    eval $assign
        $count is now 5 in the current shell.

Exit status

The exit status is that of the evaluated command. eval with no
arguments is a successful no-op.

Notes

Quoting from the first parse is intentionally not preserved -- eval's
contract is to re-parse. `eval echo "a b"` runs `echo a b`, passing
two arguments.

See also

source, exec, set

exec back to top ↑

replace shell with command

Synopsis

    exec COMMAND [ARGS...]

Description

Replaces the current shell process with the specified command. The command
runs in place of the shell - when the command exits, there is no shell
to return to.

Options

    COMMAND         Command to execute.
    ARGS            Arguments for the command.

Examples

    exec notepad
        Replace shell with Notepad.

    exec cmd
        Replace shell with Windows cmd.exe.

    exec /usr/bin/bash
        Replace with another shell.

    exec python script.py
        Run Python script, exit when done.

Exit status

    Does not return (shell is replaced).

Notes

No Return:
exec does not return. The shell process is completely replaced
by the new command. When that command exits, the window closes.

Use Cases:
- Final command in a script
- Switching to another shell
- Wrapper scripts that launch another program
- Reducing process overhead (no extra shell process)

Comparison with start:
- exec: Replaces shell, no return
- start: New window, shell continues

Resource Efficiency:
exec is slightly more efficient than starting a child process
because it doesn't keep the shell running.

Scripts:
In scripts, commands after exec never run:
    exec myprogram
    echo "Never executed"

See also

start, source, exit

exit back to top ↑

exit the shell

Synopsis

    exit [CODE]

Description

Terminates the shell session. An optional exit code can be specified
to return to the parent process or operating system.

In scripts, exit terminates script execution and returns the specified
code.

Options

    CODE            Integer exit code (default: 0).
                    Convention:
                    0 = success
                    non-zero = error/failure

Examples

    exit
        Exit shell with code 0 (success).

    exit 0
        Explicitly exit with success.

    exit 1
        Exit with error code 1.

    # In a script:
    if ($result != "ok")
        exit 1
    endif
        Exit script on error condition.

Exit status

    Returns the specified CODE or 0 if not specified.

Notes

Running Jobs:
If background jobs are running, exit may warn you. Use 'jobs' to
check for running jobs before exiting.

Scripts:
In scripts, exit immediately terminates execution. No further
commands are run.

Return vs Exit:
In procedures, use 'return' instead of 'exit' to return control
to the caller without terminating the shell.

See also

return, jobs, logout

false back to top ↑

return failure (documented with true)

Synopsis

    false

Description

Sets $status to 1 (failure). Documented alongside `true` and `nop`
on a single page -- see `man true` for full details.

See also

true, nop, exit

fetch back to top ↑

download files from URLs

Synopsis

    fetch URL
    fetch URL -o OUTPUT
    fetch [options] URL

Description

Downloads files from HTTP and HTTPS URLs. Supports redirects, resume,
and output to file or stdout. Similar to wget or curl.

Options

    URL             The URL to download from.

    -o, --output FILE
                    Save to FILE instead of default filename.

    -O              Use remote filename (derive from URL).

    -c, --continue  Resume interrupted download.

    -q, --quiet     Suppress progress output.

    -v, --verbose   Show detailed progress.

    --no-check-certificate
                    Skip SSL certificate verification.

Examples

    fetch https://example.com/file.zip
        Download file.zip to current directory.

    fetch -o download.zip https://example.com/file.zip
        Download and save as download.zip.

    fetch -c https://example.com/large.iso
        Resume interrupted download.

    fetch https://api.example.com/data.json | grep "status"
        Download and pipe to grep.

    fetch -q https://example.com/script.sh
        Download quietly (no progress).

Exit status

    0       Success
    1       Network error
    2       HTTP error (404, 500, etc.)
    3       Invalid URL
    4       Write error

Notes

HTTPS:
fetch supports HTTPS with SSL/TLS. Certificate verification is enabled
by default. Use --no-check-certificate only when necessary.

Progress:
Download progress is shown with percentage, speed, and ETA.
Use -q to suppress or redirect stderr.

Large Files:
fetch handles large files efficiently, streaming to disk rather than
loading entirely into memory.

Authentication:
For URLs requiring authentication, include credentials in the URL:
    fetch https://user:pass@example.com/file

Proxies:
fetch respects system proxy settings from Internet Options.

See also

type, genai

fg back to top ↑

move job to foreground

Synopsis

    fg [%JOBID]

Description

Brings a background job to the foreground, making it the active process.
If no job ID is specified, operates on the current job.

Options

    %JOBID          Job number (from jobs command).

Examples

    fg
        Bring current job to foreground.

    fg %1
        Bring job 1 to foreground.

    fg %2
        Bring job 2 to foreground.

Exit status

    0       Success
    1       No such job

Notes

Interaction:
Once in foreground, you can interact with the process normally.
Use Ctrl+Z to stop and background it again.

Wait for Completion:
fg waits for the job to complete or be stopped before returning
control to the shell.

See also

bg, jobs, kill, stop

file back to top ↑

identify file type

Synopsis

    file FILE
    file FILE...

Description

Determines file type by examining content, not just the extension. Uses
"magic numbers" (byte patterns) to identify file formats.

Options

    FILE            One or more files to identify.

    -b, --brief     Don't show filename in output.
    -i, --mime      Output MIME type instead of description.
    -z              Try to look inside compressed files.

Examples

    file document.pdf
        # document.pdf: PDF document, version 1.4

    file image.png
        # image.png: PNG image data, 800 x 600, 8-bit/color RGBA

    file program.exe
        # program.exe: PE32+ executable (GUI) x86-64

    file unknown
        # unknown: ASCII text

    file mystery.dat
        # mystery.dat: Zip archive data, at least v2.0 to extract

    file -i document.pdf
        # document.pdf: application/pdf

    file *
        Identify all files in directory.

Exit status

    0       Success
    1       Error

Notes

Magic Numbers:
Many file formats start with distinctive byte sequences:
- PNG: 89 50 4E 47 0D 0A 1A 0A
- PDF: 25 50 44 46 (% P D F)
- ZIP: 50 4B 03 04
- EXE: 4D 5A (MZ)
- JPEG: FF D8 FF

Extension Independence:
file identifies by content, so renamed files are identified correctly:
    mv image.png image.txt
    file image.txt   # Still identifies as PNG

Use Cases:
- Verify file types before processing
- Find misnamed files
- Security analysis
- Batch file organization

Unknown Files:
For unrecognized formats, file reports basic type:
- "data" for binary files
- "ASCII text" or "UTF-8 text" for text

See also

hexdump, strings, peinfo

fileblob back to top ↑

encode a file into a one-line text blob

Synopsis

    fileblob <file>

Description

fileblob reads <file> and writes a single line of text -- a "blob" --
to standard output. The blob is the file's bytes base64-encoded behind
a CSHWBLOB1 header that also records the original filename:

    CSHWBLOB1:<original-name>:<base64-data>

Because the blob is plain text it can go wherever text can: captured
into a shell variable, redirected to a .blob file, or pasted inline in
a script -- a way to carry a binary asset (an icon, a small data file)
as text. Decode it again with unfileblob.

Examples

    set logo = `fileblob icon.png`
        Hold a binary asset in a shell variable.

    fileblob icon.png > icon.blob
        Save the blob to a file for use later.

Exit status

0 on success; non-zero if the file cannot be read.

See also

unfileblob, base64

find back to top ↑

search for files in directory tree

Synopsis

    find [path] [options]
    find [path] -name PATTERN
    find [path] -type TYPE

Description

Searches for files and directories in a directory tree based on various
criteria including name patterns, file types, size, and modification time.
By default, find starts from the current directory and searches recursively.

find is essential for locating files when you don't know their exact
location, or for finding files matching certain criteria across large
directory structures.

Options

    path            Starting directory for the search (default: current dir).

    -name PATTERN   Find files matching PATTERN (supports * and ? wildcards).
                    The match is case-insensitive on Windows.

    -iname PATTERN  Case-insensitive name match (same as -name on Windows).

    -type TYPE      Filter by type:
                    f   Regular files only
                    d   Directories only

    -size [+|-]N    Find files by size:
                    N   Exactly N bytes
                    +N  Greater than N bytes
                    -N  Less than N bytes
                    Suffixes: k (KB), M (MB), G (GB)

    -mtime [+|-]N   Find by modification time (days):
                    N   Modified exactly N days ago
                    +N  Modified more than N days ago
                    -N  Modified less than N days ago

    -maxdepth N     Descend at most N directory levels.

    -mindepth N     Start applying tests at directory level N.

Examples

    find
        List all files and directories from current location.

    find . -name "*.txt"
        Find all .txt files in current directory tree.

    find C:\Users -name "*.doc"
        Find all .doc files under C:\Users.

    find . -type f -name "*.log"
        Find only files (not directories) with .log extension.

    find . -type d
        Find only directories.

    find . -size +10M
        Find files larger than 10 megabytes.

    find . -size -1k
        Find files smaller than 1 kilobyte.

    find . -mtime -7
        Find files modified in the last 7 days.

    find . -mtime +30
        Find files not modified in 30+ days.

    find . -name "*.tmp" -type f
        Find temporary files (not directories).

    find . -maxdepth 2 -name "*.exe"
        Search only 2 levels deep for executables.

    find C:\Projects -name "main.cpp"
        Locate main.cpp files in Projects folder.

Exit status

    0       Success (matches may or may not have been found)
    1       Path not found or invalid
    2       Syntax error or invalid option

Notes

Performance:
For very large directory trees, find may take some time. Use -maxdepth
to limit the search scope when possible.

Wildcards:
The -name pattern uses shell glob syntax:
    *       Matches any sequence of characters
    ?       Matches any single character
    [abc]   Matches any character in the set

Output Format:
Each matching file is printed on its own line with its full path.

Combining with Other Commands:
Use find output with other commands via piping:
    find . -name "*.log" | grep error
    find . -name "*.bak" | wc -l

See also

dir, grep, where, which

ftpfetch back to top ↑

FTP file transfer client

Synopsis

    ftpfetch URL
    ftpfetch [options] URL

Description

Downloads files from FTP servers. Supports anonymous and authenticated
FTP transfers.

Options

    URL             FTP URL to download from.
                    Format: ftp://[user:pass@]host/path

    -o FILE         Output filename (default: derived from URL).
    -u USER         FTP username.
    -p PASS         FTP password.
    -P PORT         FTP port (default: 21).
    -v, --verbose   Show transfer progress.
    --passive       Use passive mode (default).
    --active        Use active mode.

Examples

    ftpfetch ftp://ftp.example.com/pub/file.zip
        Anonymous download.

    ftpfetch -o download.zip ftp://ftp.example.com/file.zip
        Download with specific output name.

    ftpfetch -u myuser -p mypass ftp://ftp.example.com/private/data.txt
        Authenticated download.

    ftpfetch ftp://user:pass@ftp.example.com/file.txt
        Credentials in URL.

    ftpfetch -v ftp://ftp.example.com/large.iso
        Verbose mode with progress.

Exit status

    0       Success
    1       Connection error
    2       Authentication failed
    3       File not found
    4       Transfer error

Notes

Anonymous FTP:
Without credentials, ftpfetch uses anonymous login (typically
"anonymous" with email as password).

Passive vs Active:
- Passive mode (default): Works through firewalls
- Active mode: May be blocked by firewalls

URL Format:
    ftp://ftp.example.com/pub/file.txt      Anonymous
    ftp://user:pass@ftp.example.com/file    Authenticated

Binary vs ASCII:
ftpfetch uses binary mode by default, appropriate for most files.

Security:
FTP transmits credentials in plain text. For secure transfers,
consider SFTP or HTTPS instead.

Large Files:
ftpfetch supports large files and shows progress in verbose mode.

See also

fetch, copy

genai back to top ↑

interact with AI language models

Synopsis

    genai register PROVIDER API_KEY [options]
    genai list
    genai remove NAME
    genai default NAME
    genai complete PROMPT
    genai chat
    genai analyze FILE

Description

Interface to generative AI language models including OpenAI (GPT) and
Anthropic (Claude). The genai command allows you to register AI providers,
send prompts, have conversations, and analyze files using AI.

This is a powerful tool for code generation, text analysis, problem
solving, and interactive AI assistance directly from the shell.

Options

    Subcommands:

    register PROVIDER API_KEY [options]
        Register a new AI provider.
        PROVIDER: openai, anthropic
        API_KEY: Your API key for the provider
        Options:
            --model MODEL       Model to use (e.g., gpt-4, claude-3-opus)
            --name NAME         Custom name for this configuration
            --default           Set as default provider

    list
        Display all registered AI providers.

    remove NAME
        Remove a registered provider configuration.

    default NAME
        Set the default AI provider.

    complete PROMPT
        Send a prompt and get a completion response.
        Also accepts piped input.

    chat
        Start an interactive chat session.
        Type 'exit' or 'quit' to end.

    analyze FILE
        Send file contents to AI for analysis.

Examples

    genai register openai sk-xxx123 --model gpt-4 --default
        Register OpenAI with GPT-4 as the default.

    genai register anthropic sk-ant-xxx --model claude-3-opus --name claude
        Register Anthropic's Claude as 'claude'.

    genai list
        Show all registered AI providers.

    genai default claude
        Switch default to the 'claude' configuration.

    genai complete "Write a Python hello world program"
        Get an AI-generated response.

    genai complete "Explain this code:" < script.py
        Pipe file content with a prompt.

    type error.log | genai complete "What caused this error?"
        Analyze log file with AI.

    genai chat
        Start interactive conversation mode.

    genai analyze main.cpp
        Have AI analyze a source file.

    echo "Translate to French: Hello" | genai complete
        Use piped input as the prompt.

Exit status

    0       Success
    1       Provider not found or not configured
    2       API error (invalid key, rate limit, etc.)
    3       Network error
    4       Invalid arguments

Environment

    OPENAI_API_KEY      Default API key for OpenAI
    ANTHROPIC_API_KEY   Default API key for Anthropic

Files

    %APPDATA%\cshw\genai.json    Stored provider configurations

Notes

API Keys:
Keep your API keys secure. They are stored in the configuration file.
Consider using environment variables for sensitive keys.

Rate Limits:
AI providers have rate limits. If you exceed them, you'll receive an
error. Wait before retrying.

Costs:
API calls may incur costs depending on your provider plan. Monitor
your usage on the provider's dashboard.

Model Selection:
Different models have different capabilities and costs:
- gpt-4: Most capable OpenAI model, higher cost
- gpt-3.5-turbo: Fast and economical
- claude-3-opus: Most capable Anthropic model
- claude-3-sonnet: Balanced performance/cost

Token Limits:
Each model has maximum token limits. Very long prompts or files may
be truncated or cause errors.

Interactive Chat:
In chat mode, context is maintained within the session. The AI
remembers previous messages in the conversation.

See also

type, echo, fetch

glob back to top ↑

expand filename patterns

Synopsis

    glob PATTERN
    glob PATTERN...

Description

Expands wildcard patterns into matching filenames. Useful for testing
patterns before using them in commands, or in scripts that need explicit
filename lists.

Options

    PATTERN         Wildcard pattern to expand.

    Wildcards:
    *               Match any characters (including none)
    ?               Match exactly one character
    [abc]           Match any character in brackets
    [a-z]           Match character range
    [!abc]          Match any character NOT in brackets

Examples

    glob *.txt
        List all .txt files.

    glob src/*.cpp
        List C++ files in src directory.

    glob [A-Z]*.doc
        Files starting with uppercase letter.

    glob ???.txt
        Three-character names with .txt extension.

    glob **/*.h
        Recursively find header files.

    glob file[0-9].dat
        Match file0.dat through file9.dat.

    glob *.[ch]
        Match .c and .h files.

    glob [!._]*
        Files not starting with . or _

Exit status

    0       Matches found
    1       No matches

Notes

No Matches:
If no files match, glob either returns the pattern unchanged or
returns an error, depending on shell settings.

Escaping:
To match literal wildcard characters, escape them:
    glob file\*.txt   # Matches "file*.txt" literally

Hidden Files:
By default, patterns don't match files starting with '.'
Use .* to explicitly match hidden files.

Directory Patterns:
glob can expand directories too:
    glob */          # All subdirectories

Recursive Patterns:
Use **/ for recursive matching:
    glob **/*.log    # All .log files in all subdirectories

Use in Scripts:
    set files=$(glob *.txt)
    foreach f ($files)
        echo "Processing $f"
    endforeach

See also

find, dir, ls

grep back to top ↑

search for patterns in files

Synopsis

    grep [options] PATTERN [FILE...]
    grep [options] PATTERN

Description

Searches for PATTERN in each FILE or standard input. By default, grep prints
the matching lines. PATTERN is a regular expression using PCRE2 (Perl
Compatible Regular Expressions) syntax when available, falling back to
std::wregex otherwise.

grep is one of the most powerful text-processing tools in CSHW, supporting
both simple string searches and complex pattern matching with full regex
capabilities including lookahead, lookbehind, and Unicode support.

When reading from standard input (piped data), grep processes each line
and outputs those matching the pattern.

Options

    PATTERN         The regular expression to search for.
    FILE...         One or more files to search. If omitted, reads stdin.

    -i, --ignore-case
                    Perform case-insensitive matching.

    -v, --invert-match
                    Invert the sense of matching - select non-matching lines.

    -n, --line-number
                    Prefix each output line with its line number in the file.

    -h, --no-filename
                    Suppress the prefixing of filenames on output when
                    searching multiple files.

    -r, --recursive
                    Recursively search subdirectories.

    -l, --files-with-matches
                    Only print filenames containing matches (not the lines).

    -c, --count
                    Only print a count of matching lines per file.

Examples

    grep error log.txt
        Find lines containing "error" in log.txt.

    grep -i ERROR log.txt
        Case-insensitive search for "error".

    grep -n "TODO" *.cpp
        Show line numbers for TODO comments in C++ files.

    grep -r "password" .
        Recursively search for "password" in current directory tree.

    grep -v "^#" config.txt
        Show lines NOT starting with # (non-comments).

    grep "^\s*$" file.txt
        Find empty or whitespace-only lines.

    type log.txt | grep -i warning
        Search piped input for warnings (case-insensitive).

    grep "[0-9]{3}-[0-9]{4}" contacts.txt
        Find phone number patterns (###-####).

    grep -rn "class\s+\w+" src/
        Find class definitions in source directory.

    dir /b | grep "\.txt$"
        Filter dir output to show only .txt files.

    grep "^(GET|POST)" access.log
        Find HTTP GET or POST requests in log.

    grep -l "main" *.cpp
        List .cpp files containing "main".

Exit status

    0       One or more matches were found
    1       No matches were found
    2       Error occurred (file not found, invalid regex, etc.)

Notes

PCRE2 Regular Expression Quick Reference:

    .       Any character (except newline)
    ^       Start of line
    $       End of line
    *       Zero or more of preceding
    +       One or more of preceding
    ?       Zero or one of preceding
    [abc]   Character class (a, b, or c)
    [^abc]  Negated class (not a, b, or c)
    [a-z]   Character range
    \d      Digit [0-9]
    \w      Word character [a-zA-Z0-9_]
    \s      Whitespace
    \b      Word boundary
    (x|y)   Alternation (x or y)
    (...)   Grouping
    {n}     Exactly n occurrences
    {n,m}   Between n and m occurrences
    (?=...) Positive lookahead
    (?!...) Negative lookahead
    (?i)    Case-insensitive mode (inline)

CSHW's grep uses PCRE2 with JIT compilation for optimal performance on
large files. The JIT compiler provides near-native speed for complex patterns.

See also

find, type, wc, sort, uniq

hash back to top ↑

create or manipulate an associative array (hash) variable

Synopsis

    hash <name>
    hash <name> <key1>=<value1> <key2>=<value2> ...

Description

Creates an associative array (string-keyed hash) variable. With only a
name, creates an empty hash. With trailing `<key>=<value>` pairs,
initializes the hash with those entries.

Hash elements are read with `${name{<key>}}` and written with
`set name{<key>} = <value>`.

Options

    <name>      Hash name. Same rules as scalar variable names.
    <key>=<value>
                Optional initial entries.

Examples

    hash users alice=admin bob=user
    echo "alice is $users{alice}"

    hash settings
    set settings{theme} = "dark"
    set settings{font}  = "Consolas"

Exit status

    0       Hash declared / updated.
    1       Bad name or syntax error.

Notes

For integer-indexed arrays, see `array`. The two styles are distinct:
`array` uses [], `hash` uses {}.

See also

array, set, unset, declare

hashstat back to top ↑

display command hash table statistics

Synopsis

    hashstat

Description

Displays statistics about the command hash table, including the number
of entries, hits, misses, and efficiency information.

Examples

    hashstat
        # Hash table statistics:
        # Entries: 45
        # Hits: 234
        # Misses: 12
        # Hit rate: 95.1%

Exit status

    0       Success

Notes

Statistics Shown:
- Number of cached command paths
- Cache hit count (found in hash)
- Cache miss count (required PATH search)
- Hit rate percentage

Performance Tuning:
High miss rates might indicate:
- Commands not in expected locations
- Frequent PATH changes
- Need to run rehash

Debugging:
Use hashstat to understand shell command lookup performance.

See also

rehash, unhash, which

head back to top ↑

output the first part of files

Synopsis

    head [options] FILE
    head -n COUNT FILE
    command | head [options]

Description

Outputs the first part of files or piped input. By default, prints the
first 10 lines. Useful for previewing files or limiting output.

Options

    FILE            File to read from.

    -n COUNT        Output the first COUNT lines (default: 10).
    -COUNT          Shorthand for -n COUNT (e.g., -20).

    -c COUNT        Output the first COUNT bytes instead of lines.

Examples

    head file.txt
        Display first 10 lines of file.txt.

    head -n 20 log.txt
        Display first 20 lines.

    head -50 data.csv
        Display first 50 lines (shorthand).

    dir /s | head -n 30
        Show first 30 lines of dir output.

    head -c 100 binary.dat
        Show first 100 bytes.

    type largefile.txt | head
        Preview beginning of a large file.

Exit status

    0       Success
    1       File not found
    2       Read error

Notes

Default Lines:
Without -n, head outputs 10 lines by default.

Binary Files:
Use -c for binary files where line concepts don't apply.

Piping:
head is commonly used at the end of a pipeline to limit output:
    find . -name "*.log" | head -n 5

See also

tail, type, wc

hexdump back to top ↑

display file contents in hexadecimal

Synopsis

    hexdump [options] FILE
    command | hexdump [options]

Description

Displays file contents in hexadecimal format with optional ASCII
representation. Essential for examining binary files, debugging data
formats, and analyzing file structures.

Options

    FILE            File to display.

    -C              Canonical format: hex + ASCII (most common).
    -n LENGTH       Display only first LENGTH bytes.
    -s OFFSET       Skip OFFSET bytes from start.
    -v              Display all data (don't suppress duplicate lines).

Examples

    hexdump -C file.bin
        Display file in canonical hex+ASCII format.

    hexdump -C -n 256 program.exe
        Show first 256 bytes of executable.

    hexdump -C -s 1024 -n 512 file.dat
        Show 512 bytes starting at offset 1024.

    echo "Hello" | hexdump -C
        See hex representation of text.

    hexdump -C image.png | head -20
        Preview beginning of PNG file.

Exit status

    0       Success
    1       File not found
    2       Read error

Notes

Output Format (Canonical -C):
    00000000  48 65 6c 6c 6f 20 57 6f  72 6c 64 0a              |Hello World.|
    OFFSET    HEX BYTES (16 per line)                          ASCII

Reading Hex:
- Each hex pair represents one byte (00-FF)
- ASCII column shows printable characters
- Non-printable bytes shown as '.'

File Signatures:
Many file formats have distinctive headers ("magic numbers"):
- PNG: 89 50 4E 47 0D 0A 1A 0A
- PDF: 25 50 44 46 (% P D F)
- EXE: 4D 5A (MZ)
- ZIP: 50 4B 03 04

See also

base64, strings, file, type

history back to top ↑

display command history

Synopsis

    history
    history [N]
    history -c

Description

Displays the list of previously executed commands. CSHW maintains a history
of commands entered during the current session and optionally across
sessions if persistence is enabled.

The history command is invaluable for recalling previous commands,
understanding what operations were performed, and repeating or modifying
past commands.

Options

    N               Display only the last N commands.

    -c, --clear     Clear the command history.

Examples

    history
        Display all commands in history.

    history 20
        Display the last 20 commands.

    history -c
        Clear all command history.

Exit status

    0       Success

Notes

History Navigation:
Use the up/down arrow keys at the command prompt to navigate through
previous commands.

History Size:
The shell maintains a configurable maximum number of history entries.
Older entries are removed when the limit is reached.

History Persistence:
History is saved to %APPDATA%\cshw\history and restored on shell startup.
Use the history_max shell variable to configure the maximum number of
entries persisted.

Command Recall:
Previous commands can be recalled and edited before re-execution using
the arrow keys.

Duplicate Handling:
Consecutive duplicate commands may be stored only once to keep the
history clean.

See also

alias, set

hostname back to top ↑

display the system hostname

Synopsis

    hostname [options]

Description

Displays the computer's network hostname. By default, shows the NetBIOS
name. Options allow retrieving the DNS hostname or fully qualified
domain name (FQDN).

Options

    -f, --fqdn    Display fully qualified domain name (e.g., host.domain.com)
    -d, --dns     Display DNS hostname

Examples

    hostname
        MYCOMPUTER

    hostname -f
        mycomputer.corp.example.com

    hostname -d
        mycomputer

Notes

This command displays the hostname but cannot change it. To change the
hostname on Windows, use:
    - System Properties > Computer Name
    - PowerShell: Rename-Computer -NewName "NewName"
    - Control Panel: sysdm.cpl

The difference between name types:
    - NetBIOS name: Legacy Windows network name (up to 15 characters)
    - DNS hostname: Modern hostname used by DNS
    - FQDN: Complete DNS name including domain suffix

See also

uname, whoami, winver

install back to top ↑

install cshw onto the system

Synopsis

    install [path] [/user]

Description

Copies cshw.exe and its supporting files (man pages, runtime DLLs) to
an install location, then updates PATH so `cshw` is invocable by name
from any prompt.

By default the install is system-wide (under Program Files, writes
HKLM PATH) and requires admin. With /user, the install is per-user
(under %LOCALAPPDATA%, writes HKCU PATH) and runs without elevation.

Options

    path        Optional explicit install directory. If omitted, uses
                a sensible default based on whether /user is set.
    /user       Install per-user under %LOCALAPPDATA%. No admin needed.
                Modifies only HKCU PATH.

Examples

    install
        System-wide install to Program Files. Requires admin.

    install /user
        Per-user install to %LOCALAPPDATA%\Tropibyte\cshw.

    install "C:\tools\cshw"
        System-wide install to an explicit directory.

Exit status

    0       Install succeeded.
    1       Permission denied (not running elevated for a system
            install) or copy/registry write failure.

Notes

The Inno Setup installer (cshw-setup-X.Y.Z.exe) is the recommended
distribution mechanism for end users -- it adds file associations,
Windows Terminal integration, and an uninstaller. This `install`
command is the lightweight in-shell alternative for scripted setups
or developer workflows.

See also

sudo, rcl

isWindows back to top ↑

check if running on Windows

Synopsis

    iswindows
    isWindows

Description

Returns true (exit code 0) if running on Windows, false (exit code 1)
otherwise. Useful for cross-platform scripts that need to detect the
operating system.

Examples

    iswindows
    echo $?
        # 0 on Windows

    if ($(iswindows))
        echo "Running on Windows"
    else
        echo "Not Windows"
    endif

    iswindows && echo "Windows detected"

Exit status

    0       Running on Windows (true)
    1       Not running on Windows (false)

Notes

Always True:
In CSHW, this always returns 0 because CSHW only runs on Windows.
It exists for script compatibility.

Cross-Platform Scripts:
Useful when writing scripts that might run on different shells:
    if ($(iswindows))
        set pathsep=";"
    else
        set pathsep=":"
    endif

Case Insensitivity:
Both 'iswindows' and 'isWindows' work identically (Windows is
case-insensitive for command names).

See also

uname, winver

jobs back to top ↑

display status of background jobs

Synopsis

    jobs
    jobs [options]

Description

Displays the status of jobs that have been started in the background.
Each job is identified by a job number and shows its current state
(running, stopped, completed) along with the command that started it.

Job control allows you to run multiple commands simultaneously, switching
between foreground and background execution as needed.

Options

    -l              Long format - include process IDs.
    -p              Print only process IDs.
    -r              Display only running jobs.
    -s              Display only stopped jobs.

Examples

    jobs
        List all background jobs.

    jobs -l
        List jobs with process IDs.

    jobs -r
        Show only currently running jobs.

Exit status

    0       Success

Notes

Job States:
    RUNNING     - Job is currently executing
    STOPPED     - Job has been suspended (Ctrl+Z)
    COMPLETED   - Job has finished execution

Job Numbers:
Jobs are assigned sequential numbers starting from 1. These numbers
can be used with fg, bg, kill, and other job control commands.

Starting Background Jobs:
To start a command in the background, append & to the command line:
    longprocess.exe &

Current and Previous Jobs:
The most recently backgrounded job is the "current" job (+).
The previously backgrounded job is the "previous" job (-).

See also

fg, bg, kill, stop, processlist

kad back to top ↑

kill process and secure-delete its executable (alias for killanddel)

Synopsis

    kad <pid_or_name>

Description

`kad` is identical to `killanddel`. See `man killanddel` for full
documentation.

See also

killanddel, kill, processlist

kill back to top ↑

terminate processes

Synopsis

    kill PID
    kill -9 PID
    kill %JOBID

Description

Terminates a process by its process ID (PID) or job number. By default,
kill attempts a graceful termination, but can forcefully terminate
processes that don't respond.

kill is essential for managing runaway processes, stopping hung programs,
and controlling background jobs.

Options

    PID             Process ID to terminate (numeric).

    %JOBID          Job number from jobs command (prefixed with %).

    -9, -KILL       Forcefully terminate (no cleanup allowed).

    -15, -TERM      Request graceful termination (default).

    /f              Force termination (same as -9).

    /t              Terminate process tree (include child processes).

Examples

    kill 1234
        Terminate process with PID 1234.

    kill -9 1234
        Forcefully terminate process 1234.

    kill %1
        Terminate job number 1.

    kill /f /t 1234
        Force-kill process 1234 and all its children.

    processlist | grep notepad
        # Find notepad's PID, then:
    kill 5678
        Terminate notepad process.

Exit status

    0       Success - process terminated
    1       Process not found
    2       Access denied (need administrator privileges)
    3       Invalid argument

Notes

Process Trees:
Some processes spawn child processes. Use /t to terminate the entire
process tree, not just the parent.

Access Rights:
You can only kill processes you own, unless running as Administrator.
System processes may require elevated privileges.

Graceful vs Forced:
Without -9, kill sends a termination request allowing the process to
clean up (save files, release resources). With -9, the process is
immediately terminated with no cleanup.

Finding PIDs:
Use 'processlist' or 'ps' to find process IDs, or use Task Manager.

Hung Processes:
If a process doesn't respond to normal kill, use -9 to force termination.

See also

processlist, jobs, bg, fg, killanddel

killanddel back to top ↑

kill processes and securely delete executables

Synopsis

    killanddel [options] EXECUTABLE_PATH
    kad [options] EXECUTABLE_PATH

Description

Aliases: kad

Terminates all processes running a specified executable and securely
deletes the file. Designed for removing malware that respawns quickly
after deletion.

The command performs these steps:
1. Find all processes running the executable
2. Forcefully terminate those processes
3. Open file with exclusive access (prevent respawn)
4. Overwrite file contents with zeros
5. Delete the file

Options

    EXECUTABLE_PATH Path to the executable to kill and delete.

    /v, /verbose    Show detailed progress.
    /a, /ancestors  Show process ancestry (parent, grandparent).
    /r:N, /recurse:N
                    Also kill N levels of ancestor processes.
    /admin          Run with elevated Administrator privileges.
    /f, /force      Don't prompt for confirmation.
    /dry            Dry run - show actions without performing them.

Examples

    killanddel C:\temp\malware.exe
        Kill process and delete file.

    kad C:\temp\malware.exe
        Short form of killanddel.

    kad /v /a C:\temp\malware.exe
        Verbose output with ancestry display.

    kad /r:1 C:\temp\malware.exe
        Also kill the parent process.

    kad /dry C:\temp\suspicious.exe
        Preview what would happen.

    kad /admin C:\temp\malware.exe
        Run as Administrator for system-level access.

Exit status

    0       Success - process killed and file deleted
    1       File not found
    2       Access denied (may need /admin)
    3       Process termination failed
    4       File deletion failed

Notes

Secure Deletion:
Before deleting, the file is overwritten with zeros. This prevents
simple file recovery tools from retrieving the original content.

Process Ancestry:
The /a flag shows the process tree, helpful for identifying if
malware has spawned from or infected another process.

Recursive Killing:
/r:1 kills the malware's parent process. /r:2 kills parent and
grandparent. Use carefully - you may kill legitimate processes.

Administrator Rights:
Many malware processes run with elevated privileges. Use /admin
to ensure you can terminate them.

Respawn Prevention:
By opening the file exclusively before killing processes, killanddel
prevents watchdog processes from respawning the malware.

Dry Run:
Always use /dry first on unfamiliar malware to see what will happen
before actually killing processes.

See also

kill, processlist, del

lc back to top ↑

count lines in files

Synopsis

    lc FILE
    lc PATTERN
    lc [/s] [/q] PATTERN[,PATTERN,...]
    lc [/s] [/q] DIR\PATTERN[,PATTERN,...]
    linecount [options] PATTERN...

Description

Counts the number of lines in files matching the specified pattern(s).
Supports wildcards, multiple patterns, and recursive directory traversal.
This is useful for quickly determining the size of a codebase or project.

When counting multiple files, displays the line count for each file
followed by a summary showing total lines and file count.

The command name 'linecount' is an alias for 'lc'.

Options

    FILE            Single file to count lines in.

    PATTERN         Wildcard pattern (e.g., *.cpp, *.h, file?.txt).
                    Supports * (match any characters) and ? (match
                    single character).

    /s, -s, -r, --recursive
                    Recurse into subdirectories. Without this flag,
                    only files in the specified directory are counted.

    /q, -q, --quiet
                    Quiet mode. Only display the final total, not
                    individual file counts. Useful for scripts.

    Multiple patterns can be specified:
    - Comma-separated: *.cpp,*.h,*.c
    - As separate arguments: *.cpp *.h *.c (if shell supports)

Examples

    lc readme.txt
        Count lines in a single file.

    lc *.cpp
        Count lines in all .cpp files in current directory.

    lc /s *.cpp
        Count lines in all .cpp files, including subdirectories.

    lc /s *.cpp,*.h
        Count lines in all C++ source and header files recursively.

    lc /s /q *.c,*.h
        Quietly count all C files recursively (only show total).

    lc src\*.cpp
        Count lines in .cpp files in the src subdirectory.

    lc /s src\*.cpp,*.h,*.c
        Count C/C++ files in src directory tree.

    lc /s *.cpp,*.h,*.c,*.rc,*.vcxproj
        Count all Visual Studio C++ project source files.

    linecount /s *.py
        Count Python files recursively (using alias).

Exit status

    0       Success
    1       Syntax error or no files found

Notes

Codebase Size Estimation:
Use lc to get accurate line counts for your project instead of
guessing. Example for a typical C++ Visual Studio project:

    lc /s *.cpp,*.h,*.c,*.rc,*.vcxproj,*.props

This counts all source files, resource files, and project files.

Pattern Matching:
Patterns are case-insensitive on Windows. The following wildcards
are supported:
    *       Match zero or more characters
    ?       Match exactly one character

Examples:
    *.cpp       All files ending in .cpp
    test*.h     Header files starting with "test"
    file?.txt   file1.txt, fileA.txt, but not file10.txt

Performance:
For large codebases, consider using /q (quiet) mode to reduce
output overhead. The line counting itself is efficient, reading
files line by line without loading entire files into memory.

Binary Files:
Binary files will be counted but may report inaccurate line counts
since they don't contain proper line endings. For best results,
use patterns that match only text files.

Comparison with wc:
- wc: UNIX-style word count for single file (lines, words, bytes)
- lc: Line count optimized for multiple files with patterns

Empty Files:
Empty files are included in the file count but contribute 0 lines.

See also

wc, find, dir, grep

library back to top ↑

load CSHW script as procedure library

Synopsis

    library FILE
    library FILE...

Description

Loads a CSHW script file and registers all procedures defined in it as
available commands. This allows you to create reusable procedure libraries
that can be loaded on demand.

Options

    FILE            Script file(s) containing procedure definitions.

Examples

    library utils.csh
        Load procedures from utils.csh.

    library lib/math.csh lib/string.csh
        Load multiple libraries.

    # File: mylib.csh
    proc greet(name)
        echo "Hello, $name!"
    endproc

    proc add(a, b)
        return ($a + $b)
    endproc

    # Then:
    library mylib.csh
    greet "World"
    set result=$(add 5 3)
        # result = 8

Exit status

    0       Success
    1       File not found
    2       Syntax error in library

Notes

Procedure Registration:
All 'proc' definitions in the file become available as commands
after loading. They're registered in the global procedure registry.

Load Order:
Libraries are loaded in order. Later definitions override earlier
ones with the same name.

Dependencies:
If a library depends on other libraries, load dependencies first:
    library base.csh
    library extended.csh   # May use procs from base.csh

vs source:
- library: Registers procedures for later use
- source: Executes commands immediately

Best Practices:
- Libraries should only contain procedure definitions
- Use descriptive procedure names
- Document procedures with comments
- Group related procedures in one file

Reloading:
Loading the same library again updates procedure definitions.

See also

source, proc, call

limit back to top ↑

display or set resource limits

Synopsis

    limit
    limit RESOURCE
    limit RESOURCE VALUE

Description

Displays or sets resource limits for the shell and its child processes.
Resource limits prevent processes from consuming excessive system resources.

Options

    RESOURCE        Resource to limit:
                    cputime     CPU time (seconds)
                    filesize    Maximum file size
                    datasize    Data segment size
                    stacksize   Stack size
                    coredumpsize Core dump size
                    memoryuse   Maximum memory
                    vmemoryuse  Virtual memory limit
                    descriptors Max open file descriptors

    VALUE           Limit value (with optional unit: k, m, g).
                    Use "unlimited" to remove limit.

Examples

    limit
        Display all current limits.

    limit filesize
        Display file size limit.

    limit filesize 100m
        Limit files to 100 megabytes.

    limit cputime 60
        Limit CPU time to 60 seconds.

    limit memoryuse 1g
        Limit memory to 1 gigabyte.

    limit filesize unlimited
        Remove file size limit.

Exit status

    0       Success
    1       Unknown resource
    2       Invalid value

Notes

Windows Implementation:
Windows doesn't have traditional UNIX resource limits. CSHW provides
limited support through Windows Job Objects where possible.

Soft vs Hard Limits:
- Soft limit: Current effective limit (can be raised)
- Hard limit: Maximum value for soft limit (needs privileges to raise)

Use Cases:
- Prevent runaway processes
- Test program behavior under constraints
- Protect system resources

Inherited Limits:
Child processes inherit limits from the shell.

See also

unlimit, nice, time

linecount back to top ↑

count lines in files (alias for lc)

Synopsis

    linecount FILE
    linecount [/s] [/q] PATTERN[,PATTERN,...]

Description

Alias for the lc command. Counts lines in files matching patterns.
See 'man lc' for complete documentation.

Examples

    linecount /s *.cpp,*.h
        Count all C++ source files recursively.

    linecount /q *.py
        Quietly count Python files (total only).

See also

lc

local back to top ↑

declare a variable in the current procedure's scope

Synopsis

    local <name> [= <value>]
    local <name1> <name2> ... <nameN>

Description

Declares one or more variable names as local to the current proc. The
variable disappears when the proc returns, restoring any global of the
same name that was previously visible.

Without an `= value`, the variable is declared but left empty (and
unset when the proc returns).

`local` outside a proc is a no-op for scoping purposes but still
performs any assignment.

Options

    <name>      Variable name. Multiple names can be declared in one
                `local` statement.
    <value>     Optional initial value (only when one name is given).

Examples

    proc square
        local result
        @ result = $1 * $1
        echo $result
    endproc
    set result = "global-result"
    square 5            # prints 25
    echo $result        # still "global-result" -- local didn't leak

    proc tmp
        local a b c
        set a = 1
        set b = 2
        set c = 3
        echo $a $b $c
    endproc

Exit status

    0       Always.

Notes

By default, `set` inside a proc already creates a local variable. The
explicit `local` is mainly useful for:
  - Documenting intent ("these names are scoped to this proc")
  - Declaring multiple locals at once
  - Reserving a name BEFORE any conditional assignment to it, so
    later `set name = ...` doesn't accidentally hit a global of the
    same name when the conditional path skips the first write.

The counterparts that REACH OUT of local scope are `share` (writes
through to the global namespace from a coroutine or proc) and the
explicit global-variable accessors.

See also

set, unset, share, declare, readonly

login back to top ↑

log in as a different user

Synopsis

    login [USERNAME]

Description

Initiates a login session as the specified user. This command is primarily
for compatibility with UNIX shells. On Windows, actual user switching
requires different mechanisms.

Options

    USERNAME        User to log in as.

Examples

    login
        Prompt for username and password.

    login administrator
        Log in as administrator.

Exit status

    0       Success
    1       Authentication failed
    2       User not found

Notes

Windows Limitations:
On Windows, true user switching within a console session has
limitations. For full user switching, use:
- Windows logoff/logon
- runas command
- Fast User Switching

runas Alternative:
For running commands as another user:
    runas /user:DOMAIN\username command

Security:
Credentials entered at the login prompt should be handled securely.
Be cautious on shared or untrusted systems.

See also

logout, sudo, whoami

logout back to top ↑

exit login shell

Synopsis

    logout

Description

Exits the current login shell session. Equivalent to 'exit' for login
shells. If this is the main shell window, it will close.

Examples

    logout
        Exit the shell session.

Exit status

    Does not return (shell exits).

Notes

Login vs Non-login:
- logout: For login shells (the first shell of a session)
- exit: Works for any shell

Typically, both commands work identically in CSHW.

Running Jobs:
If background jobs are running, you may receive a warning.
Use 'jobs' to check, then decide whether to wait or force exit.

See also

exit, login, jobs

ls back to top ↑

list directory contents (native, not a shell-out)

Synopsis

    ls [-l] [-a] [-R] [-t] [-r] [path ...]

Description

Lists files and subdirectories. Native implementation -- does NOT shell
out to an external ls.exe. With no path, lists the current directory.
A path may be a directory, a single file, or a wildcard pattern.

The (somewhat barebones) output format is one entry per line. Several
flags from GNU ls are accepted for familiarity but currently do not
change the output format -- the contract is "ls works the way scripts
expect for filename enumeration"; format flags are reserved for a
future expansion.

Options

    -R, --recursive
        Recurse into subdirectories.

    -l, -a, -t, -r
        Accepted (no syntax error) but do not currently affect the
        output format. -r in particular does NOT reverse the listing
        in this version -- use the output of ls as input to sort or
        a script-side reversal if you need ordering control.

    path...
        Directory path, single file path, or wildcard. Multiple paths
        are listed in order.

Examples

    ls
        List the current directory.

    ls *.cshw
        List only .cshw files in the current directory.

    ls C:\Users
        List a specific directory.

    ls -R src
        Recursive listing of src/ and all subdirectories.

Exit status

    0       Success.
    1       Path not found or wildcard matched nothing.

Notes

For richer formatting (sizes, dates, attributes), use `dir` -- the
Windows-style listing that CSHW ships with full column / sort support.
`ls` is for the Unix-style scripted enumeration use case.

See also

dir, find, glob, stat

man back to top ↑

display manual pages

Synopsis

    man [command]
    man -k keyword

Description

Displays comprehensive documentation for CSHW shell commands. Man pages
provide detailed information including syntax, options, examples, and
related commands.

Without arguments, lists all available manual pages.

Options

    command         Display the manual page for this command.

    -k keyword      Search manual pages for keyword in names and
                    descriptions.

Examples

    man
        List all available manual pages.

    man grep
        Display manual page for grep command.

    man cd
        Display manual page for cd command.

    man -k file
        Find commands related to "file".

    man -k network
        Find network-related commands.

Exit status

    0       Success
    1       Manual page not found

Notes

Man Page Format:
Manual pages are organized into sections:
    NAME        - Command name and brief description
    SYNOPSIS    - Usage syntax
    DESCRIPTION - Detailed explanation
    OPTIONS     - Available options and switches
    EXAMPLES    - Usage examples
    EXIT_STATUS - Return codes
    NOTES       - Additional information
    SEE_ALSO    - Related commands

Man Page Location:
Manual pages are stored as .man files. The shell searches for them
in this order:
1. Directory specified by CSHW_MAN environment variable
2. 'man' subdirectory alongside the shell executable

Comparison with Help:
- 'help' provides brief usage information
- 'man' provides comprehensive documentation

Creating Man Pages:
Man pages use a simple text format with section headers starting
with a period (.NAME, .SYNOPSIS, etc.).

Environment

    CSHW_MAN        Directory containing .man files. If set and the
                    directory exists, man pages are loaded from here
                    instead of the default location.

See also

help

md back to top ↑

make a directory (alias for mkdir)

Synopsis

    md <directory>

Description

`md` is identical to `mkdir`. See `man mkdir` for full documentation.

See also

mkdir, rd, rmdir

md5sum back to top ↑

compute MD5 message digest

Synopsis

    md5sum FILE...
    command | md5sum

Description

Computes and displays the MD5 hash (128-bit) of files. MD5 produces a
32-character hexadecimal fingerprint that changes if the file changes.

Options

    FILE            One or more files to hash.

    -c FILE         Check MD5 sums against a checksum file.

Examples

    md5sum file.txt
        Compute MD5 hash of file.txt.

    md5sum *.iso
        Hash all ISO files.

    md5sum -c checksums.md5
        Verify files against saved checksums.

    type data.bin | md5sum
        Hash piped input.

    md5sum file.zip > file.zip.md5
        Save checksum to file.

Exit status

    0       Success (or all checksums verified)
    1       Checksum mismatch (verify mode)
    2       File not found

Notes

Output Format:
    d41d8cd98f00b204e9800998ecf8427e  filename.txt

Security Warning:
MD5 is cryptographically broken and should NOT be used for security
purposes. Use SHA-256 or SHA-512 for security applications.
MD5 is still acceptable for:
- Non-security integrity checks
- Duplicate file detection
- Cache keys

Verification:
Create checksum files for later verification:
    md5sum *.zip > checksums.md5
    # Later...
    md5sum -c checksums.md5

See also

sha256sum, sha512sum, sha1sum

messagebox back to top ↑

show a Win32 MessageBox

Synopsis

    messagebox <text> [<title>] [/type:<flags>]
    msgbox     <text> [<title>] [/type:<flags>]

Description

Wraps the Win32 MessageBoxW API. Shows a modal message with one of the
standard button sets and icons; the button the user pressed lands in
$result as a number (the IDOK/IDCANCEL/IDYES/IDNO/etc. constant).

`messagebox` and `msgbox` are aliases for the same command.

Options

    <text>          The body of the message. Required.
    <title>         Window caption. Default: "cshw".
    /type:<flags>   Comma list of MB_* flags (case-insensitive). Common:
                      ok | okcancel | yesno | yesnocancel
                      info | warning | error | question
                      defbutton1 | defbutton2
                      systemmodal | topmost

Examples

    messagebox "Hello, world"
        Simple info box.

    msgbox "Continue?" "Confirm" /type:yesno,question
        Yes/No prompt with a question icon.

    msgbox "Are you sure?" "Warning" /type:yesnocancel,warning
        if ($result == 6) then echo "Yes" endif        # IDYES = 6
        if ($result == 7) then echo "No"  endif        # IDNO  = 7
        if ($result == 2) then echo "Cancel" endif     # IDCANCEL = 2

Exit status

    0       MessageBox returned (any button). Use $result for which.
    1       Bad arguments or UI thread unavailable.

Notes

$result button constants follow the Win32 IDOK / IDCANCEL etc. values:
    1=OK, 2=Cancel, 3=Abort, 4=Retry, 5=Ignore, 6=Yes, 7=No.

See also

passworddlg, about

mkdir back to top ↑

create directories

Synopsis

    mkdir DIRECTORY
    mkdir -p DIRECTORY
    md DIRECTORY

Description

Aliases: md

Creates one or more directories. Can create nested directory structures
in a single command with the -p option.

Options

    DIRECTORY       The directory path to create.

    -p, --parents   Create parent directories as needed. No error if
                    the directory already exists.

Examples

    mkdir newdir
        Create directory 'newdir' in current location.

    mkdir C:\Users\Me\Projects\NewProject
        Create directory with absolute path.

    mkdir -p deep/nested/directory/structure
        Create entire directory tree.

    mkdir "My Documents"
        Create directory with spaces in name.

    md backup
        Create 'backup' directory (md is alias for mkdir).

Exit status

    0       Success
    1       Parent directory doesn't exist (without -p)
    2       Access denied
    3       Directory already exists (without -p)

Notes

Parent Directories:
Without -p, all parent directories must already exist.
With -p, missing parents are created automatically.

Permissions:
New directories inherit permissions from the parent directory
on Windows.

Network Paths:
UNC paths (\\server\share\dir) are supported.

See also

rmdir, cd, dir

mklink back to top ↑

create symbolic and hard links

Synopsis

    mklink LINK TARGET
    mklink /D LINK TARGET
    mklink /H LINK TARGET
    mklink /J LINK TARGET

Description

Creates symbolic links, hard links, or directory junctions. Links allow
a file or directory to appear in multiple locations without copying data.

Options

    LINK            The name/path of the link to create.
    TARGET          The file or directory the link points to.

    Link types:
    (default)       Symbolic link to a file.
    /D              Symbolic link to a directory.
    /H              Hard link (file only, same volume).
    /J              Directory junction (directory only).

Examples

    mklink shortcut.txt C:\Path\To\original.txt
        Create symbolic link to a file.

    mklink /D ProjectLink C:\Projects\MainProject
        Create symbolic link to a directory.

    mklink /H hardlink.txt original.txt
        Create hard link (shares same data on disk).

    mklink /J DevFolder "C:\Users\Me\Development"
        Create directory junction.

Exit status

    0       Success
    1       Target not found
    2       Access denied (need Administrator for symlinks)
    3       Link already exists

Notes

Link Types Explained:

Symbolic Links (default, /D):
- Can point to files or directories
- Can span volumes (different drives)
- Require Administrator or Developer Mode
- Broken if target is deleted

Hard Links (/H):
- Files only (not directories)
- Same volume only
- Shares actual disk space
- File persists until ALL hard links deleted
- No special privileges required

Directory Junctions (/J):
- Directories only
- Same volume (usually)
- No special privileges required
- Similar to symlinks but older technology

Developer Mode:
On Windows 10+, enabling Developer Mode allows creating symbolic
links without Administrator privileges.

Administrator Required:
Creating symbolic links typically requires:
- Running as Administrator, OR
- Developer Mode enabled, OR
- SeCreateSymbolicLinkPrivilege

See also

copy, mv, del, attrib

msgbox back to top ↑

display a message box

Synopsis

    msgbox MESSAGE
    msgbox MESSAGE TITLE
    msgbox MESSAGE TITLE TYPE

Description

Displays a Windows message box with the specified message, optional title,
and optional button/icon configuration. The command waits for user response
and returns the button clicked.

Options

    MESSAGE         The message text to display.
    TITLE           Window title (default: "CSHW").
    TYPE            Button and icon configuration (numeric or named).

    Type values:
    0, ok           OK button only
    1, okcancel     OK and Cancel buttons
    2, abortretryignore
                    Abort, Retry, Ignore buttons
    3, yesnocancel  Yes, No, Cancel buttons
    4, yesno        Yes and No buttons
    5, retrycancel  Retry and Cancel buttons

    Add for icons:
    16, error       Error icon (X)
    32, question    Question mark icon (?)
    48, warning     Warning icon (!)
    64, info        Information icon (i)

Examples

    msgbox "Hello World"
        Simple message with OK button.

    msgbox "Operation complete" "Status"
        Message with custom title.

    msgbox "Delete this file?" "Confirm" yesno
        Yes/No confirmation dialog.

    msgbox "File not found" "Error" 16
        Error message with error icon.

    msgbox "Are you sure?" "Confirm" 36
        Yes/No (4) + Question icon (32).

    msgbox "Warning: Low disk space" "Warning" 48
        Warning with warning icon.

Exit status

    Returns button clicked:
    1       OK
    2       Cancel
    3       Abort
    4       Retry
    5       Ignore
    6       Yes
    7       No

Notes

Blocking:
The shell waits for the user to click a button before continuing.
This pauses script execution.

Return Value:
Use $? to check which button was clicked:
    msgbox "Continue?" "Confirm" yesno
    if ($? == 6)
        echo "User clicked Yes"
    endif

GUI Interaction:
Message boxes appear in the foreground and grab focus. They work
even when the shell is running in the background.

Scripting:
Useful for user confirmations, error notifications, and interactive
scripts that need user decisions.

See also

echo, read

mv back to top ↑

move or rename files

Synopsis

    mv SOURCE DEST
    mv SOURCE... DIRECTORY
    rename SOURCE DEST

Description

Aliases: rename

Moves files or directories to a new location, or renames them. If the
destination is an existing directory, files are moved into it.

Options

    SOURCE          File or directory to move.
    DEST            Destination path or new name.
    DIRECTORY       Target directory for multiple sources.

    /y              Suppress confirmation when overwriting.

Examples

    mv oldname.txt newname.txt
        Rename a file.

    mv file.txt Documents/
        Move file to Documents directory.

    mv *.txt backup/
        Move all text files to backup directory.

    mv project/ archived/project/
        Move entire directory.

    mv "My File.doc" "Renamed File.doc"
        Rename file with spaces.

    rename config.bak config.ini
        Rename using the rename alias.

Exit status

    0       Success
    1       Source not found
    2       Destination access denied
    3       Invalid arguments

Notes

Rename vs Move:
- Same directory: operation is a rename
- Different directory: operation is a move

Cross-Drive Moves:
Moving files between drives performs a copy-then-delete operation.
This is slower than same-drive moves.

Overwriting:
If the destination exists, it will be overwritten. Use with caution.

Directories:
Moving directories moves all contents. This is typically fast on the
same drive (just updates directory entries).

See also

copy, del, rm, rename

nice back to top ↑

run command with modified priority

Synopsis

    nice COMMAND [ARGS...]
    nice -n ADJUSTMENT COMMAND

Description

Runs a command with adjusted scheduling priority. Lower priority allows
other processes to get more CPU time, useful for background tasks.

Options

    COMMAND         Command to run.
    -n ADJUSTMENT   Priority adjustment (-20 to 19, default: 10).
                    Positive = lower priority (nicer)
                    Negative = higher priority (requires admin)

    Windows priority mapping:
    -20 to -10      High priority
    -9 to 0         Above normal
    1 to 9          Normal
    10 to 14        Below normal
    15 to 19        Idle/Low priority

Examples

    nice compress.exe largefile
        Run compression at lower priority.

    nice -n 15 backup.bat
        Run backup at very low priority.

    nice -n -5 important.exe
        Run at higher priority (needs admin).

    nice -n 19 longprocess.exe
        Run at lowest priority (idle).

Exit status

    Returns the exit code of the command.

Notes

CPU Scheduling:
Nice processes still run, just with lower priority. They get CPU
time when higher-priority processes don't need it.

Negative Values:
Increasing priority (negative nice) typically requires Administrator
privileges on Windows.

Windows Priorities:
Windows has fewer priority levels than UNIX. Nice values are mapped
to the closest Windows priority class.

Background Tasks:
Use nice for:
- Backups
- File compression
- Large builds
- Any task that shouldn't slow foreground work

Real-Time Priority:
Extremely high priorities can make the system unresponsive.
Use with caution.

See also

time, bg, jobs

nohup back to top ↑

run command immune to hangups

Synopsis

    nohup COMMAND [ARGS...]

Description

Runs a command that will continue running even if the shell is closed
or the user logs out. Output is redirected to nohup.out if not already
redirected.

Options

    COMMAND         Command to run.
    ARGS            Arguments for the command.

Examples

    nohup longprocess.exe
        Run process that survives shell exit.

    nohup backup.bat &
        Background nohup process.

    nohup script.bat > output.log 2>&1 &
        Nohup with explicit output redirection.

    nohup server.exe &
        Start server that persists after logout.

Exit status

    Returns immediately if backgrounded, otherwise returns command's
    exit code.

Notes

Output:
If stdout is a terminal, output redirects to nohup.out in the
current directory (or $HOME/nohup.out if that fails).

Combination with &:
nohup is typically combined with & to run in background:
    nohup command &

Signals:
nohup makes the process ignore SIGHUP (hangup signal), which is
sent when the terminal closes.

Use Cases:
- Long-running server processes
- Batch jobs that take hours
- Processes that should survive logout

Windows Equivalent:
On Windows, this is similar to starting a process detached from
the console, allowing it to continue after shell exit.

Checking Status:
Use 'processlist' or Task Manager to check if the process is
still running.

See also

bg, jobs, start

nop back to top ↑

no operation (alias for true)

Synopsis

    nop

Description

Does nothing; succeeds with $status = 0. Aliased at the dispatcher
to `true`. Documented alongside `true` and `false` on a single
page -- see `man true` for full details.

See also

true, false

notify back to top ↑

enable job completion notifications

Synopsis

    notify
    notify %JOBID

Description

Enables or displays asynchronous notification when background jobs complete.
When enabled, the shell immediately displays a message when a job finishes,
rather than waiting until the next prompt.

Options

    (no args)       Show notification settings.
    %JOBID          Enable notification for specific job.

Examples

    notify %1
        Enable notification for job 1.

    longprocess &
    notify %1
        Start background job and enable notification.

    # When job completes:
    # [1]    Done                    longprocess

Exit status

    0       Success
    1       No such job

Notes

Default Behavior:
By default, job completion is reported at the next prompt.
With notify, you're informed immediately.

Use Cases:
- Long-running background tasks
- Multiple background jobs
- When you need to know completion time precisely

Notification Format:
    [JOB#]  Status  Command
Example:
    [1]     Done    backup.bat

Per-Job Setting:
notify is set per job. Enable for jobs where you want immediate
notification.

See also

jobs, bg, fg

onintr back to top ↑

set interrupt handler

Synopsis

    onintr
    onintr LABEL
    onintr -

Description

Specifies what happens when an interrupt signal (Ctrl+C) is received.
Can ignore interrupts, handle them with a label, or restore default behavior.

Options

    (no args)       Restore default interrupt handling.
    LABEL           Jump to LABEL when interrupted.
    -               Ignore interrupts (disable Ctrl+C).

Examples

    onintr cleanup
        # ... code that might be interrupted ...
        exit 0
    cleanup:
        echo "Cleaning up..."
        rm -f temp_*
        exit 1
        # When Ctrl+C pressed, jumps to 'cleanup'

    onintr -
        # Critical section - ignore interrupts
        important_operation
    onintr
        # Restore normal interrupt handling

Exit status

    0       Success

Notes

Use Cases:
- Clean up temporary files on interrupt
- Save state before exiting
- Prevent interruption during critical operations

Label Handling:
When interrupted, the shell jumps to the specified label and
continues execution from there.

Nested Handlers:
Save and restore handlers for nested operations:
    onintr outer_handler
    # ... code ...
    onintr inner_handler
    # ... critical code ...
    onintr outer_handler
    # ... more code ...

Critical Sections:
Use 'onintr -' to prevent interruption during operations that
must complete atomically.

See also

exit, trap

password back to top ↑

read a password from the console (no echo)

Synopsis

    password [/prompt:<text>] [/confirm]

Description

Reads a line of input from the console with echo suppressed and stores
it in $result. The console-mode counterpart of `passworddlg`. Suitable
for scripts that need a password and are running without a GUI (over
SSH, in CI, etc.).

Options

    /prompt:<text>
        Prompt string. Default: "Password: ".
    /confirm
        Prompt twice and only return success if both entries match.

Examples

    password
        Read a password silently. $result holds the value.

    password /prompt:"SSH passphrase: "
        Custom prompt text.

    password /confirm
        Read twice, must match. Useful for setting a new password.

Exit status

    0       Password read successfully.
    1       User cancelled (Ctrl-C), or /confirm fields differ.

Notes

Echo is suppressed via the console mode flags; only newline / backspace
appear visibly while the user is typing.

See also

passworddlg

passworddlg back to top ↑

prompt for a password using a modal dialog

Synopsis

    passworddlg [/title:<text>] [/prompt:<text>] [/confirm]

Description

Shows a modal password-entry dialog and stores the entered password
in $result. With /confirm, presents a second edit field and only
returns success when both fields match.

The dialog runs on the UI thread (with fallback to a calling-thread
modal pump in non-interactive mode) and routes activation correctly
so the first edit field gets focus on open.

Options

    /title:<text>
        Window title. Default: "Password".
    /prompt:<text>
        Prompt label above the edit field. Default: "Enter password:".
    /confirm
        Add a second edit field and require both entries to match.

Examples

    passworddlg
        Simple password prompt. $result has the password on OK.

    passworddlg /title:"Backup" /prompt:"Backup passphrase:"
        Custom title and prompt.

    passworddlg /confirm /prompt:"New password:"
        Two-field confirm form. Fails if the two fields don't match.

Exit status

    0       User clicked OK; $result holds the password.
    1       User cancelled, or /confirm fields didn't match.

Notes

$result is set even on cancel (to an empty string) -- check $status
to distinguish OK from cancel rather than testing $result for empty.

The console-mode equivalent (no GUI) is the `password` command.

See also

password, about, splash

peinfo back to top ↑

display PE file information

Synopsis

    peinfo FILE
    peinfo [options] FILE

Description

Displays detailed information about Windows Portable Executable (PE) files,
including EXE, DLL, SYS, and other PE formats. Shows headers, sections,
imports, exports, and other metadata.

Options

    FILE            PE file to analyze.

    -h, --headers   Show PE headers only.
    -s, --sections  Show section information.
    -i, --imports   Show imported functions.
    -e, --exports   Show exported functions.
    -r, --resources Show resources.
    -a, --all       Show all information.

Examples

    peinfo program.exe
        Display basic PE information.

    peinfo -a C:\Windows\System32\kernel32.dll
        Full analysis of kernel32.

    peinfo -i malware.exe
        Show imports (useful for analysis).

    peinfo -e library.dll
        Show exported functions.

    peinfo -s driver.sys
        Show section layout.

Exit status

    0       Success
    1       File not found
    2       Not a valid PE file

Notes

Information Displayed:
- Machine type (x86, x64, ARM)
- Subsystem (GUI, Console, Driver)
- Entry point address
- Section table (code, data, resources)
- Import table (DLLs and functions used)
- Export table (functions provided)
- Timestamps, checksums

Security Analysis:
peinfo is valuable for malware analysis:
- Check imports for suspicious APIs
- Examine section characteristics
- Verify digital signatures
- Detect packers/obfuscation

PE Format:
The PE format is used by Windows executables, DLLs, drivers, and
other binary files. Understanding PE structure helps with debugging
and security analysis.

Packed Files:
Packed/encrypted executables may show unusual characteristics:
- Few imports
- High entropy sections
- Unusual section names

See also

file, strings, hexdump

popd back to top ↑

pop directory from stack and change to it

Synopsis

    popd

Description

Removes the top directory from the directory stack and changes to that
directory. Used in conjunction with pushd to navigate back to previously
saved locations.

Examples

    pushd C:\Projects
    # work in Projects...
    popd
        Return to the directory where pushd was issued.

    pushd dir1
    pushd dir2
    popd
        Return to dir1.
    popd
        Return to original directory.

Exit status

    0       Success
    1       Directory stack is empty
    2       Cannot change to directory (deleted or inaccessible)

Notes

Empty Stack:
If the directory stack is empty, popd will display an error message.
Use 'dirs' to check the stack contents.

Deleted Directories:
If the directory on the stack no longer exists (was deleted while
you were elsewhere), popd will fail.

See also

pushd, dirs, cd

postmessage back to top ↑

post a Win32 message to a window's queue (async)

Synopsis

    postmessage <hwnd> <msg> [<wParam> [<lParam>]]

Description

Calls PostMessageW(hwnd, msg, wParam, lParam). The message is appended
to the target window's thread message queue and the call returns
immediately. $result is 1 on success, 0 on failure.

`msg` accepts the same symbolic-WM_* names and numeric forms as
`sendmessage`.

Options

    <hwnd>      Target HWND in hex or decimal. Must satisfy IsWindow().
    <msg>       Symbolic (WM_CLOSE, ...) or numeric.
    <wParam>    WPARAM. Default 0.
    <lParam>    LPARAM. Default 0.

Examples

    # Fire-and-forget close request:
    postmessage $w WM_CLOSE

    # Post a custom WM_USER notification (plugins may translate this
    # into a script-event via DispatchScriptEvent):
    postmessage $w WM_USER 1 0

Exit status

    0       PostMessage returned TRUE; $result = 1.
    1       PostMessage returned FALSE; $result = 0. Use $? for the
            Windows error code.

Notes

Use `sendmessage` when the message handler needs to run BEFORE the
script continues (e.g., the WM_CLOSE veto path). Use `postmessage`
when you want the script to keep running without waiting.

See also

sendmessage, bindevent

printenv back to top ↑

print environment variables

Synopsis

    printenv
    printenv NAME
    printenv NAME...

Description

Prints the values of environment variables. Without arguments, prints
all variables. With arguments, prints only the specified variables.

Options

    NAME            Specific variable(s) to print.

Examples

    printenv
        Print all environment variables.

    printenv PATH
        Print only PATH variable.

    printenv PATH HOME TEMP
        Print multiple variables.

    printenv USERNAME
        Print current username.

    printenv NONEXISTENT
        # Outputs nothing (no error)

Exit status

    0       Success (variable found or all printed)
    1       Variable not found (when specific name given)

Notes

Output Format:
When printing a specific variable, only the value is shown (no NAME=).
When printing all, format is NAME=VALUE.

Scripts:
Useful in scripts to get environment values:
    set mypath=$(printenv PATH)

Comparison:
- printenv NAME: Prints value only
- echo %NAME%: Also prints value (Windows syntax)
- env: Prints NAME=VALUE format

See also

env, setenv, set

printf back to top ↑

format and print arguments

Synopsis

    printf <format> [argument ...]

Description

Print the arguments under the control of <format>, in the style of the
C printf function. Unlike echo, printf adds no trailing newline -- the
format string controls the output exactly.

The format string may contain:

  Literal text, printed as-is.

  Backslash escapes:  \n  \t  \r  \a  \b  \f  \v  \\

  Conversion specifications, each introduced by % and consuming one
  argument:
    %s               string
    %d  %i           signed integer
    %u  %o  %x  %X   unsigned, octal, lower/upper hexadecimal
    %c               the first character of the argument
    %f %e %E %g %G   floating point
    %%               a literal percent sign
  Flags (- + space # 0), a field width, and a .precision may appear
  between the % and the conversion -- e.g. %-10s, %05d, %.2f.

If there are more arguments than the format consumes, the format is
reused until every argument has been printed. Missing arguments are
treated as an empty string or zero.

Examples

    printf '%s\n' hello
        Prints hello, followed by a newline.

    printf '%-8s%5d\n' item 42
        Prints the name left-justified in 8 columns, the number in 5.

    printf '%.2f\n' 3.14159
        Prints: 3.14

    printf '%s\n' a b c
        Prints a, b and c on three lines -- the format is reused.

Exit status

Zero on success. printf with no format argument is a usage error.

See also

echo, eval

processlist back to top ↑

list running processes

Synopsis

    processlist
    processlist [options]
    ps

Description

Displays a list of all processes currently running on the system. Shows
process ID (PID), parent process ID (PPID), process name, thread count,
and memory usage.

This command is essential for system monitoring, finding process IDs
for the kill command, and identifying resource-heavy processes.

Options

    /v, --verbose   Show additional details including module path.

    /s, --sort NAME Sort by: name, pid, memory, threads.

    /f, --filter    Filter by process name pattern.

Examples

    processlist
        List all running processes.

    processlist /v
        Verbose listing with full paths.

    processlist | grep chrome
        Find Chrome-related processes.

    processlist /s memory
        Sort processes by memory usage.

Exit status

    0       Success

Notes

Information Displayed:
- PID: Process ID (unique identifier)
- PPID: Parent Process ID (who started this process)
- Name: Executable name
- Threads: Number of threads in the process
- Memory: Working set size (RAM usage)

Administrator Privileges:
Some system processes may show limited information unless running as
Administrator.

Process Relationships:
The PPID column shows parent-child relationships between processes.
A process with PPID 0 is typically a system process.

Performance:
On systems with many processes, the command may take a moment to
enumerate all processes.

See also

kill, jobs, top, uptime

progressdlg back to top ↑

show and drive a modeless progress dialog

Synopsis

    progressdlg <subcommand> [args]

Description

Shows a modeless progress-bar dialog and updates its state from the
script. The first state-modifying subcommand creates the dialog;
`progressdlg end` dismisses it.

Bound click handlers fire as coroutines, so the UI thread stays
responsive. Out-of-range positions / increments are clamped to the
current range rather than wrapping or erroring.

Options

    setcaption <text>
        Set the window title.
    setstatus <text>
        Set the status line below the progress bar (e.g. "12 of 100").
    setbarrange <min> <max>
        Set the bar's range. Current position clamps into the new range.
    setbarpos <n>
        Jump to an absolute position. Clamped to [min, max].
    incrementbar [<n>]
        Add n to the position (default +1; negative ok; clamped).
    button <text>
        Set the button label AND make the button visible.
    showbutton YES|NO
        Show or hide the button. `showbutton:YES` colon form also accepted.
    onbuttonclick <proc>
        Bind a script proc to the button click. The proc fires on a
        coroutine thread; the UI thread is not blocked.
    onbuttonclick cancel
        Shortcut: clicking the button destroys the dialog.
        `onbuttonclick:cancel` colon form also accepted.
    hide
        ShowWindow SW_HIDE -- the window is hidden but state is kept.
    show
        ShowWindow SW_SHOW. Creates the dialog if it doesn't exist yet.
    gethwnd
        Set $result to the dialog's HWND (0x0 when none is showing).
    end
        Destroy the dialog.

Examples

    progressdlg setcaption "Downloading..."
    progressdlg setbarrange 0 100
    progressdlg button "Cancel"
    progressdlg onbuttonclick:cancel
    foreach i (0 1 2 3 4 5 6 7 8 9)
        progressdlg setstatus "${i}0 of 100"
        progressdlg incrementbar 10
        sleep 0.5
    end
    progressdlg end

    # Bind a custom click handler instead of just dismissing:
    proc on_cancel
        share user_cancelled = 1
        progressdlg end
    endproc
    progressdlg button "Stop"
    progressdlg onbuttonclick on_cancel

Exit status

    0       Success.
    1       Bad subcommand, parse error, or UI thread unavailable.

Notes

Only one progress dialog exists at a time. Calling state-modifying
subcommands without an existing dialog auto-creates it; subsequent
calls update the live dialog via SendMessage so script-side updates
from any thread are safe.

Bound click procs run as coroutines (CShellCoroutineManager). They can
call back into progressdlg (e.g., setstatus) from inside the proc
without deadlocking the UI thread.

See also

splash, endsplash, passworddlg, about

prompt back to top ↑

set or display command prompt

Synopsis

    prompt
    prompt FORMAT

Description

Sets or displays the shell command prompt. The prompt appears before
each command you enter, typically showing the current directory and
other useful information.

Options

    FORMAT          Prompt format string with special codes.

    Special codes:
    $P              Current directory path
    $G              Greater-than sign (>)
    $L              Less-than sign (<)
    $N              Current drive letter
    $D              Current date
    $T              Current time
    $S              Space
    $$              Dollar sign
    $Q              Equals sign (=)
    $H              Backspace
    $E              Escape character
    $_              Newline

Examples

    prompt
        Display current prompt format.

    prompt $P$G
        Standard prompt: "C:\Users\Me>"

    prompt [$T] $P$G
        Add time: "[14:30:25] C:\Users\Me>"

    prompt $N:$G
        Drive letter only: "C:>"

    prompt $P$_$G
        Directory on one line, > on next.

    prompt cshw $P$G
        Add prefix: "cshw C:\Users\Me>"

    prompt [$D $T]$_$P$G
        Date/time on first line, path on second.

Exit status

    0       Success

Notes

Default Prompt:
The default prompt is typically "$P$G" showing the current path
followed by ">".

Customization:
The prompt can include any text along with special codes. Use
$_ for multi-line prompts.

Colors:
Color codes may be supported using ANSI escape sequences with $E.

Persistence:
Prompt settings are not saved between sessions. Add your prompt
command to your startup script for persistence.

See also

cd, pwd, set

pushd back to top ↑

push directory onto stack and change to it

Synopsis

    pushd DIRECTORY
    pushd

Description

Saves the current directory on a stack and then changes to the specified
directory. This allows you to easily return to your previous location
using popd.

The directory stack enables efficient navigation between multiple
working directories without losing track of where you've been.

Options

    DIRECTORY       The directory to change to.

    Without arguments, pushd swaps the top two directories on the stack.

Examples

    pushd C:\Projects
        Save current directory and change to C:\Projects.

    pushd src
        Save current directory and change to src subdirectory.

    pushd
        Swap current directory with top of stack.

    pushd D:\Backup
    # ... do work in D:\Backup ...
    popd
        Return to original directory.

Exit status

    0       Success
    1       Directory not found
    2       Invalid argument

Notes

Stack Operations:
- pushd adds to the stack and changes directory
- popd removes from the stack and changes back
- dirs shows the current stack

Multiple Pushes:
You can push multiple directories onto the stack:
    pushd dir1
    pushd dir2
    pushd dir3
    # Now stack has 3 entries

The most recent push is at the top and will be the first restored
by popd.

Use Cases:
- Temporarily work in another directory
- Navigate between related project directories
- Keep track of multiple working locations

See also

popd, dirs, cd

pwd back to top ↑

print working directory

Synopsis

    pwd

Description

Prints the absolute path of the current working directory. This is the
directory where relative paths are resolved from and where commands
operate by default.

Examples

    pwd
        Display current directory path.

    set currentdir=$(pwd)
        Store current directory in a variable.

Exit status

    0       Success (always)

Notes

The current directory is also available in the $: special variable:
    echo $:

pwd is equivalent to 'cd' with no arguments.

See also

cd, pushd, popd, dirs

rcl back to top ↑

register command library (load plugin DLL)

Synopsis

    rcl PATH
    rcl PATH PREFIX
    rcl PATH PREFIX /prefixonly
    registercmdlib PATH [PREFIX] [/prefixonly]

Description

Loads a command library DLL and registers its commands with the shell.
Command libraries are DLL plugins that extend cshw with custom commands.

The DLL must export a RegisterCommandLibrary function that returns
command definitions. Each command includes init, execute, and help
functions following the CSHW plugin API.

Commands can be accessed with or without the namespace prefix:
    mylib:mycmd    Explicit namespace (always works)
    mycmd          Direct access (if no conflict)

Plugins can shadow intrinsic commands. When a plugin command has the
same name as a built-in command, the plugin version takes precedence.
The original command is restored when the library is unloaded.

Options

    PATH            Path to the DLL containing command definitions.
    PREFIX          Optional namespace prefix for commands.
    /prefixonly     Commands only accessible with prefix.
    /p              Short form of /prefixonly.

Examples

    rcl C:\Plugins\mylib.dll
        Load plugin with auto-detected prefix.

    rcl C:\Plugins\mylib.dll tools
        Load plugin with "tools" prefix.
        Commands available as: tools:cmd or cmd

    rcl C:\Plugins\mylib.dll tools /prefixonly
        Load with prefix required.
        Commands only available as: tools:cmd

    rcl "C:\Program Files\MyApp\plugin.dll" myapp
        Load plugin with spaces in path.

Exit status

    0       Success
    1       DLL not found
    2       Invalid plugin format (missing RegisterCommandLibrary)
    3       API version mismatch
    4       Registration failed
    5       Command conflicts with existing plugin command

Configuration

Command libraries can be preloaded automatically from:

INI File (cshw.ini next to cshw.exe):
    [CommandLibraries]
    C:\Plugins\mylib.dll=mylib
    C:\Plugins\tools.dll=tools:prefixonly

Registry:
    HKEY_CURRENT_USER\Software\cshw\CommandLibraries
    Value name: DLL path
    Value data: prefix

Environment Variable:
    CSHW_CMDLIBS=C:\lib1.dll;C:\lib2.dll:prefix2

Plugin Api

Plugin DLLs must export these functions:

    BOOL RegisterCommandLibrary(CShwPluginLibraryInfo** ppInfo)
        Called when plugin is loaded. Returns library info and
        command definitions.

    void UnregisterCommandLibrary(void)
        Called when plugin is unloaded. Perform cleanup here.

See CShellPluginAPI.h for the complete API specification.

Notes

Plugin Development:
Include CShellPluginAPI.h from the cshw SDK to develop plugins.
The header contains structures, typedefs, and convenience macros.

Shadowing:
Plugins can override built-in commands with a warning. This allows
extending or replacing default behavior. Originals are restored
when the library is unloaded.

Security:
Only load DLLs you trust. Plugin DLLs have full access to the
shell process and can execute arbitrary code.

Architecture:
32-bit plugins require 32-bit cshw.
64-bit plugins require 64-bit cshw.

See also

urcl, cmdliblist, dllimport, library

rd back to top ↑

remove a directory (alias for rmdir)

Synopsis

    rd <directory>

Description

`rd` is identical to `rmdir`. See `man rmdir` for full documentation.

See also

rmdir, md, mkdir, rm

readfile back to top ↑

read a file's contents into a shell variable

Synopsis

    readfile <variable> <file>

Description

readfile reads the entire contents of <file> and stores them in the
shell variable <variable>.

It is the direct way to get a file into a variable. The csh idiom
`set v = \`cat file\`` also works, but backtick substitution strips the
file's trailing newline and spawns a command; readfile keeps the exact
content (trailing newline included) and runs in-process.

The file is read as text -- CRLF line endings are normalized to LF. For
binary files, use fileblob instead.

Examples

    readfile notes settings.txt
        Load settings.txt into $notes.

    readfile body message.txt
        echo "$body"

Exit status

0 on success; non-zero if the file cannot be opened.

See also

set, cat, fileblob

readonly back to top ↑

make a variable read-only

Synopsis

    readonly <name> [= <value>]
    readonly <name1> <name2> ... <nameN>

Description

Marks one or more variables as read-only. Once a variable is read-only,
further `set` / `share` / `unset` attempts against it fail with a
diagnostic and a non-zero $status. The variable's value can still be
read normally.

The read-only flag is per-variable, not per-namespace -- a local
read-only variable disappears when its proc returns, freeing the name
for re-use at the next outer scope.

Options

    <name>      Variable name(s) to mark read-only.
    <value>     Optional value to assign at the same time (only when
                one name is given).

Examples

    readonly MAX_RETRIES = 5
    set MAX_RETRIES = 99
        # ERROR: MAX_RETRIES is read-only

    readonly version = "1.0.0-alpha.1"
    echo "running $version"

    proc enforce_constants
        readonly tax_rate = 0.07
        # ...calculations using $tax_rate...
        # tax_rate disappears (and is re-assignable) when this proc returns.
    endproc

Exit status

    0       Variable(s) marked read-only.
    1       Variable not found, or already read-only with a conflicting
            re-declaration.

Notes

Once set, the read-only flag cannot be removed in this session. The
intent is to lock down constants and configuration values that the
rest of the script must treat as invariants.

See also

set, unset, local, share, declare

realpath back to top ↑

print the absolute, canonical form of a path

Synopsis

    realpath <path>

Description

Print <path> in absolute, canonical form. "." and ".." components are
resolved, and a relative path is made absolute against the current
working directory. Forward slashes are normalized to backslashes.

realpath is a pure path computation -- it does not consult the
filesystem and <path> does not need to exist. This makes it safe for
building up paths that you are about to create.

Examples

    realpath .
        Prints the current working directory.

    realpath ..
        Prints the parent of the current directory.

    realpath a/b/../c
        Prints <cwd>\a\c -- the ".." cancels "b".

Exit status

Zero on success. realpath with no path argument is a usage error; a
non-zero status is also returned if the path cannot be resolved.

See also

basename, dirname, pwd

registercmdlib back to top ↑

register command library (load plugin DLL)

Synopsis

    registercmdlib PATH [PREFIX] [/prefixonly]
    rcl PATH [PREFIX] [/prefixonly]

Description

Alias for rcl. See 'man rcl' for full documentation.

See also

rcl, urcl, cmdliblist

registry back to top ↑

in-shell Windows Registry operations

Synopsis

    registry <op> KEY [options]

Description

Native Windows Registry access from cshw scripts. Named `registry`
rather than `reg` so the system reg.exe stays reachable from cshw
via PATH lookup. Switch syntax uses CSHW's colon form (e.g.,
`/v:NAME`) rather than reg.exe's space-separated form. Both
`--long-form` and `-short` switches are accepted.

Options

  Operations:

    query   KEY [/v:VALUE] [/s] [/q]
        Display values and subkeys. /v: limits to one value;
        /s recurses; /q makes a missing key a silent zero-result
        success.

    get     KEY /v:VALUE [/q]
        Pipe-friendly read -- prints just the data, no header or
        type column. Suitable for `set foo = `registry get ...``.

    list    KEY [/q]              (alias: ls)
        Print just the subkey names, one per line. Lighter than
        tree, more focused than query for foreach loops.

    add     KEY /v:VALUE /t:TYPE /d:DATA [/f] [/idempotent]
        Create the key if missing and set VALUE. Repeat /d: for
        REG_MULTI_SZ lines. /f skips overwrite confirmation.

    delete  KEY [/v:VALUE] [/f]
        Delete a value (with /v:) or the entire key (without).

    copy    SRCKEY DSTKEY [/s] [/f]
        Copy a key (and optionally subkeys) to another path.

    tree    KEY [/q]
        Recursively print the subkey tree under KEY.

    export  KEY FILE [/q]
        Write the subtree to a .reg file.

    import  FILE [/f]
        Apply a .reg file to the registry.

  Key prefixes:
    HKLM\... | HKEY_LOCAL_MACHINE\...
    HKCU\... | HKEY_CURRENT_USER\...
    HKCR\... | HKEY_CLASSES_ROOT\...
    HKU\...  | HKEY_USERS\...

  Common types for /t:
    REG_SZ, REG_EXPAND_SZ, REG_MULTI_SZ, REG_DWORD, REG_QWORD,
    REG_BINARY, REG_NONE

Examples

    registry query "HKLM\SOFTWARE\Tropibyte\cshw"

    set ver = `registry get "HKLM\SOFTWARE\Tropibyte\cshw" /v:Version`
    echo "installed cshw version: $ver"

    registry add "HKCU\Software\Tropibyte\cshw" /v:Theme /t:REG_SZ /d:dark /f

    registry list "HKLM\SOFTWARE\Tropibyte"

    registry delete "HKCU\Software\Tropibyte\cshw" /v:Theme /f

    registry export "HKLM\SOFTWARE\Tropibyte" cshw-config.reg

Exit status

    0       Operation succeeded (or /q used on a missing key).
    1       Bad arguments or operation-specific failure (see stderr).

Notes

HKLM writes typically require admin. /q (--quiet) is useful in
scripts to avoid noisy failures when a key is expected-not-present.

See also

reg, dir, where, install

rehash back to top ↑

rebuild command lookup hash table

Synopsis

    rehash

Description

Rebuilds the internal hash table that caches command locations. The shell
maintains a hash of command names to paths for faster lookup. Use rehash
after installing new programs to make them immediately available.

Examples

    rehash
        Rebuild command hash table.

    # After installing a new program:
    # 1. Install program (adds to PATH)
    # 2. rehash
    # 3. New program is now findable

Exit status

    0       Success

Notes

When to Use:
Rehash is needed when:
- New programs are installed to PATH directories
- PATH is modified
- Programs are added/removed from PATH directories

Automatic Rehash:
The shell may rehash automatically in some cases, but explicit
rehash ensures the cache is current.

Performance:
The hash table makes command lookups faster by avoiding repeated
PATH searches. rehash rebuilds this optimization.

Shell Compatibility:
rehash is traditional in csh/tcsh. Other shells use different
mechanisms (bash: hash -r).

See also

hashstat, unhash, which

rename back to top ↑

rename or move a file (alias for mv)

Synopsis

    rename <source> <dest>

Description

`rename` is identical to `mv`. See `man mv` for full documentation.

See also

mv, cp, copy

repeat back to top ↑

run a command a given number of times

Synopsis

    repeat count command [argument ...]

Description

Run a single command, with its arguments, count times in the current
shell. The count must be the first argument and must be an integer.

A count of zero or a negative number runs the command zero times --
a successful no-op.

repeat runs one command. It is not a loop construct: for anything
needing a loop body of multiple statements, use while, foreach, or
loop instead.

Arguments

    count
        Integer number of repetitions.
    command [argument ...]
        The command to run, with any arguments.

Examples

    repeat 3 echo hi
        Prints "hi" three times.

    repeat 5 mkdir -p scratch
        Runs the mkdir five times (harmless after the first).

    repeat 0 echo nope
        Runs nothing; succeeds.

Exit status

    0       The count parsed and the command ran (or count <= 0).
    1       Missing arguments, or the count is not a valid integer.

Notes

The command runs in the current shell, so state changes it makes
persist between iterations and after repeat returns.

See also

while, foreach, loop, eval

rev back to top ↑

reverse lines character by character

Synopsis

    rev [FILE]
    command | rev

Description

Reverses the order of characters in each line. Reads from files or
standard input, outputting each line with characters in reverse order.

Options

    FILE            File to process (default: stdin).

Examples

    echo "hello" | rev
        Output: olleh

    rev file.txt
        Reverse each line in file.

    echo "12345" | rev
        Output: 54321

    echo "Was it a car or a cat I saw" | rev
        Reveal palindrome patterns.

    dir /b | rev | sort | rev
        Sort by reversed names (by extension effectively).

Exit status

    0       Success
    1       File not found
    2       Read error

Notes

Line by Line:
Each line is reversed independently. The order of lines is preserved.

Use Cases:
- Checking palindromes
- Reversing text for effects
- Creative sorting tricks
- Text manipulation puzzles

Unicode:
Works with Unicode characters, reversing by character not by byte.

Comparison:
- rev: Reverses characters within lines
- tac: Reverses order of lines (not available in CSHW)

See also

tr, cut, sort

rm back to top ↑

remove files

Synopsis

    rm <file> [<file> ...]
    rm /secure  <file> [<file> ...]
    rm /recycle <file> [<file> ...]
    rm --recycle <file> [<file> ...]

Description

Deletes one or more files. Registered as both 'rm' and 'del' (they share
a single handler), so either name works.

By default rm permanently deletes the named files. Use /recycle (or
--recycle) to send them to the Recycle Bin (recoverable), or /secure
(or --secure) to overwrite the file contents with zeros before deletion.

cshw accepts both Windows-style switches and common Unix aliases. The
shell's switch-extraction step rejoins lexer-split "-X" / "--X"
sequences before handlers see them, so for argument purposes /secure
and --secure are interchangeable.

Options

    <file>          File(s) to delete. The handler does not expand
                    wildcards itself; use the glob command for that:
                        rm `glob *.bak`

    /secure, --secure
                    Overwrite the file contents with zeros (size-
                    preserving in-place write, then close, then
                    DeleteFile). Useful when you want to make recovery
                    on local storage difficult. Mutually exclusive
                    with /recycle.

    /recycle, --recycle
                    Send to the Recycle Bin instead of permanently
                    deleting. The operation FAILS rather than silently
                    falling back to permanent delete when the bin is
                    unavailable -- see NOTES on rmdir(1) for the full
                    list of refusal cases.

Examples

    rm temp.txt
        Permanently delete temp.txt.

    rm /recycle bigfile.iso
        Send bigfile.iso to the Recycle Bin (or fail if it can't fit).

    rm --recycle bigfile.iso
        Same, Unix-style spelling.

    rm /secure passwords.txt
        Overwrite passwords.txt with zeros, then delete it.

    rm a.txt b.txt c.txt
        Delete several files in one command.

Exit status

    0       All files deleted successfully.
    Other   At least one delete failed. Per-file errors go to stderr.

Notes

This command does not recurse into directories -- use rmdir for that.

/secure is best-effort: it writes zeros to the file's currently allocated
clusters, but offers no guarantee against journaling, snapshots, SSD
wear-leveling, or copies that already left the disk. For real
sanitization, use a tool that addresses the storage layer directly.

See also

del, rmdir, glob

rmdir back to top ↑

remove directories

Synopsis

    rmdir <dir>
    rmdir /S [/Q] <dir>
    rmdir -r [-q] <dir>
    rmdir /recycle <dir>
    rd ...

Description

Aliases: rd

Removes (deletes) a directory. By default, only empty directories can be
removed. Use /S (or -r / --recursive) to recursively delete a non-empty
tree, or /recycle to send the directory (empty or not) to the Recycle Bin.

cshw accepts both Windows-style switches (/S, /Q, /recycle) and the
common Unix aliases (-r, --recursive, -q, --quiet, --recycle). Behind
the scenes, the shell's switch-extraction step rejoins lexer-split
"-X" / "--X" sequences before handlers see them, so for argument
purposes /S and -r are interchangeable.

Options

    <dir>           The directory to remove.

    /S, -r, --recursive
                    Recursively delete the directory and all of its
                    contents. Permanent -- no confirmation, no Recycle
                    Bin involvement. Use with care.

    /Q, -q, --quiet
                    Suppress per-file error reporting during a recursive
                    delete. Has no effect without -r/-s.

    /recycle, --recycle
                    Send the directory to the Recycle Bin instead of
                    permanently deleting it. Handles empty and non-empty
                    directories on its own; /S is unnecessary (and
                    silently a no-op when paired). The operation FAILS
                    rather than silently falling back to permanent delete
                    when the bin is unavailable -- see NOTES.

Examples

    rmdir emptydir
        Remove an empty directory.

    rmdir /S /Q oldproject
        Permanently delete a directory tree, suppressing per-file errors.

    rmdir -r --quiet oldproject
        Same as above using Unix-style switches.

    rmdir /recycle scratch
        Send the scratch directory (empty or not) to the Recycle Bin.

    rd "Temporary Files"
        Remove a directory whose name contains a space.

Exit status

    0       Success.
    Other   The command's $? value is the underlying Windows error code
            from RemoveDirectoryW or, for /recycle, from IFileOperation.

Notes

Permanent deletion:
    /S deletes content immediately and irrevocably. There is no
    confirmation prompt. Double-check the path before pressing Enter.

Recycle Bin caveats:
    /recycle uses the Vista+ IFileOperation API with the
    FOFX_RECYCLEONDELETE flag set. That flag tells Windows to FAIL the
    operation rather than silently fall back to a permanent delete when
    the Recycle Bin can't accept the item:
      - the path is on a network/UNC share (which has no bin),
      - the item is larger than the bin's per-drive size budget,
      - the drive is removable and has no per-drive bin enabled,
      - or the bin is disabled by group policy on this drive.
    In all of those cases, the file/folder is left in place and the
    command returns failure. This matches the safety expectation of
    /recycle: "recoverable, or refuse."

In-use files:
    A recursive delete may fail partway through if any file in the tree
    is held open by another process. /Q suppresses per-file noise but
    does not change the behavior.

See also

mkdir, del, rm

rundllproc back to top ↑

call an exported function from a DLL

Synopsis

    rundllproc [options] DLL FUNCTION [ARGS...]
    rundllproc [options] ALIAS FUNCTION [ARGS...]
    rundllproc [options] DLL #ORDINAL [ARGS...]

Description

Loads a DLL (or reuses one previously preloaded with dllimport), resolves
an exported function by name or ordinal, marshals up to 16 typed arguments
and invokes it under SEH protection. The raw return value is available
in %result; the printed Result line is formatted per --ret.

Options

    -v, --verbose      Verbose output: handles, function address, arg shapes.
    -r, --rundll32     Use the rundll32 entrypoint signature instead
                       (HWND, HINSTANCE, LPSTR cmdLine, int nCmdShow).
                       Args are joined into a single ANSI cmdLine.
    --ret:TYPE         Format the return value as TYPE:
                       int       (default) decimal + hex
                       hex       hex only
                       bool      TRUE / FALSE
                       hresult   HRESULT + FormatMessage text
                       wstr      dereference as LPCWSTR
                       astr      dereference as LPCSTR
                       ptr       print as pointer 0x...
                       void      suppress output

Argument Types

Each ARG is one token. Prefixes pin the type; unprefixed tokens are
auto-detected (number-shaped tokens become integers, anything else
becomes a wide-string pointer).

    i:N          Signed integer; decimal or 0xHEX. Sign-extended to a
                 pointer-sized slot.
    u:N          Unsigned / DWORD value (same width).
    p:HEX        Raw pointer-sized value (hex or decimal).
    b:0|1        BOOL. Also accepts true / false / TRUE / FALSE.
    s:STRING     Wide string (LPCWSTR). The string lives until the call
                 returns.
    a:STRING     ANSI string (LPCSTR), converted from wide via CP_ACP.
    null         Explicit NULL pointer.
    obufw:N      Allocate an N-wide-char output buffer (zeroed). After
                 the call the contents up to the first NUL are printed
                 as a wide string.
    obufa:N      Allocate an N-byte output buffer (zeroed). Decoded as
                 ANSI text up to the first NUL.
    obuf:N       Allocate an N-byte output buffer (zeroed). Hex-dumped
                 after the call (16 bytes per row).
    obufd:VALUE  Allocate a 4-byte in/out DWORD initialized to VALUE.
                 After the call the slot is reprinted as DWORD.
    obufq:VALUE  Allocate an 8-byte in/out QWORD initialized to VALUE.
                 After the call the slot is reprinted as QWORD.

Up to 16 arguments are supported.

Examples

    rundllproc kernel32.dll GetTickCount
        Call a zero-arg function. Prints the tick count.

    rundllproc kernel32.dll Sleep 250
        Pass a single integer (auto-detected).

    rundllproc user32.dll MessageBoxW 0 "Hello" "cshw" 0
        Pass two integers and two wide strings (auto-detected).

    rundllproc --ret:bool user32.dll IsWindow p:0x10010
        Tell rundllproc to format the return as TRUE/FALSE; pass an
        explicit pointer-sized value.

    rundllproc --ret:hresult ole32.dll CoInitialize null
        Print the return as an HRESULT with the FormatMessage text.

    rundllproc --ret:wstr kernel32.dll GetCommandLineW
        Treat the LPWSTR return value as a string and print it.

    rundllproc --ret:bool kernel32.dll GetComputerNameW obufw:64 obufd:64
        Real in/out call: a 64-wide-char buffer for the name and a
        4-byte DWORD pre-initialized to 64 that the function updates
        with the number of chars written.

    rundllproc --ret:bool kernel32.dll GetEnvironmentVariableW s:PATH obufw:1024 i:1024
        Read an environment variable into an output buffer; the third
        arg is the buffer size in chars (a plain int, not in/out).

    rundllproc -r shell32.dll Control_RunDLL desk.cpl
        Use the rundll32-style entrypoint (HWND, HINSTANCE, LPSTR, int).

    rundllproc mydll.dll #5
        Look up function by ordinal.

    dllimport user32.dll
    rundllproc user32 GetForegroundWindow
        Preload a DLL and refer to it by alias.

Exit status

    0       Function returned (its value is in %result; check it
            yourself if the function uses a status code).
    other   DLL load failed, function not found, SEH exception
            during the call, or a syntactic problem with arguments.

Notes

Safety: rundllproc invokes the function under __try / __except. Access
violations and most hardware exceptions are caught and reported instead
of crashing the shell -- but a corrupted process state (heap, stack
walked too far, in-flight async work) can still leave the shell unhappy.
Calling a function with the wrong arg shape is undefined behavior.

Calling convention: on x64 there is one calling convention so 0..16
DWORD_PTR slots cover almost any Win32 API. On x86 the helper typedefs
are __cdecl; calling a __stdcall function with more args than its real
arity can disturb the stack frame.

Sign extension: integer results are formatted as DWORD_PTR by default.
A 32-bit signed return (e.g. lstrcmpW returning -1) will print as a
large unsigned value because the upper 32 bits of the return register
are zero on x64. Use --ret:hex if that is clearer, or compare against
0xFFFFFFFF.

See also

dllimport, dllunload, dlllist, winapi

say back to top ↑

print a system value (time, date, hostname, etc.) and capture it

Synopsis

    say <topic> [/fmt:<format>]

Description

Prints a single system value to stdout and stores it in $result for
script use. Supports time/date formatting via wcsftime-style format
strings, plus a handful of identity, location, and system-probe
topics.

Options

    Time / date topics (accept /fmt:<wcsftime-format>):
      time       Current time of day  (default: HH:MM:SS.cs)
      date       Current date         (default: MM/DD/YYYY)
      datetime   Date + time          (default: YYYY-MM-DD HH:MM:SS)
      now        Alias for datetime

    Identity / location:
      hostname   Computer name
      user       Current user name
      cwd        Current working directory
      version    cshw version string
      os         Friendly OS name + build (e.g. "Windows 11 (10.0.26100)")

    System probes: additional topics like arch, build, etc. are
    surfaced as the implementation grows; `say /?` (help) lists the
    current set.

    /fmt:<format>
        wcsftime-style format string, e.g. /fmt:"%Y-%m-%d %H:%M".
        Only meaningful for the time/date topics.

Examples

    say hostname
    set host = $result

    say now /fmt:"%Y%m%d_%H%M%S"
    set stamp = $result
    echo "log_$stamp.txt"

    say version
        # prints "1.0.0.0" (or whatever the current version is)

Exit status

    0       Success; $result holds the value.
    1       Unknown topic or bad format.

See also

date, time, version, uname, hostname

sed back to top ↑

stream editor for filtering and transforming text

Synopsis

    sed [OPTIONS]... SCRIPT [INPUT-FILE]...
    sed [OPTIONS]... -e SCRIPT [-e SCRIPT]... [INPUT-FILE]...
    sed [OPTIONS]... -f SCRIPT-FILE [INPUT-FILE]...
    command | sed [OPTIONS]... SCRIPT

Description

sed reads text from input files (or standard input), applies a script of
editing commands to each line, and writes the result to standard output.
It is the canonical Unix tool for non-interactive text editing -- search-
and-replace, line filtering, conditional rewriting, and stream rewriting
of any kind.

cshw's sed implements a substantial GNU sed subset, with PCRE2 as the
regex engine (so lookahead, lookbehind, named groups, and Unicode classes
all work) and dual Windows-style and Unix-style switch spellings. It
also adds Windows-specific behaviors for line endings, BOMs, and the
Recycle Bin.

Options

    -n, --quiet, --silent
                Suppress automatic printing of pattern space at the end
                of each cycle. Without this, sed prints every line that
                wasn't deleted; with it, only lines explicitly printed
                by p / P / s///p / = appear.

    -e SCRIPT, --expression=SCRIPT
                Add SCRIPT to the program. Multiple -e options accumulate.

    -f FILE, --file=FILE
                Add the contents of FILE to the program. Multiple -f
                options accumulate. Mixes freely with -e.

    -E, -r, --regexp-extended
                Accepted for GNU sed compatibility. cshw's sed uses
                PCRE2 syntax unconditionally, which is a superset of
                ERE, so this flag is effectively a no-op.

    -i[SUFFIX], --in-place[=SUFFIX]
                Edit files in place. If SUFFIX is given, a backup with
                that suffix is kept (e.g. -i.bak rewrites file.txt and
                preserves file.txt.bak). Without a suffix, no backup is
                kept. The original file's encoding and line-ending
                style are preserved.

    --recycle   With -i, send the original file to the Recycle Bin
                rather than overwriting it in place. The new content is
                written to a fresh file at the original path. Provides
                a soft-delete safety net even when no backup suffix is
                given. Mutually exclusive with -c. Fails (rather than
                silently falling back to a permanent overwrite) when
                the Recycle Bin is unavailable; see NOTES.

    -c, --copy  With -i, write to a temporary file and then copy back
                rather than rename. Slower but safe across hardlink
                boundaries and OneDrive sync points.

    -s, --separate
                Treat input files as separate streams: line numbers,
                $ (last line), and the t/T branch state reset for each
                file. Without it, files are concatenated into a single
                logical stream.

    -u, --unbuffered
                Flush output after each line.

    -z, --null-data
                Use the NUL byte (ASCII 0) as the line separator
                instead of newline. Useful with `find -print0` style
                producers.

    -l N, --line-length=N
                Wrap the `l` command's output at column N. Default 70.
                0 disables wrapping.

    --posix     Disable GNU extensions (a TEXT same-line form, T, R, W,
                F, Q, z, 0~step, addr,+N, addr,~N, the e flag and
                command, replacement-string case conversion). Useful
                when porting strict POSIX scripts.

    --sandbox   Refuse to run any command that touches the host outside
                the I/O streams: r, R, w, W, e, the e flag on s, and
                the F command. The script either runs without those or
                is rejected at parse time.

    --crlf      Force CRLF line endings on output, regardless of input.

    --unix      Force LF (Unix) line endings on output. Without --crlf
                or --unix, sed auto-detects per file and writes back
                what it read.

    --debug     Annotate output with the executing command and the
                state of pattern / hold space at each cycle. Verbose;
                useful for debugging non-trivial scripts.

    --help      Print the help screen and exit.
    --version   Print version and exit.

Switch aliases:
    cshw accepts both Unix-style (-x / --xxx) and Windows-style (/x)
    spellings everywhere. So `-i.bak`, `--in-place=.bak`, and
    `/i:.bak` are all equivalent.

.SED SCRIPT LANGUAGE

A sed program consists of one or more commands, separated by newlines or
semicolons. Each command optionally begins with an ADDRESS that selects
which lines the command applies to. Comments begin with `#` and run to
end of line. The first line beginning with `#n` is equivalent to -n.

Addresses

    N           Line number N (1-based). E.g. `5d` deletes line 5.
    $           Last line of input.
    /REGEX/     Lines matching REGEX.
    \cREGEXc    Same, with custom delimiter c (any non-newline char).
                Useful when REGEX contains slashes:
                    \;/usr/local;d
    //          Empty regex re-uses the most recent regex from any
                command in the script.
    N,M         Range: from line N through line M (inclusive).
    N,$         From line N through end of input.
    /RE1/,/RE2/ From the next line matching RE1 through the next line
                matching RE2 thereafter (inclusive). Range "latches":
                once entered, stays active until RE2 matches.
    ADDR1,+N    [GNU] N lines after ADDR1 (inclusive of ADDR1).
    ADDR1,~N    [GNU] Through the next line whose number is a multiple
                of N.
    FIRST~STEP  [GNU] Every STEP lines starting at line FIRST.
                E.g. `0~2` is even lines, `1~2` is odd lines.
    0,/REGEX/   [GNU] Like /REGEX/,/REGEX/ but matches REGEX even on
                line 1 (the standard form skips line 1 when looking
                for the start of the range).
    ADDR !      Negate: the command applies to lines NOT matching ADDR.

Commands

Substitution and transliteration:
    s/RE/REPL/FLAGS
                The workhorse. Substitute RE with REPL in pattern space.
                Delimiter is whatever character follows `s` (commonly /
                or | or #). Replacement specials:
                    &       The whole match.
                    \&      A literal &.
                    \1..\9  Capture group N.
                    \n,\t   Newline, tab.
                    \r      Carriage return.
                    \\      Literal backslash.
                    \l, \u  Lowercase / uppercase the next character.
                    \L, \U  Lowercase / uppercase until \E or end.
                    \E      End \L / \U region.
                    \<nl>   Embed a literal newline in the replacement.
                Flags (any combination):
                    g       Replace all occurrences (not just the first).
                    N       Replace only the Nth occurrence (1-512).
                            Combine with g (`s/RE/REPL/3g`) to replace
                            from the Nth occurrence onward.
                    p       Print pattern space if a substitution was made.
                    w FILE  Append pattern space to FILE if substituted.
                    i, I    Case-insensitive matching.
                    m, M    Multi-line matching: ^ and $ match at
                            embedded newlines.
                    e       Execute the result as a shell command.
                            Disabled when --sandbox is in effect.
                            (cshw also disables this by default for
                            safety; pass --enable-e to opt in.)

    y/SRC/DST/  Transliterate: replace each occurrence of a character
                in SRC with the corresponding character in DST. SRC and
                DST must have the same length (after escape processing).

Pattern space output:
    p           Print the current pattern space.
    P           Print up to (and including) the first embedded newline
                in pattern space.
    =           Print the current input line number.
    l [N]       Print pattern space "unambiguously": non-printable bytes
                shown as \ooo octal, $ marks end of line, long lines
                wrap at column N (default 70 or --line-length).

Pattern space lifecycle:
    n           Print pattern space (unless -n), then read the next
                input line into pattern space. If no next line, exit.
    N           Append a newline and the next input line to pattern
                space. If no next line, behavior depends on --posix:
                strict POSIX exits without auto-printing; GNU prints
                pattern space first.
    d           Delete pattern space, start next cycle (skip auto-print).
    D           Delete up to and including the first embedded newline
                in pattern space; restart the cycle WITHOUT reading new
                input (re-runs the script on whatever's left). If no
                embedded newline, equivalent to d.

Hold space:
    h           Replace hold space with pattern space.
    H           Append \n + pattern space to hold space.
    g           Replace pattern space with hold space.
    G           Append \n + hold space to pattern space.
    x           Exchange the contents of pattern and hold space.
    z           [GNU] Zap (clear) pattern space.

Append / insert / change:
    a TEXT      Append TEXT after current line is output. TEXT can
    a\          continue across lines using a backslash at end of line.
    TEXT        The single-line `a TEXT` form is a GNU extension; the
                two-line `a\` + TEXT form is portable.
    i TEXT      Insert TEXT before current pattern space output.
    i\          Same continuation rules as `a`.
    c TEXT      Replace pattern space with TEXT. With a range address,
    c\          replaces the entire range with one copy of TEXT.

File I/O:
    r FILE      Queue contents of FILE to be output after the current
                pattern space. If FILE doesn't exist, the command is
                silently a no-op (matching GNU behavior).
    R FILE      [GNU] Queue ONE line from FILE per matching line.
                Subsequent matches read subsequent lines until EOF.
    w FILE      Write current pattern space to FILE (append after the
                first write per command per invocation; the file is
                truncated on first write).
    W FILE      [GNU] Write up to the first embedded newline of pattern
                space to FILE.
    F           [GNU] Print the name of the current input file.

Branching:
    : LABEL     Define a label.
    b LABEL     Unconditional branch to LABEL. Without a label, branch
                to end of script (skip remaining commands this cycle).
    t LABEL     Branch if any successful s/// has occurred since the
                last input line was read or the last branch.
    T LABEL     [GNU] Branch if NO successful s/// has occurred since
                the last input line was read or the last branch.

Termination:
    q [N]       Print pattern space (unless -n), drain append queue,
                exit with status N (default 0).
    Q [N]       [GNU] Quit without auto-printing or draining append
                queue.

Grouping:
    { CMDS }    Apply a block of commands as a single unit, useful with
                addresses. Group can span multiple lines.

Misc:
    #...        Comment, runs to end of line. The first line of the
                first script that begins exactly with `#n` enables -n.
    nothing     Empty commands (consecutive ; or empty -e args) are
                tolerated.

Examples

    sed 's/foo/bar/' file.txt
        Replace first 'foo' on each line with 'bar'.

    sed 's/foo/bar/g' file.txt
        Replace ALL 'foo' with 'bar' on each line.

    sed -n '5p' file.txt
        Print only line 5.

    sed '5d' file.txt
        Print everything except line 5.

    sed '/^#/d' config.ini
        Strip comment lines.

    sed -i.bak 's/old/new/g' notes.txt
        In-place edit; keep notes.txt.bak as backup.

    sed -i --recycle 's/old/new/g' notes.txt
        In-place edit; send original to the Recycle Bin (recoverable).

    sed -n '/BEGIN/,/END/p' file.txt
        Print everything between BEGIN and END markers.

    sed '5,$d' file.txt
        Keep only the first 4 lines.

    sed '0~3d' file.txt
        Delete every 3rd line.

    sed -e '/^$/d' -e 's/^[ \t]*//' file.txt
        Strip blank lines, then strip leading whitespace.

    sed 'y/abc/ABC/' file.txt
        Uppercase a, b, c.

    sed 's/.*/\U&/' file.txt
        Uppercase every line. (\U..\E is a GNU replacement extension.)

    sed -E 's/([a-z]+) ([a-z]+)/\2 \1/' names.txt
        Swap two adjacent lowercase words. -E is accepted but no-op
        (PCRE2 is the default flavor).

    sed -n '
      h
      $!d
      x
      s/.*\n//
      p
    ' file.txt
        Print only the last line (manual implementation of tail -1).

    type file.txt | sed 's/\r$//'
        Strip trailing CR (one way to convert CRLF to LF on the fly).
        Note: sed already auto-detects line endings; this is rarely
        needed in cshw.

Exit status

    0       Successful completion.
    1       At least one input file could not be opened.
    2       Sed program syntax error, or a regex failed to compile.
    N       The Q or q command exited with status N.

Notes

Regex flavor:
    cshw's sed uses PCRE2 (Perl Compatible Regular Expressions) for all
    pattern matching. This is a superset of ERE, so anything that works
    with `sed -E` on Linux works here. Strict GNU BRE (where (...) is
    literal and \(...\) is grouping) is NOT emulated -- always use ERE
    syntax. The -E / -r / --regexp-extended flags are accepted purely
    for command-line compatibility.

Line endings:
    Input is auto-detected per file: if the file uses CRLF on at least
    one line, the file is treated as CRLF and CRLFs are stripped before
    each line enters pattern space, then re-added on output. LF-only
    files round-trip as LF. To force one or the other, use --crlf or
    --unix.

Encodings:
    UTF-8, UTF-16-LE, UTF-16-BE are auto-detected via byte-order mark.
    BOMs are preserved on output. Files with no BOM are read as UTF-8.

In-place editing semantics:
    Without --recycle and without -c, sed renames a temp file over the
    original. This is fast and atomic on the same drive but breaks
    hardlinks and may confuse OneDrive/Dropbox; use -c if either matters.

    With --recycle, sed:
      1. Writes the new content to a temp file.
      2. Sends the original file to the Recycle Bin (via Vista+
         IFileOperation with FOFX_RECYCLEONDELETE, so it FAILS rather
         than silently permanent-deleting if the bin is unavailable).
      3. Renames the temp file into place.
    If step 2 fails, the temp file is removed and the original is
    untouched.

Recycle Bin caveats:
    --recycle refuses (instead of silently falling back to permanent
    delete) when:
      - the file is on a network/UNC share,
      - the file is larger than the per-drive Recycle Bin size budget,
      - the drive is removable and has no per-drive bin enabled,
      - or the bin is disabled by group policy on this drive.
    Same contract as `rm /recycle` and `rmdir /recycle`.

Sandbox mode:
    --sandbox rejects scripts that contain r, R, w, W, F, e, or the s///e
    flag at parse time, with a clear error pointing at the offending
    command. This is GNU-compatible behavior. Use --sandbox when
    running untrusted scripts, e.g. via stdin on a server.

Differences from GNU sed:
    * The `e` command and the s///e flag are disabled by default.
      Pass --enable-e to opt in. GNU sed allows them by default.
    * Strict BRE is not supported (PCRE2 / ERE only).
    * The --debug output format is similar but not byte-identical.
    * `l N` uses the cshw line-length when no command-local override
      is present; default is 70 to match GNU.

POSIX sed compatibility:
    --posix disables: same-line a / i / c text; `T`, `R`, `W`, `F`,
    `Q`, `z`; 0~step / addr,+N / addr,~N addresses; the s/// case-
    conversion replacement escapes (\l \u \L \U \E); the /g flag with
    a leading number; and embedded newlines in pattern space via N
    without auto-printing.

See also

awk, grep, tr, cut, type, mv

References

    GNU sed manual: https://www.gnu.org/software/sed/manual/sed.html
    POSIX sed:      IEEE Std 1003.1-2017

sendmessage back to top ↑

send a Win32 message to a window (synchronous)

Synopsis

    sendmessage <hwnd> <msg> [<wParam> [<lParam>]]

Description

Calls SendMessageW(hwnd, msg, wParam, lParam) and blocks until the
window's WndProc returns. The LRESULT is captured in $result as a
long.

`msg` accepts symbolic WM_* names (case-insensitive) or hex/decimal
numbers. Symbolic names are looked up in CSHW's built-in table; any
message not in the table can still be addressed by number.

Options

    <hwnd>      Target HWND in hex or decimal. Must satisfy IsWindow().
    <msg>       Symbolic name (WM_CLOSE, wm_command, WM_USER, ...) or
                a number (0x10, 16, 273, ...).
    <wParam>    WPARAM. Default 0. Hex or decimal.
    <lParam>    LPARAM. Default 0. Hex or decimal.

    Recognized symbolic names include: WM_NULL, WM_CREATE, WM_DESTROY,
    WM_MOVE, WM_SIZE, WM_ACTIVATE, WM_SETFOCUS, WM_KILLFOCUS,
    WM_ENABLE, WM_SETTEXT, WM_GETTEXT, WM_GETTEXTLENGTH, WM_PAINT,
    WM_CLOSE, WM_QUIT, WM_SHOWWINDOW, WM_ACTIVATEAPP, WM_SETCURSOR,
    WM_GETMINMAXINFO, WM_NOTIFY, WM_KEYDOWN, WM_KEYUP, WM_CHAR,
    WM_SYSKEYDOWN, WM_SYSKEYUP, WM_COMMAND, WM_TIMER, WM_HSCROLL,
    WM_VSCROLL, WM_MOUSEMOVE, WM_LBUTTONDOWN, WM_LBUTTONUP,
    WM_RBUTTONDOWN, WM_RBUTTONUP, WM_USER.

Examples

    # Simulate a button click on control id 100 in window $w:
    sendmessage $w WM_COMMAND 100 0

    # Programmatically close a window:
    sendmessage $w WM_CLOSE

    # Set a window's text:
    # (lParam is the address of the string in real Win32 -- not safe
    # to pass a script string here; use SetWindowText via winapi for
    # text-setting.)

Exit status

    0       Success. $result holds the LRESULT as a long.
    1       Bad HWND, unparseable message, or bad wParam/lParam.

Notes

SendMessage is synchronous and may block on a misbehaving window.
For fire-and-forget delivery use `postmessage`.

See also

postmessage, bindevent, createwindow

seq back to top ↑

print sequence of numbers

Synopsis

    seq LAST
    seq FIRST LAST
    seq FIRST INCREMENT LAST

Description

Prints a sequence of numbers from FIRST to LAST, with optional INCREMENT.
Useful for loops, generating test data, and numeric sequences.

Options

    LAST            Print 1 to LAST.
    FIRST LAST      Print FIRST to LAST.
    FIRST INCREMENT LAST
                    Print from FIRST to LAST by INCREMENT.

    -s STRING       Use STRING as separator (default: newline).
    -w, --equal-width
                    Pad with leading zeros for equal width.
    -f FORMAT       Use printf-style FORMAT.

Examples

    seq 5
        Output: 1 2 3 4 5 (one per line)

    seq 3 7
        Output: 3 4 5 6 7

    seq 0 2 10
        Output: 0 2 4 6 8 10 (by 2)

    seq 10 -1 1
        Output: 10 9 8 7 6 5 4 3 2 1 (countdown)

    seq -s ", " 5
        Output: 1, 2, 3, 4, 5

    seq -w 1 100
        Output: 001 002 ... 099 100 (padded)

    seq 0.5 0.5 3
        Output: 0.5 1.0 1.5 2.0 2.5 3.0 (decimals)

    # Loop example:
    foreach i ($(seq 1 10))
        echo "Iteration $i"
    endforeach

Exit status

    0       Success
    1       Invalid arguments

Notes

Floating Point:
seq supports decimal numbers:
    seq 0.1 0.1 1.0

Negative Numbers:
Both negative values and counting down work:
    seq -5 5      # -5 to 5
    seq 5 -1 -5   # 5 down to -5

Use in Loops:
seq is commonly used with foreach:
    foreach n ($(seq 1 100))
        process_item $n
    endforeach

Generating Data:
Useful for creating test files:
    seq 1000000 > numbers.txt

See also

foreach, loop, echo

service back to top ↑

manage Windows services

Synopsis

    service list
    service start NAME
    service stop NAME
    service restart NAME
    service status NAME
    service info NAME

Description

Manages Windows services - background processes that run independently
of user sessions. Can list, start, stop, restart, and query service status.

Options

    Subcommands:

    list            List all services with their status.
    start NAME      Start a stopped service.
    stop NAME       Stop a running service.
    restart NAME    Stop then start a service.
    status NAME     Show current status of a service.
    info NAME       Display detailed service information.

    Options:
    /all            Include all services (not just running).

Examples

    service list
        List running services.

    service list /all
        List all services including stopped ones.

    service status spooler
        Check print spooler status.

    service start wuauserv
        Start Windows Update service.

    service stop wuauserv
        Stop Windows Update service.

    service restart spooler
        Restart print spooler (common fix for printing issues).

    service info bits
        Show detailed info about BITS service.

Exit status

    0       Success
    1       Service not found
    2       Access denied (need Administrator)
    3       Service operation failed

Notes

Administrator Required:
Starting and stopping services requires Administrator privileges.
Run the shell as Administrator for service management.

Service Names:
Use the short service name, not the display name. For example:
- wuauserv (not "Windows Update")
- spooler (not "Print Spooler")
- bits (not "Background Intelligent Transfer Service")

Use 'service info' to see both names.

Common Services:
    wuauserv    Windows Update
    spooler     Print Spooler
    w32time     Windows Time
    bits        Background Intelligent Transfer Service
    dnscache    DNS Client
    wsearch     Windows Search

Startup Types:
Services can be set to start automatically, manually, or be disabled.
This command doesn't modify startup types.

See also

processlist, kill, reg

set back to top ↑

set or display shell variables

Synopsis

    set
    set NAME=VALUE
    set NAME VALUE

Description

Sets a shell variable or displays all currently defined shell variables.
Without arguments, displays all shell variables and their values.

Shell variables are used for storing values that can be referenced later
in commands and scripts using the $NAME syntax. Variables can hold strings,
integers, or floating-point numbers, and CSHW automatically tracks the type.

Variables set with 'set' are shell-local and do not affect the system
environment. Use 'setenv' to modify environment variables.

Options

    NAME            The variable name. Must start with a letter or underscore,
                    followed by letters, digits, or underscores.

    VALUE           The value to assign. Can be:
                    - String: "hello world" or hello
                    - Integer: 42, -17, 0x1F (hex)
                    - Float: 3.14, -2.5, 1.0e-3

Examples

    set
        Display all shell variables.

    set count=10
        Set variable 'count' to integer 10.

    set name="John Doe"
        Set variable 'name' to a string with spaces.

    set pi=3.14159
        Set variable 'pi' to a floating-point number.

    set path C:\Tools
        Set variable 'path' (alternative syntax without =).

    echo $count
        Display the value of variable 'count'.

    set result=$?
        Store the last command's exit code in 'result'.

    set files=$(dir /b *.txt)
        Store command output in a variable (command substitution).

Exit status

    0       Success
    1       Invalid variable name
    2       Syntax error

Environment

Shell variables are separate from environment variables. Changes made with
'set' do not affect the process environment. Use 'setenv' for that purpose.

Notes

Variable Naming Rules:
- Must start with a letter (a-z, A-Z) or underscore (_)
- Can contain letters, digits (0-9), and underscores
- Names are case-sensitive ($Name != $name)

Type Inference:
CSHW automatically determines variable type based on the assigned value:
- Integers: whole numbers (42, -17, 0xFF)
- Floats: numbers with decimal points (3.14) or exponents (1e-3)
- Strings: everything else ("hello", paths, etc.)

Use 'vartype' command to check a variable's inferred type.

Special Variables:
    $?      Exit code of the last command
    $:      Current working directory
    $$      Process ID of the shell

See also

unset, vartype, setenv, unsetenv, echo

setenv back to top ↑

set environment variable

Synopsis

    setenv NAME VALUE
    setenv NAME=VALUE

Description

Sets or modifies an environment variable. Unlike shell variables (set),
environment variables are inherited by child processes and can affect
system behavior.

Options

    NAME            Environment variable name.
    VALUE           Value to assign.

Examples

    setenv PATH "C:\Tools;%PATH%"
        Prepend C:\Tools to PATH.

    setenv JAVA_HOME "C:\Program Files\Java\jdk-17"
        Set JAVA_HOME for Java applications.

    setenv DEBUG 1
        Set a debug flag.

    setenv MY_APP_CONFIG "C:\Config\app.ini"
        Set application-specific variable.

Exit status

    0       Success
    1       Invalid name
    2       Error setting variable

Notes

Inheritance:
Environment variables are inherited by child processes:
- Programs started from the shell see these variables
- Use for configuration that programs expect

Shell vs Environment Variables:
- set: Shell-local, not inherited by children
- setenv: Environment, inherited by children

Persistence:
setenv changes only affect the current session and child processes.
To permanently set environment variables, use System Properties or
the Windows 'setx' command.

Common Variables:
    PATH        Executable search path
    HOME        User's home directory
    TEMP/TMP    Temporary file directory
    USERNAME    Current user name

Case Sensitivity:
Environment variable names are case-insensitive on Windows
(PATH = Path = path).

See also

unsetenv, set, env, printenv

sha1sum back to top ↑

compute SHA-1 message digest

Synopsis

    sha1sum FILE...
    command | sha1sum

Description

Computes and displays the SHA-1 hash (160-bit) of files. SHA-1 produces
a 40-character hexadecimal digest.

Options

    FILE            One or more files to hash.

    -c FILE         Check SHA-1 sums against a checksum file.

Examples

    sha1sum file.txt
        Compute SHA-1 hash.

    sha1sum *.zip
        Hash multiple files.

    sha1sum -c checksums.sha1
        Verify files against checksums.

    echo "test" | sha1sum
        Hash a string.

Exit status

    0       Success (or all checksums verified)
    1       Checksum mismatch
    2       File not found

Notes

Security Warning:
SHA-1 is cryptographically broken and should NOT be used for
security purposes. Collisions have been demonstrated.

Acceptable uses for SHA-1:
- Legacy system compatibility
- Non-security checksums
- Git commit IDs (uses SHA-1)

For security, use SHA-256 or SHA-512 instead.

Output Format:
    da39a3ee5e6b4b0d3255bfef95601890afd80709  filename

Git Compatibility:
Git uses SHA-1 for commit and object IDs, so sha1sum can be useful
when working with Git internals.

See also

sha256sum, sha512sum, md5sum

sha256sum back to top ↑

compute SHA-256 message digest

Synopsis

    sha256sum FILE...
    command | sha256sum

Description

Computes and displays the SHA-256 hash (256-bit) of files. SHA-256 is
cryptographically secure and produces a 64-character hexadecimal digest.

SHA-256 is recommended for security applications including file
integrity verification and digital signatures.

Options

    FILE            One or more files to hash.

    -c FILE         Check SHA-256 sums against a checksum file.

Examples

    sha256sum installer.exe
        Compute SHA-256 hash.

    sha256sum *.zip > checksums.sha256
        Generate checksums for all ZIP files.

    sha256sum -c checksums.sha256
        Verify files against checksums.

    echo "secret" | sha256sum
        Hash a string (includes newline).

Exit status

    0       Success (or all checksums verified)
    1       Checksum mismatch
    2       File not found

Notes

Output Format:
    e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855  file.txt

Security:
SHA-256 is part of the SHA-2 family and is considered cryptographically
secure. It's suitable for:
- File integrity verification
- Digital signatures
- Password hashing (with proper salting)
- Blockchain and cryptocurrency

Verification:
Software downloads often provide SHA-256 checksums. Always verify:
    sha256sum -c downloaded.sha256

Speed:
SHA-256 is slower than MD5 but provides much stronger security.

See also

sha512sum, sha1sum, md5sum

sha512sum back to top ↑

compute SHA-512 message digest

Synopsis

    sha512sum FILE...
    command | sha512sum

Description

Computes and displays the SHA-512 hash (512-bit) of files. SHA-512
produces a 128-character hexadecimal digest. Part of the SHA-2 family,
it offers the highest security level.

Options

    FILE            One or more files to hash.

    -c FILE         Check SHA-512 sums against a checksum file.

Examples

    sha512sum file.txt
        Compute SHA-512 hash.

    sha512sum important.doc > important.sha512
        Save checksum to file.

    sha512sum -c checksums.sha512
        Verify files against checksums.

    sha512sum *.iso
        Hash multiple ISO files.

Exit status

    0       Success (or all checksums verified)
    1       Checksum mismatch
    2       File not found

Notes

Security:
SHA-512 is the strongest SHA-2 variant. Suitable for:
- High-security file integrity
- Cryptographic applications
- Password hashing (with salt)

Output Format:
    cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e  file

Performance:
SHA-512 is actually faster than SHA-256 on 64-bit systems due to
using 64-bit operations natively.

When to Use:
- Maximum security requirements
- Long-term archives
- Cryptographic protocols
- When 256 bits isn't enough

See also

sha256sum, sha1sum, md5sum, shasum

share back to top ↑

assign a variable in the global namespace (write-through)

Synopsis

    share <name> = <value>
    share <name>[<index>] = <value>
    share <name>{<key>}   = <value>

Description

Like `set`, but always writes through to the global variable namespace
even when called from inside a proc or a coroutine.

Inside a proc, plain `set foo = 1` creates a procedure-local variable
that disappears on return. Inside a coroutine, plain `set` creates a
coroutine-local variable invisible to the main script thread.

`share` bypasses both. The variable is created/updated in the global
namespace, visible to every thread and outliving any proc / coroutine
scope.

Options

    <name>      Variable name. Same naming rules as `set`.
    <value>     The value to assign. Supports the same forms `set`
                supports: integer literals, floats, quoted strings,
                command-substitution, etc.

Examples

    # Coroutine writes a result back to the main thread:
    share _ready = 0
    proc worker
        sleep 2
        share _ready = 1
    endproc
    spawn worker
    while ($_ready == 0)
        sleep 0.1
    end
    echo "worker finished"

    # Procedure publishes a return value via a shared var instead of
    # the conventional $result -- useful when multiple values matter:
    proc compute
        share answer  = 42
        share message = "ok"
    endproc
    compute
    echo "$answer / $message"

Exit status

    0       Variable was written.
    1       Syntax error or readonly violation.

Notes

`share` is the canonical way for a coroutine to communicate results
back to the main script thread. Coroutine-local `set` writes are
isolated by design; `share` is the explicit opt-in to break that
isolation.

WM_CLOSE veto handlers (see `bindevent`) similarly use `share` to
report user intent back to the script that's waiting on the dialog.

See also

set, unset, local, declare, readonly

shasum back to top ↑

compute SHA hash with selectable algorithm

Synopsis

    shasum FILE
    shasum -a ALGORITHM FILE
    command | shasum

Description

Computes SHA hash using a specified algorithm. Provides a unified interface
to multiple SHA variants.

Options

    FILE            File to hash.

    -a ALGORITHM    Hash algorithm to use:
                    1       SHA-1 (160-bit) - NOT SECURE
                    224     SHA-224 (224-bit)
                    256     SHA-256 (256-bit) - DEFAULT
                    384     SHA-384 (384-bit)
                    512     SHA-512 (512-bit)

    -c FILE         Check hashes from FILE.
    -b              Read files in binary mode.

Examples

    shasum file.txt
        Compute SHA-256 hash (default).

    shasum -a 512 file.txt
        Compute SHA-512 hash.

    shasum -a 1 file.txt
        Compute SHA-1 hash (legacy).

    shasum -a 256 *.exe > checksums.txt
        Generate checksums for all executables.

    shasum -c checksums.txt
        Verify files against checksums.

Exit status

    0       Success
    1       Checksum mismatch
    2       Invalid algorithm or file error

Notes

Algorithm Selection:
- SHA-1: Legacy only, broken cryptographically
- SHA-224: Truncated SHA-256, rarely used
- SHA-256: Recommended for most uses
- SHA-384: Truncated SHA-512
- SHA-512: Maximum security

Compatibility:
shasum output is compatible with standard checksum file format,
usable across different systems.

Default Algorithm:
Without -a, shasum uses SHA-256, which is secure and widely used.

Perl Compatibility:
This command is compatible with Perl's shasum utility found on
many UNIX systems.

See also

sha256sum, sha512sum, sha1sum, md5sum

shift back to top ↑

shift positional parameters

Synopsis

    shift
    shift N

Description

Shifts positional parameters ($1, $2, etc.) to the left. After shift,
$2 becomes $1, $3 becomes $2, and so on. The old $1 is discarded.

Options

    N               Number of positions to shift (default: 1).

Examples

    # Script: process_args.csh
    # Called with: process_args a b c d

    echo $1     # a
    shift
    echo $1     # b (was $2)
    shift
    echo $1     # c (was $3)

    # Shift by 2:
    shift 2
    echo $1     # d (was $4)

    # Process all arguments:
    while ($# > 0)
        echo "Processing: $1"
        shift
    endwhile

Exit status

    0       Success
    1       No arguments to shift

Notes

Use in Scripts:
shift is commonly used in scripts to process command-line arguments
one at a time, especially when argument count varies.

$# Variable:
$# contains the argument count. After shift, $# decreases by 1.

Processing Options:
Common pattern for handling options:
    while ($# > 0)
        if ($1 == "-v")
            set verbose=1
        else if ($1 == "-o")
            shift
            set output=$1
        else
            # Regular argument
            process $1
        endif
        shift
    endwhile

Empty Arguments:
Shifting when no arguments remain produces an error.

See also

set, echo

shutdown back to top ↑

shutdown, restart, or log off the system

Synopsis

    shutdown [options]
    shutdown /s
    shutdown /r
    shutdown /l

Description

Shuts down, restarts, or logs off the computer. Can also abort a pending
shutdown operation. Requires appropriate privileges for shutdown/restart.

Options

    /s              Shutdown the computer.
    /r              Restart the computer.
    /l              Log off the current user.
    /h              Hibernate (if supported).
    /a              Abort a pending shutdown.
    /t SECONDS      Time delay before action (default: 30).
    /f              Force running applications to close.
    /c "MESSAGE"    Display a comment/reason (max 512 chars).
    /p              Immediate poweroff (no timeout, no warning).

Examples

    shutdown /s
        Shutdown in 30 seconds.

    shutdown /r /t 0
        Immediate restart.

    shutdown /l
        Log off current user.

    shutdown /s /t 60 /c "Maintenance in 1 minute"
        Shutdown in 60 seconds with message.

    shutdown /a
        Cancel pending shutdown.

    shutdown /r /f
        Restart, force-closing applications.

    shutdown /h
        Hibernate the system.

    shutdown /p
        Immediate power off (no delay).

Exit status

    0       Success (operation initiated)
    1       Access denied
    2       Invalid argument

Notes

Force Close:
Without /f, shutdown waits for applications to close gracefully.
With /f, applications are forcefully terminated (may lose unsaved work).

Abort Window:
During the timeout period, use 'shutdown /a' to cancel.

Privileges:
Shutdown and restart require appropriate privileges. On domain
computers, group policy may restrict these operations.

Remote Shutdown:
Windows supports remote shutdown with /m \\computer option,
though this may require additional configuration.

Scheduled Tasks:
For scheduled shutdowns, consider using Task Scheduler instead
of leaving a shutdown command pending.

See also

exit, logout, service

sleep back to top ↑

pause the current thread of execution for a duration

Synopsis

    sleep DURATION

Description

Blocks the current thread of execution for DURATION. In the interactive
shell that means the prompt pauses; inside a coroutine it pauses just
that coroutine while the rest of the shell keeps running.

DURATION is a number with an optional unit suffix. Fractional values
are accepted and rounded to the nearest millisecond. The maximum
duration is about 49 days (the 32-bit millisecond cap that Win32
Sleep() uses).

Options

    DURATION    Number + optional unit. Recognised suffixes:
                  ms                milliseconds
                  s   (default)     seconds
                  m                 minutes
                  h                 hours
                  d                 days
                Long-form aliases (millisecond, sec, secs, min, mins,
                hour, hours, day, days) are also accepted.

Examples

    sleep 5
        Pause for 5 seconds (default unit is seconds).

    sleep 0.5
        Pause for 500 milliseconds.

    sleep 100ms
        Pause for 100 milliseconds.

    sleep 2s
        Pause for 2 seconds.

    sleep 5m
        Pause for 5 minutes.

    sleep 1.5h
        Pause for one hour and thirty minutes.

    sleep 1d
        Pause for 24 hours.

    # In a polling loop:
    while (1)
        processlist | grep myprogram
        sleep 5s
    endwhile

    # Inside a coroutine -- only this coroutine pauses:
    corunproc myproc {
        sleep 1m
        echo "minute elapsed"
    }

Exit status

    0       Success.
    1       Missing argument, negative value, unknown unit, or
            duration over the 49-day cap.

Notes

sleep blocks the calling thread (Win32 Sleep). For per-coroutine pauses,
just call sleep inside the coroutine -- it will not block the shell.

To pause until a system event rather than a time, write the polling
loop yourself with a 'while' and a short sleep, or use 'corunproc' to
do the waiting on a worker.

To prevent the *system* from sleeping while a long task runs, see
'suspend keepawake'.

See also

suspend, timeout, time, corunproc

socket back to top ↑

low-level socket operations

Synopsis

    socket <subcommand> [args...]

Description

Provides low-level TCP and UDP socket operations for network programming.
Sockets are identified by names (user-assigned or auto-generated like "sock1").

Subcommands

    create [-4|-6] [--dual] [--keep-mapped] tcp|udp [name]
        Create a new socket. Returns socket id in $result.
        Type can be 'tcp' (SOCK_STREAM) or 'udp' (SOCK_DGRAM).
        Default family is IPv4. Pass -6 (or --ipv6) for an IPv6 socket.

        --dual
            For IPv6 sockets, clear IPV6_V6ONLY before bind so the same
            socket accepts both IPv6 and IPv4 clients. Implies -6; using
            it with -4 is an error.

        --keep-mapped
            By default, when a v4 client connects to a dual-stack v6
            listener, its address is stripped from ::ffff:a.b.c.d to plain
            a.b.c.d in 'socket info' and 'socket accept' output, and the
            accepted socket's family is reported as IPv4. Pass this flag
            to keep the on-the-wire v6 form. Only meaningful with --dual.

    bind <sock> [addr] <port>
        Bind socket to address and port. Address defaults to the wildcard for
        the socket's family: 0.0.0.0 for IPv4, :: for IPv6. Quote IPv6 literals
        on the command line: socket bind v6sock "::1" 8080

    listen <sock> [backlog]
        Start listening for connections. Backlog defaults to SOMAXCONN.

    accept <sock> [/timeout:ms] [name]
        Accept an incoming connection. Returns new socket id in $result.
        Use /timeout to specify maximum wait time in milliseconds.

    connect <sock> <host> <port> [/timeout:ms]
        Connect to a remote server. Host can be IP address or hostname.

    send <sock> <data>
        Send data through the socket. Data is sent as UTF-8.

    recv <sock> [maxbytes] [/timeout:ms]
        Receive data from socket. Result stored in $result.
        Default maxbytes is 4096. Timeout returns empty string (not error).

    close <sock> | /all
        Close a socket or all open sockets.

    list
        Display all open sockets with their state and addresses.

    info <sock>
        Show detailed information about a socket.

    select <sock> r|w|e [/timeout:ms]
        Check if socket is readable (r), writable (w), or has errors (e).
        Multiple modes can be combined (e.g., "rw"). Result contains matched modes.

Options

    /timeout:ms, /t:ms
        Specify timeout in milliseconds for blocking operations.

Examples

    # Simple TCP server
    socket create tcp server
    socket bind server 8080
    socket listen server
    set client (socket accept server)
    socket recv $client
    echo "Received: $result"
    socket send $client "Hello back!"
    socket close $client
    socket close server

    # Simple TCP client
    socket create tcp
    socket connect $result localhost 8080
    socket send $result "Hello server"
    socket recv $result
    echo "Response: $result"
    socket close $result

    # UDP example
    socket create udp sender
    socket connect sender 192.168.1.100 5000
    socket send sender "UDP message"
    socket close sender

    # Check socket readability with timeout
    socket select mysock r /timeout:5000
    if $result == "r"
        socket recv mysock
    endif

Exit status

    0       Success
    >0      Error (check $errorlevel for WSA error code)

Errors

    10048   WSAEADDRINUSE - Address already in use
    10060   WSAETIMEDOUT - Connection timed out
    10061   WSAECONNREFUSED - Connection refused

See also

tcpserver, tcpclient, fetch

sort back to top ↑

sort lines of text

Synopsis

    sort [options] FILE
    command | sort [options]

Description

Sorts lines of text alphabetically or numerically. By default, sorts in
ascending order using the entire line as the sort key.

Options

    FILE            File to sort.

    -r, --reverse   Sort in descending order.
    -n, --numeric   Sort numerically instead of alphabetically.
    -u, --unique    Remove duplicate lines (output unique lines only).
    -f, --ignore-case
                    Ignore case when sorting.
    -t CHAR         Use CHAR as field delimiter.
    -k N            Sort by field N (1-based).

Examples

    sort names.txt
        Sort file alphabetically.

    sort -r names.txt
        Sort in reverse order.

    sort -n numbers.txt
        Sort numerically (1, 2, 10 not 1, 10, 2).

    sort -u data.txt
        Sort and remove duplicates.

    dir /b | sort
        Sort directory listing.

    sort -t, -k2 data.csv
        Sort CSV by second column.

    sort -f words.txt
        Case-insensitive sort.

    type log.txt | grep ERROR | sort -u
        Get unique sorted error lines.

Exit status

    0       Success
    1       File not found
    2       Error

Notes

Stability:
The sort is stable - equal elements maintain their relative order.

Numeric vs Alphabetic:
Without -n, "10" sorts before "2" (alphabetically).
With -n, "2" sorts before "10" (numerically).

Memory:
Large files are sorted in memory. Very large files may require
significant RAM.

Locale:
Sort order may be affected by system locale settings.

See also

uniq, wc, grep

source back to top ↑

execute commands from a file in the current shell

Synopsis

    source FILE
    . FILE

Description

Reads and executes commands from FILE in the current shell environment.
Unlike running a script normally, source executes in the current shell,
so variable changes and alias definitions persist after the file executes.

This is the standard way to load configuration files and define procedures.

Options

    FILE            Script file to execute.

Examples

    source config.csh
        Load configuration file.

    source ~/.cshrc
        Load shell startup file.

    source functions.csh
        Load procedure definitions.

    . mysetup.csh
        Short form using dot notation.

    source env_setup.csh && echo "Environment loaded"
        Load and confirm.

Exit status

    Returns the exit status of the last command executed in the file.

Notes

Variable Scope:
Variables set in the sourced file become available in the current
shell. This is different from running a script as a subprocess.

Use Cases:
- Loading configuration: source ~/.cshrc
- Setting up environment: source project_env.csh
- Defining procedures: source myfunctions.csh

Startup Scripts:
On interactive startup, CSHW loads a startup file if present. It first looks
for %USERPROFILE%\.cshrc. If that file is missing, it falls back to
%APPDATA%\cshw\cshwrc.

Error Handling:
If an error occurs during sourcing, subsequent commands in the file
may still execute. Use 'exit' in the script if fatal errors should
stop execution.

Dot Command:
The '.' command is an alias for 'source' (UNIX tradition):
    . config.csh

See also

set, alias, library, exit

splash back to top ↑

show a modeless splash dialog during a long-running step

Synopsis

    splash [<mode> [<duration_ms>]]

Description

Puts up a modeless splash dialog and returns immediately, so the script
keeps running with the splash on top. Typical use: cover a long step
(downloads, init, build) so the user sees something other than a console.

Dismiss with `endsplash`, or wait for the timer when mode=timed.

Calling `splash` while one is already showing is a no-op.

The modeless splash ignores mouse clicks and the OK / close buttons --
only `endsplash` (or the timer, for mode=timed) dismisses it.

Options

    <mode>          One of:
                      splash    (default)  title + tagline
                      timed                same look; auto-dismisses
                                            after <duration_ms>
                      about | verbose | logo | none
    <duration_ms>   Only meaningful for mode=timed. Default 3000 ms.
                    The script does NOT wait for the timer to fire.

Examples

    splash
        Show the default splash. Dismiss with endsplash later.

    splash logo
        Show the logo variant.

    splash timed 5000
        Show for 5 seconds and auto-dismiss. Script continues immediately.

    splash
    # ... do long-running work ...
    endsplash

Exit status

    0       Success (or splash already showing -- treated as success).
    1       UI thread not available (non-interactive mode without it).

Notes

The modal counterpart is `testsplash` -- internal/dev-only and not
part of the public surface.

See also

endsplash, about, progressdlg, passworddlg

splitpath back to top ↑

print the components of a path, one per line

Synopsis

    splitpath <path>

Description

Split <path> into its individual directory/name components and print
each on its own line. Both forward slashes and backslashes are
recognized as separators.

Empty components -- from a leading separator or doubled separators --
and a leading drive specifier such as "C:" are skipped, so what comes
back is just the list of names.

This pairs naturally with foreach: the output drops straight into a
word list.

    foreach part (`splitpath C:\dir\subdir\file.txt`)
        echo $part
    end

splitpath is a pure text operation; it does not touch the filesystem.

Examples

    splitpath C:\dir\subdir\subdir2
        Prints three lines: dir, then subdir, then subdir2

    splitpath /usr/lib/file
        Prints three lines: usr, then lib, then file

Exit status

Zero on success. splitpath with no path argument is a usage error.

See also

basename, dirname, realpath

start back to top ↑

start a program or open a file

Synopsis

    start PROGRAM [ARGS...]
    start FILE
    start URL

Description

Starts a program in a new window, opens a document with its associated
application, or opens a URL in the default browser. The shell does not
wait for the program to complete.

Options

    PROGRAM         Program to execute.
    FILE            File to open with associated application.
    URL             Web address to open in browser.
    ARGS            Arguments to pass to the program.

    /min            Start window minimized.
    /max            Start window maximized.
    /wait           Wait for program to terminate.
    /b              Start without creating new window.
    /d PATH         Set starting directory.
    /i              Ignore environment changes.

Examples

    start notepad
        Open Notepad in new window.

    start notepad document.txt
        Open document in Notepad.

    start document.docx
        Open Word document (with associated app).

    start https://www.google.com
        Open URL in default browser.

    start /max excel report.xlsx
        Open Excel maximized with file.

    start /wait setup.exe
        Run installer and wait for completion.

    start /d "C:\Projects" cmd
        Open command prompt in specific directory.

    start /min background.exe
        Start program minimized.

    start "" "C:\Program Files\App\app.exe"
        Empty title needed when path has spaces.

Exit status

    0       Success (program started)
    1       Program/file not found
    2       Error starting program

Notes

New Window:
start creates a new window/process. The shell continues immediately
unless /wait is specified.

File Associations:
For documents, Windows opens the associated application:
- .docx -> Microsoft Word
- .pdf -> PDF reader
- .html -> Web browser

Path Spaces:
If the path contains spaces and you use a title, put the title first:
    start "My Title" "C:\Program Files\App.exe"

Without Title:
Use empty quotes for title if path has spaces:
    start "" "C:\Path With Spaces\program.exe"

Background Programs:
Use start for launching programs that should run independently
of the shell session.

See also

exec, sudo, jobs

stat back to top ↑

display file status information

Synopsis

    stat FILE...

Description

Displays detailed information about files including size, timestamps,
attributes, and owner. Provides more detail than dir for individual files.

Options

    FILE            One or more files to examine.

Examples

    stat document.txt
        Display full status of document.txt.

    stat *.exe
        Show status of all executables.

    stat "C:\Program Files"
        Examine a directory.

Exit status

    0       Success
    1       File not found
    2       Access denied

Notes

Information Displayed:
- Full path
- File size in bytes
- Creation time
- Last modification time
- Last access time
- File attributes (read-only, hidden, system, archive)
- Owner (if accessible)

Attributes:
R = Read-only
H = Hidden
S = System
A = Archive
D = Directory
L = Reparse point (symlink/junction)

Timestamps:
Windows maintains three timestamps per file. Access time updates
may be disabled on some systems for performance.

See also

dir, attrib, type

stop back to top ↑

suspend a running job

Synopsis

    stop %JOBID
    stop PID

Description

Suspends (pauses) a running job or process. The job remains in memory
but stops executing until resumed with 'bg' or 'fg'.

Options

    %JOBID          Job number from 'jobs' command (prefixed with %).
    PID             Process ID to suspend.

Examples

    stop %1
        Suspend job number 1.

    stop %2
        Suspend job number 2.

    jobs
        # [1]  Running     longprocess.exe
        # [2]  Running     another.exe
    stop %1
    jobs
        # [1]  Stopped     longprocess.exe
        # [2]  Running     another.exe

Exit status

    0       Success
    1       No such job
    2       Cannot stop job

Notes

Difference from Kill:
- stop: Pauses the process (can be resumed)
- kill: Terminates the process (cannot be resumed)

Resuming:
Use 'fg %JOBID' to resume in foreground.
Use 'bg %JOBID' to resume in background.

Interactive Stop:
Pressing Ctrl+Z in the terminal also stops the foreground process.

System Processes:
Some system processes cannot be stopped without Administrator
privileges.

See also

jobs, bg, fg, kill

strings back to top ↑

extract printable strings from files

Synopsis

    strings [options] FILE
    strings FILE

Description

Extracts and displays sequences of printable characters from files,
particularly useful for examining binary files. Finds text embedded
in executables, DLLs, and other binary formats.

Options

    FILE            File to examine.

    -n LENGTH       Minimum string length (default: 4).
    -a              Scan entire file (default).
    -t FORMAT       Print offset (d=decimal, o=octal, x=hex).

Examples

    strings program.exe
        Find strings in an executable.

    strings -n 10 binary.dat
        Find strings at least 10 characters long.

    strings -t x malware.exe
        Show strings with hex offsets.

    strings file.dll | grep -i password
        Search for password-related strings.

    strings *.exe | grep -i "http://"
        Find URLs in executables.

    strings image.jpg
        Find metadata text in images.

Exit status

    0       Success
    1       File not found
    2       Read error

Notes

Default Behavior:
By default, strings extracts ASCII sequences of 4+ characters.
This catches most meaningful text while filtering noise.

Security Analysis:
strings is valuable for malware analysis and reverse engineering.
It can reveal:
- Hardcoded URLs, IPs, filenames
- Error messages and debug strings
- Function names and API calls
- Embedded credentials (don't do this!)

Binary Analysis:
Combined with grep, strings is a quick way to search binary files
for specific patterns:
    strings malware.bin | grep -E 'http|ftp|password'

See also

hexdump, grep, file

sudo back to top ↑

run command as Administrator

Synopsis

    sudo COMMAND [ARGS...]

Description

Runs a command with elevated (Administrator) privileges. On Windows, this
triggers User Account Control (UAC) to request elevation. The command
runs in a new elevated process.

Options

    COMMAND         The command to run elevated.
    ARGS            Arguments to pass to the command.

Examples

    sudo notepad C:\Windows\System32\drivers\etc\hosts
        Edit hosts file (requires admin).

    sudo reg add HKLM\SOFTWARE\Test /v Key /d Value
        Modify HKLM registry (requires admin).

    sudo service start wuauserv
        Start Windows Update service.

    sudo netsh firewall show config
        View firewall configuration.

    sudo cmd /c "net user Administrator /active:yes"
        Enable Administrator account.

Exit status

    Returns the exit code of the elevated command, or:
    1       UAC cancelled by user
    2       Error launching elevated process

Notes

UAC Prompt:
Windows displays a User Account Control prompt asking for permission.
If denied, the command does not run.

New Window:
The elevated command typically runs in a new console window, as
Windows doesn't allow mixing elevation levels in one console.

When Needed:
Administrator rights are required for:
- Modifying system files
- HKEY_LOCAL_MACHINE registry changes
- Service management
- Network configuration
- Installing software system-wide

Already Elevated:
If the shell is already running as Administrator, sudo simply
runs the command normally.

Security:
Be cautious with sudo. Only elevate commands you trust and understand.

See also

service, reg, kill

suspend back to top ↑

manage system power state from the shell

Synopsis

    suspend
    suspend status
    suspend keepawake [on | off]
    suspend keepawake while DURATION

Description

suspend manages the system's power state. It does NOT pause shell
execution -- use 'sleep' for that.

The only state currently managed is "keepawake", which prevents the
system from going to sleep or hibernating while cshw is running. The
underlying mechanism is SetThreadExecutionState with the
ES_CONTINUOUS | ES_SYSTEM_REQUIRED | ES_AWAYMODE_REQUIRED flags,
refreshed by a background thread every fifteen seconds.

When cshw exits, the keepawake state is automatically released and
normal Windows power management resumes -- so even if you forget to
turn it off, the system goes back to its configured timeouts as soon
as you close the shell.

Options

    status                  Print 'keepawake: on' or 'keepawake: off'.
                            (Running 'suspend' alone is the same.)
    keepawake               With no further argument: print current
                            state. Same as 'status'.
    keepawake on            Start preventing system sleep / hibernation.
    keepawake off           Stop preventing system sleep / hibernation.
    keepawake while DUR     Turn keepawake on, sleep DUR (same syntax
                            as the sleep command), then restore the
                            previous keepawake state. Useful for "stay
                            awake for the next two hours then revert".

Examples

    suspend keepawake on
        Don't let the box sleep while cshw runs.

    suspend keepawake off
        Restore default power management.

    suspend keepawake while 2h
        Stay awake for two hours, then go back to whatever the
        keepawake state was before.

    suspend status
        Query: prints 'keepawake: on' or 'keepawake: off'.

Exit status

    0       Success.
    1       Syntax error (unknown subcommand, unknown argument,
            missing DURATION, or bad DURATION).

Notes

This is a runtime hint to the OS, not a registry change. It does the
same thing as the powercfg block:

    powercfg /change standby-timeout-ac 0
    powercfg /change standby-timeout-dc 0
    powercfg /change monitor-timeout-ac 0
    ...

except (a) it auto-restores when cshw exits, (b) it doesn't persist
across reboots, and (c) it doesn't require admin. It will not override
group policy on locked-down machines.

The 'suspend' command used to also pause the shell for a duration
(e.g. 'suspend 5 minutes'). That role has moved to 'sleep', which now
accepts unit suffixes ('sleep 5m'). 'suspend' with a bare number prints
a redirect message.

See also

sleep, timeout

tac back to top ↑

concatenate and print files in reverse line order

Synopsis

    tac [file...]
    tac [/reverse | --reverse]

Description

Reverse-order concatenation, the cat-spelled-backwards companion to
`cat`. With multiple files, tac reverses the FILE ORDER too (matches
GNU coreutils): `tac a b` prints b's lines reversed, then a's lines
reversed.

Internally, `tac` is `cat` with reverseDefault=true; it shares all
the cat infrastructure, so options that work for `cat` (line
numbering, BOM-aware encoding detection, etc.) work for `tac`.

Options

    /reverse, --reverse
        Cancel the default reversal -- effectively makes tac behave
        like cat for that one invocation. Mainly useful in scripts
        that conditionally choose tac or cat.

    file...
        Files to read. Reads stdin when none are given.

    See `man cat` for the full set of formatting flags (-n, -b, -s,
    -E, -T, -v, -A, -e, -t, -q, -u) -- all available for tac too.

Examples

    tac log.txt
        Print log.txt with the lines reversed.

    cat log.txt | tac
        Same effect via pipe.

    tac access.log error.log
        Reverses BOTH the line order AND the file order.

Exit status

    0       Success.
    1       File not found or I/O error.

See also

cat, rev, head, tail

tail back to top ↑

output the last part of files

Synopsis

    tail [options] FILE
    tail -n COUNT FILE
    command | tail [options]

Description

Outputs the last part of files or piped input. By default, prints the
last 10 lines. Essential for viewing log files and monitoring output.

Options

    FILE            File to read from.

    -n COUNT        Output the last COUNT lines (default: 10).
    -COUNT          Shorthand for -n COUNT (e.g., -20).

    -n +COUNT       Output starting from line COUNT (skip first COUNT-1 lines).

    -c COUNT        Output the last COUNT bytes instead of lines.

    -f, --follow    Keep file open and output new lines as they're appended.
                    Useful for monitoring log files. Press Ctrl+C to stop.

Examples

    tail file.txt
        Display last 10 lines of file.txt.

    tail -n 20 log.txt
        Display last 20 lines.

    tail -50 error.log
        Display last 50 lines (shorthand).

    tail -f access.log
        Monitor log file in real-time (follow mode).

    tail -n +5 data.txt
        Output everything starting from line 5.

    processlist | tail -n 5
        Show last 5 processes in list.

    tail -c 256 binary.dat
        Show last 256 bytes.

Exit status

    0       Success
    1       File not found
    2       Read error

Notes

Follow Mode:
The -f flag is particularly useful for monitoring log files. The shell
keeps the file open and displays new content as it's written. Use
Ctrl+C to exit follow mode.

Log Monitoring:
Common pattern for monitoring logs:
    tail -f /var/log/app.log | grep -i error

Line Selection:
Use -n +N to skip the first N-1 lines and output the rest. This is
useful for skipping headers:
    tail -n +2 data.csv    # Skip header row

See also

head, type, wc, grep

tar back to top ↑

archive files

Synopsis

    tar -c [-z] [-v] -f ARCHIVE FILES...
    tar -x [-z] [-v] -f ARCHIVE [-C DIR]
    tar -t [-v] -f ARCHIVE

Description

Creates, extracts, or lists the contents of tar archives. Supports both
plain tar and gzip-compressed (.tar.gz or .tgz) archives.

tar (tape archive) is the standard UNIX archive format. CSHW's tar
implementation provides core functionality for bundling files together.

Options

    Operation mode (one required):
    -c, --create    Create a new archive.
    -x, --extract   Extract files from archive.
    -t, --list      List archive contents.

    Modifiers:
    -f ARCHIVE      Specify archive filename (required).
    -z, --gzip      Use gzip compression/decompression.
    -v, --verbose   Verbose output (list files processed).
    -C DIR          Extract to directory DIR (with -x).

Examples

    tar -cvf backup.tar Documents/
        Create archive of Documents folder.

    tar -czvf backup.tar.gz Documents/
        Create gzip-compressed archive.

    tar -tvf backup.tar
        List contents of archive.

    tar -xvf backup.tar
        Extract archive in current directory.

    tar -xvf backup.tar -C /restore
        Extract to specific directory.

    tar -xzvf backup.tar.gz
        Extract gzip-compressed archive.

    tar -cvf project.tar *.cpp *.h Makefile
        Archive specific files.

Exit status

    0       Success
    1       Archive error (corrupt, not found)
    2       I/O error
    3       Invalid arguments

Notes

Archive Format:
CSHW's tar uses standard POSIX ustar format, compatible with other
tar implementations.

Gzip Compression:
The -z flag enables gzip compression. Files are typically named
.tar.gz or .tgz when compressed.

Permissions:
Windows doesn't have UNIX permissions. CSHW stores basic attributes
but permission bits may not be meaningful on Windows.

Long Filenames:
The ustar format supports filenames up to 255 characters. Longer
names may be truncated.

Symbolic Links:
Windows symbolic links (created with mklink) are archived as their
target paths.

Large Files:
Files up to 8GB are supported. Larger files require extended formats
not currently implemented.

See also

copy, mv, gzip

tc back to top ↑

time how long a command takes to run

Synopsis

    tc [/v] command [argument ...]

Description

Run a command and report how long it took. Everything after tc -- and
an optional leading /v switch -- is taken from the raw command line and
run fresh in the current shell, so the command keeps its own switches,
quoting, pipes, and redirection.

tc records a high-resolution timestamp before the command starts and
again after it finishes, then prints the elapsed wall-clock time in
seconds.

With /v (verbose), tc also prints the command line that ran and its
exit status.

tc is transparent: after it returns, $status and $? hold the exit
status of the command that ran, not tc's own -- so tc can be dropped in
front of any command without disturbing status checks or && / || chains.

The elapsed time is also stored, in seconds, in the shell variable
$timecount, so a script can read the measurement and act on it.

Examples

    tc sort big.txt
        Sorts the file, then prints e.g. "tc: 1.204 s".

    tc /v grep -r needle .
        Runs the recursive grep, then prints the command line, the
        elapsed time, and the exit status.

    tc sleep 2
        Prints roughly "tc: 2.001 s".

Exit status

The exit status is that of the timed command -- tc is transparent.
Running tc with no command is a usage error.

Notes

The elapsed time is wall-clock time, so it includes any time the
command spent waiting on I/O, other processes, or the system.

See also

eval, repeat

tcpclient back to top ↑

one-shot TCP client

Synopsis

    tcpclient <host> <port> [options]

Description

One-shot TCP client that connects to a server, optionally sends data,
optionally receives a response, and closes the connection.

This is a convenience command for simple request/response patterns.
For more complex interactions or persistent connections, use the
low-level socket command instead.

Options

    -4 | --ipv4
        Force IPv4. Errors out if the host can't be reached over IPv4.

    -6 | --ipv6
        Force IPv6. Errors out if the host can't be reached over IPv6.
        Quote IPv6 literals: tcpclient "::1" 8080

    /send:"data"
        Send the specified data after connecting.
        Quotes are optional but recommended for data with spaces.

    /recv
        Receive response data. Result is stored in $result.

    /timeout:ms
        Connection and receive timeout in milliseconds.
        Default is 5000 (5 seconds).

Family Selection

When neither -4 nor -6 is given, the family is auto-detected. A literal IP
address picks its own family. A hostname is resolved with the OS resolver
under AF_UNSPEC; whichever family it returns first wins (this honors the
system's preference rules, e.g. RFC 6724 / Windows source-address policy).

Examples

    # Check if a server is listening (connect test)
    tcpclient localhost 8080
    if $? == 0
        echo "Server is up"
    else
        echo "Server is down"
    endif

    # Send data and receive response
    tcpclient localhost 8080 /send:"hello" /recv
    echo "Response: $result"

    # HTTP GET request
    tcpclient example.com 80 /send:"GET / HTTP/1.0\r\nHost: example.com\r\n\r\n" /recv
    echo $result

    # With custom timeout
    tcpclient slow-server.com 8080 /timeout:30000 /recv

    # Check website availability
    tcpclient google.com 443
    if $? == 0
        echo "Google is reachable"
    endif

Notes

Escape Sequences:
    Use \r\n for carriage return + line feed (HTTP requires this).
    Example: "GET / HTTP/1.0\r\n\r\n"

HTTPS:
    This command does not support SSL/TLS. For HTTPS, use the
    fetch command instead.

Response Handling:
    The command waits for the connection to close or timeout before
    returning all received data. For streaming responses, use the
    low-level socket commands.

Exit status

    0       Success
    >0      Connection failed, timeout, or error

See also

tcpserver, socket, fetch

tcpserver back to top ↑

start a TCP server

Synopsis

    tcpserver <port> <handler_proc> [options]

Description

Starts a TCP server that listens on the specified port and calls a
handler procedure for each incoming connection.

The server creates a socket, binds to the port, and enters an accept
loop. For each accepted connection, it calls the handler procedure
with the client socket ID as an argument.

By default, the server runs indefinitely. Use /max or /timeout to limit.

Options

    -4 | --ipv4
        Bind the IPv4 wildcard 0.0.0.0 (default).

    -6 | --ipv6
        Bind the IPv6 wildcard ::. By default this listens IPv6-only;
        accepted clients must reach the server over IPv6.

    --dual
        Bind ::, but clear IPV6_V6ONLY so the same socket accepts both
        IPv6 and IPv4 clients. Implies -6; conflicts with -4.

    --keep-mapped
        With --dual, v4 peers normally appear as plain a.b.c.d in
        'socket info' and the accepted socket's family is reported as
        IPv4. Pass --keep-mapped to leave the on-the-wire ::ffff:a.b.c.d
        form intact and report the family as IPv6 instead.

    /max:N
        Accept at most N connections, then exit.

    /timeout:ms
        Stop after timeout milliseconds with no new connections.

    /once
        Same as /max:1 - accept one connection and exit.

Handler Procedure

The handler procedure receives the client socket ID as its first argument.
The procedure is responsible for:
  - Reading from the socket (socket recv)
  - Writing to the socket (socket send)
  - Closing the socket when done (socket close)

Example handler:
    proc echo_handler(sock)
        socket recv $sock
        socket send $sock $result
        socket close $sock
    endproc

Examples

    # Echo server - returns whatever client sends
    proc echo_handler(sock)
        socket recv $sock
        socket send $sock $result
        socket close $sock
    endproc
    tcpserver 8080 echo_handler

    # HTTP server example
    proc http_handler(sock)
        socket recv $sock
        socket send $sock "HTTP/1.1 200 OK\r\nContent-Length: 13\r\n\r\nHello, World!"
        socket close $sock
    endproc
    tcpserver 80 http_handler

    # Accept only 10 connections
    tcpserver 8080 handler /max:10

    # Accept one connection (useful for testing)
    tcpserver 8080 handler /once

    # Run server in background using coroutine
    corunproc tcpserver 8080 handler
    echo "Server started in background"

Notes

Running in Background:
    To run the server in the background, use corunproc:
        corunproc tcpserver 8080 myHandler
    The server will run in a separate coroutine while you continue
    working in the shell.

Port Reuse:
    The server sets SO_REUSEADDR to allow quick restarts without
    waiting for TIME_WAIT to expire.

Exit status

    0       Success (server exited normally)
    >0      Error (bind failed, listen failed, etc.)

See also

tcpclient, socket, corunproc

tee back to top ↑

read from stdin and write to stdout and files

Synopsis

    command | tee FILE
    command | tee FILE1 FILE2...
    command | tee [options] FILE

Description

Reads from standard input and writes to both standard output AND one or
more files. Like a "T" pipe fitting that splits the data flow.

Options

    FILE            File(s) to write to.

    -a, --append    Append to files instead of overwriting.
    -i, --ignore-interrupts
                    Ignore interrupt signals.

Examples

    dir | tee listing.txt
        Display dir output AND save to file.

    build.bat | tee build.log
        Show build output while logging.

    command | tee file1.txt file2.txt
        Write to multiple files.

    command | tee -a log.txt
        Append to existing log.

    longprocess | tee output.log | grep ERROR
        Log everything, display only errors.

    tar -cvf - src/ | tee backup.tar | md5sum
        Create archive and compute checksum simultaneously.

Exit status

    0       Success
    1       Write error

Notes

Non-Destructive Piping:
Without tee, you choose either viewing OR saving:
    command > file     # Saved but not displayed
    command            # Displayed but not saved
    command | tee file # Both!

Multiple Outputs:
tee can write to multiple files simultaneously:
    command | tee log1.txt log2.txt log3.txt

Pipeline Position:
tee is typically in the middle of a pipeline:
    producer | tee file | consumer

Append Mode:
Use -a to add to existing files rather than overwriting:
    status_check | tee -a daily.log

Real-Time Output:
Output appears in real-time, not after completion.

See also

type, echo, grep

test back to top ↑

evaluate a conditional expression

Synopsis

    test <expression>
    [ <expression> ]

Description

Evaluate <expression> and report the result as the exit status: 0 when
the expression is true, 1 when it is false, and 2 when the expression
is malformed. test produces no output on success -- it exists to drive
the && / || operators and $status checks.

`[` is an alias for test that requires a closing `]` as its final
argument, so these two lines are equivalent:

    test -f config.txt
    [ -f config.txt ]

String tests:
    -z STR          true if STR is empty
    -n STR          true if STR is non-empty
    STR             true if STR is non-empty (one-argument form)
    STR1 = STR2     true if the strings are equal (== is also accepted)
    STR1 != STR2    true if the strings differ

Integer tests (operands are compared numerically):
    N1 -eq N2       equal             N1 -ne N2   not equal
    N1 -lt N2       less than         N1 -le N2   less or equal
    N1 -gt N2       greater than      N1 -ge N2   greater or equal

File tests:
    -e PATH         PATH exists
    -f PATH         PATH exists and is a regular file
    -d PATH         PATH exists and is a directory
    -s PATH         PATH exists and is not empty
    -r PATH         PATH is readable
    -w PATH         PATH is writable
    -x PATH         PATH is executable

Negation:
    ! EXPR          true if EXPR is false

To combine conditions, use the shell's own && and || between separate
test invocations rather than -a / -o.

Examples

    test -f settings.cshw && source settings.cshw

    [ -n "$name" ] && echo "hello, $name"

    test $count -gt 10
    if ($status != 0) echo "too many"

Exit status

0 if the expression is true, 1 if false, 2 if it is malformed.

See also

if, true, false

testsplash back to top ↑

[INTERNAL] exercise the splash dialog in a chosen mode

Synopsis

    testsplash [<mode> [<duration_ms>]]

Description

INTERNAL / DEV-ONLY command. Not part of the public cshw command
surface. Exists so developers can exercise every mode of the modal
splash dialog during development.

For scripted use, see the public `splash` command (modeless,
script-friendly lifecycle).

Options

    Same mode set as `splash`. See `man splash` for the list.

Notes

The name is deliberately awkward to discourage scripting use. If
you reach for this in a real script, you almost certainly want
`splash` + `endsplash` instead.

See also

splash, endsplash

time back to top ↑

measure command execution time

Synopsis

    time COMMAND [ARGS...]

Description

Executes a command and reports the time taken to complete. Shows real
(wall-clock) time, user CPU time, and system CPU time.

Options

    COMMAND         Command to execute and time.
    ARGS            Arguments for the command.

Examples

    time dir /s
        Time a recursive directory listing.

    time find . -name "*.cpp"
        Time a file search.

    time sort largefile.txt > sorted.txt
        Time a sort operation.

    time build.bat
        Time a build script.

Exit status

    Returns the exit code of the timed command.

Notes

Output Format:
    real    0m1.234s    # Wall-clock time
    user    0m0.567s    # CPU time in user mode
    sys     0m0.123s    # CPU time in kernel mode

Real vs CPU Time:
- Real: Actual elapsed time (includes I/O waits)
- User: CPU time executing your code
- Sys: CPU time in system calls

Performance Analysis:
- High real, low CPU: I/O bound (waiting for disk/network)
- High CPU, matches real: CPU bound (computation)

Multicore:
User+sys can exceed real if multiple cores are used.

Precision:
Timing precision depends on Windows timer resolution, typically
around 15.6ms on desktop Windows.

Scripts:
Useful for identifying slow operations in scripts or comparing
different approaches.

See also

timeout, sleep, suspend

timeout back to top ↑

run command with time limit

Synopsis

    timeout DURATION COMMAND [ARGS...]
    timeout [options] DURATION COMMAND

Description

Runs a command and kills it if it doesn't complete within the specified
time limit. Useful for commands that might hang or take too long.

Options

    DURATION        Time limit (seconds, or with suffix: s/m/h).
    COMMAND         Command to run.
    ARGS            Arguments for the command.

    -s SIGNAL       Signal to send on timeout (default: KILL).
    -k DURATION     Kill with SIGKILL after DURATION if still running.
    --preserve-status
                    Exit with command's status even on timeout.

Examples

    timeout 30 ping server.com
        Run ping for max 30 seconds.

    timeout 5m build.bat
        Allow 5 minutes for build.

    timeout 1h longprocess.exe
        1 hour limit.

    timeout 10 curl https://slow-server.com/file
        Kill download if it takes over 10 seconds.

    timeout 60 script.bat || echo "Timed out!"
        Handle timeout case.

Exit status

    124     Command timed out
    125     timeout command failed
    126     Command found but not executable
    127     Command not found
    Other   Command's exit status (if completed)

Notes

Time Units:
    30      30 seconds
    30s     30 seconds
    5m      5 minutes
    1h      1 hour

Graceful Termination:
By default, timeout sends a termination request. Use -k to ensure
the process is killed if it ignores the request.

Use Cases:
- Network commands that might hang
- Build processes with time limits
- Automated testing with deadlines
- CI/CD pipeline steps

Scripting:
Check exit code 124 to detect timeouts:
    timeout 10 command
    if ($? == 124)
        echo "Command timed out"
    endif

See also

time, kill, watch

title back to top ↑

set or display the console window title

Synopsis

    title [text ...]

Description

Sets the console window title to the given text. With no arguments,
prints the current title to stdout and stores it in $result.

When multiple positional arguments are supplied, they are joined with
spaces before being applied.

Examples

    title
        Print the current title.

    title "Build server"
        Set the title to "Build server".

    title cshw -- backup running
        Sets title to "cshw -- backup running" (positional join).

Exit status

    0       Always.

See also

prompt, say

tokenize back to top ↑

display parsed tokens from input

Synopsis

    tokenize LINE
    tokenize "COMMAND WITH ARGS"

Description

Parses a command line and displays the tokens identified by the lexer.
Useful for debugging command parsing, understanding how the shell
interprets input, and developing shell scripts.

Options

    LINE            Text to tokenize.

Examples

    tokenize "echo hello world"
        # Token 0: Identifier "echo"
        # Token 1: Identifier "hello"
        # Token 2: Identifier "world"

    tokenize "set x=42"
        # Token 0: Identifier "set"
        # Token 1: Identifier "x"
        # Token 2: Operator "="
        # Token 3: Number "42"

    tokenize 'grep -i "pattern" file.txt'
        # Shows how quotes and switches are parsed

    tokenize "dir /s /b *.txt"
        # Token 0: Identifier "dir"
        # Token 1: Switch "/s"
        # Token 2: Switch "/b"
        # Token 3: Identifier "*.txt"

Exit status

    0       Success

Notes

Token Types:
- Identifier: Commands, filenames, arguments
- String: Quoted text
- Number: Numeric values
- Operator: =, |, <, >, etc.
- Switch: /x or -x style options
- Variable: $name references

Debugging:
tokenize helps understand:
- How quotes are handled
- Where words are split
- How special characters are interpreted

Parser Development:
Essential tool when developing or debugging shell scripts that
depend on specific parsing behavior.

See also

echo, set

touch back to top ↑

change file timestamps or create empty files

Synopsis

    touch FILE...
    touch [options] FILE...

Description

Updates the access and modification times of files to the current time.
If a file doesn't exist, touch creates an empty file with that name.

touch is commonly used to create empty files or to update timestamps
for build systems that depend on file modification times.

Options

    FILE            File(s) to touch.

    -a              Change only access time.
    -m              Change only modification time.
    -c, --no-create Do not create files that don't exist.
    -t TIMESTAMP    Use specified time instead of current time.
                    Format: [[CC]YY]MMDDhhmm[.ss]

Examples

    touch newfile.txt
        Create empty file or update existing file's timestamp.

    touch file1.txt file2.txt file3.txt
        Touch multiple files.

    touch -c maybeexists.txt
        Update timestamp only if file exists.

    touch -m important.dat
        Update only modification time.

    touch *.cpp
        Update timestamps on all C++ source files.

Exit status

    0       Success
    1       Cannot create file (permission denied)
    2       Invalid arguments

Notes

Creating Files:
touch is the standard way to create empty files in a shell. It's
cleaner than "echo. > file" or similar.

Build Systems:
touch is useful for forcing rebuilds in make-based systems by
updating source file timestamps.

Timestamps:
Windows files have creation, modification, and access times. touch
primarily updates modification and access times.

See also

stat, dir, type

tr back to top ↑

translate or delete characters

Synopsis

    tr SET1 SET2
    tr -d SET1
    command | tr SET1 SET2

Description

Translates, squeezes, or deletes characters from standard input, writing
to standard output. Useful for character substitution and cleanup.

Options

    SET1            Source character set.
    SET2            Replacement character set.

    -d, --delete    Delete characters in SET1 (no replacement).
    -s, --squeeze   Replace repeated characters with single occurrence.
    -c, --complement
                    Use complement of SET1.

    Character classes:
    [:alnum:]       Letters and digits
    [:alpha:]       Letters
    [:digit:]       Digits
    [:lower:]       Lowercase letters
    [:upper:]       Uppercase letters
    [:space:]       Whitespace
    [:punct:]       Punctuation

Examples

    echo "hello" | tr a-z A-Z
        Convert to uppercase: HELLO

    echo "HELLO" | tr A-Z a-z
        Convert to lowercase: hello

    echo "hello   world" | tr -s ' '
        Squeeze spaces: "hello world"

    echo "abc123" | tr -d '0-9'
        Delete digits: abc

    echo "hello" | tr 'aeiou' '12345'
        Replace vowels: h2ll4

    type file.txt | tr '\r\n' '\n'
        Convert Windows to Unix line endings.

    echo "a,b,c" | tr ',' '\n'
        Replace commas with newlines.

    echo "hello world" | tr -d ' '
        Remove all spaces: helloworld

    type file.txt | tr -d '\r'
        Remove carriage returns.

    echo "hello" | tr -c 'aeiou' '_'
        Replace non-vowels: _e__o

Exit status

    0       Success
    1       Error

Notes

Character Ranges:
- a-z: Lowercase letters
- A-Z: Uppercase letters
- 0-9: Digits

Special Characters:
- \n: Newline
- \r: Carriage return
- \t: Tab
- \\: Backslash

One-to-One Mapping:
Characters in SET1 map to corresponding positions in SET2.
If SET2 is shorter, its last character is repeated.

Common Uses:
- Case conversion
- Removing unwanted characters
- Line ending conversion
- Character substitution

See also

cut, sed, grep

true back to top ↑

succeed or fail with no side effects

Synopsis

    true
    false
    nop

Description

Three minimal commands that perform no work and only affect $status:

    true    Sets $status to 0 (success).
    false   Sets $status to 1 (failure).
    nop     Identical to true. A no-op placeholder; succeeds.

`nop` is dispatcher-aliased to `true` and shares the same handler.
Comment lines starting with `#` are discarded by the lexer before
dispatch, so they neither run nor touch $status.

Useful in shell constructs that require a command but where you
want a guaranteed success/failure, as a placeholder in empty
branches, or to deliberately seed $status before a conditional.

Examples

    true
        Succeed. $status = 0.

    false
        Fail. $status = 1.

    nop
        Same as true. Useful as a placeholder.

    if ($condition)
        nop         # explicit no-op in the empty branch
    else
        # ...
    endif

    proc always_fail
        false
    endproc

Exit status

    true, nop       0       Always.
    false           1       Always.

Notes

true vs nop:
Functionally identical -- both succeed without side effects. true is
the conventional Unix name; nop is the legacy cshw spelling. Both
remain registered and point at the same handler.

Comments:
The `#` prefix is recognized by the lexer (lexer.cpp:111) and the
rest of the line is consumed without emitting any token. Inline
comments (`echo hi # trailing`) work the same way. `#` never
reaches the dispatcher.

See also

exit

type back to top ↑

display file contents

Synopsis

    type FILE...
    type FILE | command

Description

Displays the contents of one or more files to standard output. Similar to
the UNIX 'cat' command, type is used for viewing file contents, concatenating
files, and feeding file contents into pipelines.

When multiple files are specified, their contents are displayed sequentially,
effectively concatenating them.

Options

    FILE            One or more files to display.

Examples

    type readme.txt
        Display contents of readme.txt.

    type file1.txt file2.txt
        Display contents of both files sequentially.

    type log.txt | grep error
        Pipe file contents to grep for filtering.

    type config.ini | head 20
        Show first 20 lines of a config file.

    type *.txt
        Display contents of all text files.

    type data.csv | wc -l
        Count lines in a CSV file.

    type script.csh | grep "proc "
        Find procedure definitions in a script.

Exit status

    0       Success
    1       File not found
    2       Access denied or read error

Notes

Binary Files:
Type is designed for text files. Displaying binary files will produce
garbled output and may affect your terminal.

Large Files:
For large files, consider using 'head' or 'tail' to view portions, or
pipe through 'grep' to find specific content.

Encoding:
CSHW's type command handles UTF-8 and UTF-16 encoded files automatically.
For other encodings, output may appear incorrect.

Piping:
Type is frequently used as the start of a pipeline to feed file contents
into other commands like grep, sort, wc, etc.

See also

head, tail, grep, wc, copy

umask back to top ↑

set file creation mode mask

Synopsis

    umask
    umask MASK

Description

Displays or sets the file creation mode mask. The umask value is subtracted
from the default permissions when creating new files.

On Windows, umask has limited effect since Windows uses ACLs rather than
UNIX-style permissions.

Options

    MASK            Octal permission mask (e.g., 022, 077).

Examples

    umask
        Display current umask value.

    umask 022
        Common umask: files 644, directories 755.

    umask 077
        Restrictive: only owner can access new files.

    umask 002
        Group-friendly: files 664, directories 775.

Exit status

    0       Success

Notes

How umask Works:
Default permissions minus umask equals actual permissions.
    File default:      666 (rw-rw-rw-)
    umask:             022
    Result:            644 (rw-r--r--)

    Directory default: 777 (rwxrwxrwx)
    umask:             022
    Result:            755 (rwxr-xr-x)

Common Values:
    022     Standard user (owner full, others read)
    077     Private (owner only)
    002     Collaborative (group full)
    000     No mask (full permissions)

Windows Limitations:
Windows doesn't use UNIX permissions natively. umask affects:
- Files created by POSIX-compatible operations
- Cygwin/MSYS interoperability
- Cross-platform script behavior

Persistence:
umask affects only the current shell. Set in startup scripts for
persistence.

See also

chmod, chown, touch

unalias back to top ↑

remove command aliases

Synopsis

    unalias NAME
    unalias NAME...
    unalias -a

Description

Removes one or more previously defined command aliases. After removal,
the alias name will no longer expand to its defined command.

Options

    NAME            Alias name(s) to remove.
    -a, --all       Remove all defined aliases.

Examples

    unalias ll
        Remove the 'll' alias.

    unalias ll la ls
        Remove multiple aliases.

    unalias -a
        Remove all aliases.

    alias g=grep
    g pattern file.txt    # Works
    unalias g
    g pattern file.txt    # Error: g not found

Exit status

    0       Success
    1       Alias not found

Notes

Non-existent Aliases:
Removing an alias that doesn't exist may produce a warning but
is not a fatal error.

Persistence:
Like aliases, unalias changes only affect the current session.
To permanently remove an alias, edit your startup script.

Restoring Commands:
If you aliased over a built-in command, unalias restores access
to the original command.

See also

alias, set, unset

uname back to top ↑

print system information

Synopsis

    uname
    uname [options]

Description

Displays system information including operating system name, version,
machine architecture, and more. Provides UNIX-compatible system
identification on Windows.

Options

    -a, --all       Print all information.
    -s, --kernel-name
                    Print operating system name.
    -n, --nodename  Print network node hostname.
    -r, --kernel-release
                    Print kernel/OS release.
    -v, --kernel-version
                    Print kernel/OS version.
    -m, --machine   Print machine hardware name (architecture).
    -p, --processor Print processor type.
    -o, --operating-system
                    Print operating system name.

Examples

    uname
        Print OS name (Windows_NT).

    uname -a
        Print all system information.

    uname -m
        Print architecture (x86_64 or ARM64).

    uname -r
        Print OS version/build.

    uname -n
        Print computer name.

Exit status

    0       Success

Notes

Output Format:
With -a, output is: OS nodename release version machine processor

Windows Values:
- OS: Windows_NT
- Machine: x86_64 (AMD64) or ARM64
- Release: Windows version (e.g., 10.0.19045)

Cross-Platform Scripts:
uname allows scripts to detect the operating system:
    if ($(uname -s) == "Windows_NT")
        echo "Running on Windows"
    endif

Comparison:
- uname: UNIX-style system info
- winver: Windows-specific version details
- version: CSHW shell version

See also

winver, version, whoami

unbindevent back to top ↑

remove a window event binding

Synopsis

    unbindevent <hwnd> <kind> [<args>]

Description

Removes a binding previously installed by `bindevent`. The kind and
per-kind args identify which binding to remove (same key shape as
`bindevent`). Removing a binding that doesn't exist is a clean no-op.

Options

    <hwnd>      Target HWND. (IsWindow() is NOT required here -- removing
                a binding from a destroyed window is allowed.)
    <kind>      Same kinds as `bindevent`. Per-kind args identify
                command/notify/timer/keydown bindings; close/destroy/
                lbutton/size take no extras.

Examples

    unbindevent $w command 100
    unbindevent $w close
    unbindevent $w keydown 27         # remove the Esc-key handler

Exit status

    0       Success (including the no-op case).
    1       Bad HWND syntax, unknown kind, or missing args.

See also

bindevent, createwindow

uncomplete back to top ↑

remove tab completion rules

Synopsis

    uncomplete COMMAND
    uncomplete COMMAND...

Description

Removes custom tab completion rules for commands, reverting to default
file completion behavior.

Options

    COMMAND         Command(s) to remove completion rules for.

Examples

    uncomplete cd
        Remove custom cd completion.

    uncomplete git svn hg
        Remove completion for multiple commands.

    complete cd d
    # Tab after cd shows only directories
    uncomplete cd
    # Tab after cd now shows files too

Exit status

    0       Success
    1       No rule defined for command

Notes

Effect:
After uncomplete, the command uses default file completion.

Use Cases:
- Reset unwanted completion behavior
- Debug completion issues
- Temporarily disable custom completion

See also

complete, alias

unfileblob back to top ↑

decode a fileblob back into a file

Synopsis

    unfileblob [blob] [outfile]

Description

unfileblob reverses fileblob: it takes a CSHWBLOB1 text blob and writes
the decoded bytes back out as a file.

The blob may be supplied as an argument -- typically a shell variable
holding one -- or piped in on standard input. If <outfile> is given it
is used as the destination; otherwise the original filename embedded in
the blob is used.

Examples

    unfileblob "$logo" icon.png
        Decode a blob held in a variable to a named file.

    unfileblob < icon.blob
        Decode a saved blob file, restoring the original filename.

Exit status

0 on success; non-zero if the input is not a valid fileblob or the
output file cannot be written.

See also

fileblob, base64

unhash back to top ↑

remove command from hash table

Synopsis

    unhash COMMAND
    unhash COMMAND...

Description

Removes one or more commands from the hash table cache. Next time the
command is run, the shell will search PATH to find it.

Options

    COMMAND         Command name(s) to remove from cache.

Examples

    unhash python
        Remove python from cache.

    unhash git python node
        Remove multiple commands.

    # After replacing a program with new version:
    unhash myprogram
    myprogram   # Now finds the new version

Exit status

    0       Success
    1       Command not in hash table

Notes

Use Cases:
- Force shell to find updated program location
- Clear cache for specific command
- Debug command resolution issues

vs rehash:
- unhash: Removes specific entries
- rehash: Rebuilds entire table

After unhash, the command is looked up in PATH on next execution
and potentially re-added to the hash.

See also

rehash, hashstat, which

uniq back to top ↑

report or filter out repeated lines

Synopsis

    uniq [options] [FILE]
    sort FILE | uniq

Description

Filters adjacent matching lines from input. Typically used after sort
to remove or count duplicate lines.

Note: uniq only removes ADJACENT duplicates. Sort input first to remove
all duplicates, or use 'sort -u'.

Options

    FILE            File to process (default: stdin).

    -c, --count     Prefix lines with occurrence count.
    -d, --repeated  Only print duplicate lines.
    -u, --unique    Only print unique lines (appears once).
    -i, --ignore-case
                    Ignore case when comparing.

Examples

    sort names.txt | uniq
        Remove all duplicate lines.

    uniq -c sorted.txt
        Count occurrences of each line.

    sort data.txt | uniq -d
        Show only duplicated lines.

    sort data.txt | uniq -u
        Show only lines that appear once.

    dir /b | sort | uniq
        List unique filenames.

    type log.txt | grep ERROR | sort | uniq -c
        Count unique error messages.

Exit status

    0       Success
    1       Error

Notes

Important: Sort First!
uniq only compares adjacent lines. To remove all duplicates:
    sort file.txt | uniq

Or use: sort -u file.txt

Counting:
The -c option is useful for frequency analysis:
    cat access.log | cut -d' ' -f1 | sort | uniq -c | sort -rn

See also

sort, wc, grep

unlimit back to top ↑

remove resource limits

Synopsis

    unlimit RESOURCE
    unlimit

Description

Removes resource limits, setting them to unlimited (or the system maximum).
Without arguments, removes all limits.

Options

    RESOURCE        Specific resource to unlimit (see 'limit' for list).

Examples

    unlimit filesize
        Remove file size limit.

    unlimit
        Remove all limits.

    unlimit memoryuse
        Remove memory limit.

Exit status

    0       Success
    1       Unknown resource
    2       Permission denied (can't raise hard limit)

Notes

Hard Limits:
You can only raise limits up to the hard limit set by the system
or administrator. Raising hard limits requires privileges.

Caution:
Removing limits allows processes to consume unlimited resources,
potentially affecting system stability.

Use Cases:
- Allow large file processing
- Remove constraints for trusted operations
- Reset to defaults

See also

limit, nice, time

unregistercmdlib back to top ↑

unregister command library (unload plugin DLL)

Synopsis

    unregistercmdlib PATH|NAME|PREFIX
    unregistercmdlib /all
    urcl PATH|NAME|PREFIX
    urcl /all

Description

Alias for urcl. See 'man urcl' for full documentation.

See also

urcl, rcl, cmdliblist

unset back to top ↑

remove shell variables

Synopsis

    unset NAME
    unset NAME...

Description

Removes one or more shell variables from the current environment. After
unsetting, the variable is no longer defined and references to it will
return empty values.

Options

    NAME            One or more variable names to remove.

Examples

    unset count
        Remove the variable 'count'.

    unset var1 var2 var3
        Remove multiple variables.

    set temp="temporary"
    echo $temp
    unset temp
    echo $temp
        # Second echo outputs nothing

Exit status

    0       Success
    1       Variable not found (may still succeed)

Notes

Non-existent Variables:
Unsetting a variable that doesn't exist is not an error.

Environment Variables:
unset removes shell variables. To remove environment variables,
use 'unsetenv' instead.

Special Variables:
Some special variables ($?, $:, $$) cannot be unset as they are
managed by the shell.

Scope:
unset only affects variables in the current shell scope. Variables
in parent or child processes are not affected.

See also

set, unsetenv, vartype

unsetenv back to top ↑

remove environment variable

Synopsis

    unsetenv NAME
    unsetenv NAME...

Description

Removes one or more environment variables from the current process
environment. Child processes will not inherit the removed variables.

Options

    NAME            Environment variable name(s) to remove.

Examples

    unsetenv DEBUG
        Remove DEBUG variable.

    unsetenv TEMP_VAR MY_CONFIG
        Remove multiple variables.

    setenv TEST_VAR "hello"
    echo %TEST_VAR%
    unsetenv TEST_VAR
    echo %TEST_VAR%
        # Second echo shows empty

Exit status

    0       Success
    1       Error

Notes

System Variables:
Some system variables (PATH, SYSTEMROOT, etc.) should not be
unset as they may affect system operation.

Scope:
unsetenv only affects the current process and its future children.
It does not affect:
- The parent process
- Other running programs
- System environment (permanent settings)

Verification:
Use 'env' or 'printenv' to verify the variable was removed.

See also

setenv, unset, env, printenv

unzip back to top ↑

extract or list a .zip archive

Synopsis

    unzip [/l] [/d:<dir>] [/p[:<password>]] <archive.zip>

Description

Extract a .zip archive, or list its contents without extracting.
Supports password-encrypted archives via /p.

Options

    /l, /list, --list
        List archive contents instead of extracting. Prints entry
        names, sizes, and last-modified timestamps.

    /d:<dir>, --dest:<dir>
        Extract into <dir> rather than the current directory. The
        directory is created if it doesn't exist.

    /p[:<password>]
        Password for encrypted archives. Bare /p prompts on the
        console; /p:<value> uses the literal password.

    <archive.zip>
        Archive to extract or list.

Examples

    unzip backup.zip
        Extract everything into the current directory.

    unzip /l backup.zip
        List archive contents.

    unzip /d:out backup.zip
        Extract into out/.

    unzip /p:s3cret secret.zip
        Extract a password-protected archive.

Exit status

    0       Extraction or listing succeeded.
    1       Bad arguments, archive not found, wrong password, or I/O error.

See also

zip, tar

uptime back to top ↑

show how long system has been running

Synopsis

    uptime

Description

Displays the current time, how long the system has been running, and
system load information.

Examples

    uptime
        Display system uptime.

Exit status

    0       Success

Notes

Output includes:
- Current time
- Time since last boot (days, hours, minutes)
- Number of logged-in users (if available)

Windows Uptime:
On Windows, uptime is calculated from the system boot time.
This can also be viewed in Task Manager's Performance tab.

Long Uptimes:
Servers often have uptimes measured in weeks or months. Desktops
typically restart more frequently for updates.

See also

uname, processlist, df

urcl back to top ↑

unregister command library (unload plugin DLL)

Synopsis

    urcl PATH|NAME|PREFIX
    urcl /all
    unregistercmdlib PATH|NAME|PREFIX
    unregistercmdlib /all

Description

Unloads a previously registered command library and removes all its
commands from the shell.

The library can be identified by its DLL path, library name, or
namespace prefix.

If the library had shadowed any intrinsic commands, those built-in
commands are restored when the library is unloaded.

The plugin's UnregisterCommandLibrary function is called (if exported)
to allow cleanup before the DLL is freed from memory.

Options

    PATH|NAME|PREFIX    Identify library by DLL path, name, or prefix.
    /all                Unload all command libraries.
    /a                  Short form of /all.

Examples

    urcl mylib
        Unload library by its prefix or name.

    urcl C:\Plugins\mylib.dll
        Unload library by its DLL path.

    urcl /all
        Unload all loaded command libraries.

Exit status

    0       Success
    1       Library not found

Notes

Cleanup:
Before unloading, the shell calls UnregisterCommandLibrary if the
DLL exports it. Use this to release resources, close handles, etc.

Restoration:
If the library had shadowed built-in commands (e.g., provided its
own "echo" command), the original intrinsic commands are automatically
restored when the library is unloaded.

Order:
When unloading all libraries with /all, they are unloaded in
arbitrary order. Design plugins to not depend on unload order.

See also

rcl, cmdliblist

vartype back to top ↑

display variable type

Synopsis

    vartype NAME
    vartype $NAME

Description

Displays the data type of a shell variable. CSHW automatically tracks
variable types based on assigned values, supporting strings, integers,
and floating-point numbers.

Options

    NAME            Variable name to examine (with or without $).

Examples

    set count=42
    vartype count
        # Output: integer

    set name="John"
    vartype name
        # Output: string

    set pi=3.14159
    vartype pi
        # Output: float

    set hex=0xFF
    vartype hex
        # Output: integer

Exit status

    0       Success
    1       Variable not found

Notes

Type Inference:
CSHW infers types automatically:
- Integer: whole numbers (42, -17, 0xFF, 0b1010)
- Float: numbers with decimals (3.14) or exponents (1e-3)
- String: everything else

Type Conversion:
Variables can change type when reassigned:
    set x=42        # integer
    set x="hello"   # now string

Type in Expressions:
Type matters in expressions. String comparisons use lexicographic
order, numeric comparisons use numeric order.

See also

set, unset, echo

ver back to top ↑

display shell version (alias for version)

Synopsis

    ver

Description

`ver` is identical to `version`. See `man version` for details.

See also

version, about, winver

version back to top ↑

display shell version

Synopsis

    version
    ver

Description

Aliases: ver

Displays the CSHW shell version number and build information.

Examples

    version
        Display shell version.

    ver
        Short form (alias for version).

Exit status

    0       Success (always)

Notes

The version command shows the CSHW version. For Windows version
information, use 'winver' instead.

See also

winver, uname

watch back to top ↑

execute command periodically

Synopsis

    watch COMMAND
    watch -n INTERVAL COMMAND
    watch [options] COMMAND

Description

Executes a command repeatedly at regular intervals, displaying the output.
Useful for monitoring changes over time. Press Ctrl+C to stop.

Options

    COMMAND         Command to execute repeatedly.

    -n INTERVAL     Seconds between executions (default: 2).
    -d, --differences
                    Highlight differences between updates.
    -t, --no-title  Don't show header with time and command.
    -e, --errexit   Exit on command error.

Examples

    watch dir
        Monitor directory changes every 2 seconds.

    watch -n 5 processlist
        Show process list every 5 seconds.

    watch -n 10 df
        Monitor disk space every 10 seconds.

    watch -d "dir /b"
        Highlight file changes.

    watch -n 1 "type log.txt | tail -10"
        Monitor last 10 lines of log.

    watch "grep ERROR log.txt | wc -l"
        Count errors continuously.

Exit status

    0       Exited normally (Ctrl+C)
    1       Error running command
    2       Invalid arguments

Notes

Display:
watch clears the screen and shows fresh output each interval.
The header shows current time and the command being run.

Quoted Commands:
For commands with pipes or multiple arguments, use quotes:
    watch "ps | grep python"

Interval:
Minimum interval is typically 0.1 seconds. Very short intervals
can cause high CPU usage.

Use Cases:
- Monitor log files for new entries
- Watch process status changes
- Track disk space
- Observe build progress
- Check network connectivity

Stopping:
Press Ctrl+C to stop watching.

See also

time, timeout, tail

wc back to top ↑

word, line, character, and byte count

Synopsis

    wc [options] FILE...
    command | wc [options]

Description

Counts lines, words, characters, and bytes in files or standard input.
By default, displays all counts. Options allow selecting specific counts.

Options

    FILE            One or more files to count.

    -l, --lines     Print only line counts.
    -w, --words     Print only word counts.
    -c, --bytes     Print only byte counts.
    -m, --chars     Print only character counts.

Examples

    wc file.txt
        Show lines, words, and bytes for file.txt.

    wc -l file.txt
        Count only lines.

    wc -w document.txt
        Count only words.

    wc *.txt
        Count for all text files (with totals).

    dir /b | wc -l
        Count number of files in directory.

    find . -name "*.cpp" | wc -l
        Count number of C++ files.

    type log.txt | grep error | wc -l
        Count error lines in log.

    wc -l -w report.txt
        Show both line and word counts.

Exit status

    0       Success
    1       File not found
    2       Read error

Notes

Output Format:
Default output shows: lines words bytes filename
With multiple files, a total line is added.

Words:
A "word" is defined as a sequence of non-whitespace characters
separated by whitespace.

Characters vs Bytes:
For ASCII text, -c and -m give the same result. For UTF-8 encoded
files, -m counts Unicode characters while -c counts bytes.

Common Uses:
- Count lines in a file: wc -l file.txt
- Count files: dir /b | wc -l
- Measure code: wc -l *.cpp *.h

See also

head, tail, type, grep

where back to top ↑

locate all instances of a command

Synopsis

    where COMMAND
    where PATTERN

Description

Displays all locations where the specified command or pattern is found.
Unlike 'which' which shows only the first match, 'where' shows every
matching executable in the PATH.

Options

    COMMAND         Command name to locate.
    PATTERN         Pattern with wildcards (* and ?).

Examples

    where notepad
        # C:\Windows\System32\notepad.exe
        # C:\Windows\notepad.exe

    where python
        Show all Python installations.

    where *.exe
        # (lists all .exe files in PATH)

    where java*
        Find all java-related executables.

    where /R C:\Tools *.exe
        Recursively search C:\Tools for executables.

Exit status

    0       At least one match found
    1       No matches found
    2       Error

Notes

All Matches:
where shows ALL matching executables in PATH, which is useful when
multiple versions are installed:
    where python
    # C:\Python311\python.exe
    # C:\Python39\python.exe

Which Runs First:
The first result is what would execute if you typed the command.

Recursive Search:
Use /R to search a directory tree (not just PATH):
    where /R C:\ filename.exe

Comparison:
- which: First match only
- where: All matches

See also

which, find, dir

which back to top ↑

locate a command

Synopsis

    which COMMAND
    which COMMAND...

Description

Displays the full path of the executable that would be run for each
COMMAND. Searches through the PATH environment variable to find the
first matching executable.

Options

    COMMAND         Command name(s) to locate.

Examples

    which notepad
        # C:\Windows\System32\notepad.exe

    which python
        # C:\Python311\python.exe

    which git
        # C:\Program Files\Git\cmd\git.exe

    which grep
        # (built-in) - for CSHW built-in commands

    which notepad python
        Locate multiple commands.

    which nonexistent
        # Command not found

Exit status

    0       Command found
    1       Command not found

Notes

Search Order:
1. Built-in shell commands
2. Aliases
3. PATH directories (left to right)

Executables:
On Windows, which looks for files with executable extensions:
.exe, .com, .bat, .cmd, .ps1

Built-in Commands:
For built-in commands, which indicates "(built-in)" instead of
a file path.

Multiple Matches:
which shows only the first match. Use 'where' to see all matches.

Case Sensitivity:
Command names are case-insensitive on Windows.

See also

where, type, alias

whoami back to top ↑

display current user name

Synopsis

    whoami
    whoami [options]

Description

Displays the user name of the current user. On Windows, shows the
username in DOMAIN\username format.

Options

    /upn            Display in User Principal Name format (user@domain).
    /fqdn           Display Fully Qualified Domain Name.
    /user           Display user SID.
    /groups         Display groups the user belongs to.
    /priv           Display user privileges.
    /all            Display all available information.

Examples

    whoami
        Display current username.

    whoami /groups
        Show group memberships.

    whoami /priv
        Show user privileges.

    whoami /all
        Display comprehensive user information.

Exit status

    0       Success
    1       Error

Notes

Administrator Check:
To check if running as Administrator, look for BUILTIN\Administrators
in 'whoami /groups' output.

Domain vs Local:
On domain-joined machines, shows domain name. On standalone machines,
shows computer name.

See also

env, uname

winapi back to top ↑

call a Win32 API by name with auto-resolution of its DLL

Synopsis

    winapi [-d] [-v] [-h] FUNCTION [ARGS...]

Description

Sugar layer over rundllproc. Looks FUNCTION up in cshw's built-in table
of common Win32 APIs, resolves the hosting DLL (kernel32, user32, gdi32,
advapi32, shell32, ole32, ws2_32, ...) and picks the W or A variant
appropriate to cshw's wide-char default, then dispatches the existing
rundllproc command.

Most callers never have to remember which DLL exports a function. For
unusual cases (private DLL, ordinal lookup, non-standard signature) use
rundllproc directly.

Options

    -d, --dump         Print the resolved <dll>::<name> and exit.
                       Useful for verifying which export will be called.
    -v, --verbose      Forwarded to rundllproc; prints handle and args.
    -h, --help         Show built-in help.
    FUNCTION           Win32 API name. Bare name picks the W variant
                       by default for W/A pairs; append A or W to force
                       a specific variant (MessageBoxA vs MessageBox).
    ARGS               Arguments forwarded verbatim to rundllproc.

Examples

    winapi GetTickCount
        kernel32::GetTickCount -- no arguments, no W/A variant.

    winapi Sleep 250
        kernel32::Sleep called with a 250 ms delay.

    winapi MessageBox 0 "hi" "cshw" 0
        Resolves to user32::MessageBoxW. The bare name picks W.

    winapi MessageBoxA 0 "hi" "cshw" 0
        Forces the ANSI variant.

    winapi -d CreateWindow
        Prints "user32.dll::CreateWindowW" without calling anything.

    winapi -v GetSystemDirectory
        Verbose call, shows DLL handle and arg marshalling.

Exit status

    0       Success (the function returned; the value is in $?).
    1       Function name not in table and no user override; or the
            underlying rundllproc call failed.
    2       Syntax error (no function name, unknown option).

Notes

Extending the table:
A user-level TSV at %APPDATA%\cshw\winapi.tsv adds or overrides entries:
    FunctionName<TAB>your.dll<TAB>None|W|A
Lines beginning with '#' are comments. User entries win over built-ins,
so this is also the way to remap a name to a different DLL.

Resolution order:
    1. Exact name match in user TSV.
    2. Exact name match in the baked-in table.
    3. Strip a trailing W or A and retry (so CreateWindowA finds the
       CreateWindow entry and dispatches the literal name you typed).
    4. Friendly error suggesting rundllproc and the TSV path.

W vs A:
For functions that exist as a W/A pair, the table records the bare name
and a default variant (almost always W). Type the suffix explicitly to
override per-call without editing the table.

Safety:
winapi inherits rundllproc's crash semantics. Wrong argument count or
type can crash the shell. Prefer -d first to confirm resolution before
chaining a call into a script.

See also

rundllproc, dllimport, dlllist, peinfo

winver back to top ↑

display Windows version

Synopsis

    winver

Description

Displays detailed information about the currently running Windows version,
including edition, version number, and build information.

Examples

    winver
        Display Windows version information.

Exit status

    0       Success

Notes

Information Displayed:
- Windows edition (Home, Pro, Enterprise, etc.)
- Version number (e.g., 22H2)
- Build number (e.g., 19045.3803)
- Architecture (32-bit or 64-bit)

Version vs Build:
- Version: Marketing version (21H2, 22H2, 23H2)
- Build: Specific build number, changes with updates

For CSHW shell version, use 'version' or 'ver' instead.

See also

version, uname

writefile back to top ↑

write a shell variable's contents to a file

Synopsis

    writefile <variable> <file>

Description

writefile writes the contents of shell variable <variable> out to
<file>, overwriting any existing file. It is the inverse of readfile.

The variable's text is written as-is; a trailing newline appears only
if the variable's value already ends with one. The file is written as
text, so LF line endings become CRLF.

Examples

    writefile report summary.txt
        Save $report to summary.txt.

    readfile data in.txt
    writefile data out.txt
        Copy a file's contents through a variable.

Exit status

0 on success; non-zero if the variable is not set or the file cannot
be written.

See also

readfile, set, fileblob

xargs back to top ↑

build command lines from standard input and run them

Synopsis

    xargs [options] [command [initial-args...]]

Description

xargs reads items from standard input and runs <command> with those
items appended as arguments. It is most often used at the end of a
pipe to turn a list of names into arguments for another command:

    ls *.tmp | xargs rm

If no <command> is given, echo is used. Input items are separated by
whitespace (spaces, tabs, newlines) unless -0 or -d changes that.
Without -n or -I, every item is passed to a single invocation.

Options:
    -n N        pass at most N items to each invocation
    -I STR      replace STR in the command with one input item,
                running the command once per input line
    -d C        use character C as the item separator
    -0          items are separated by NUL (for `find -print0`)
    -t          print each command line to stderr before running it
    -r          do not run the command if the input is empty
                (long form: --no-run-if-empty)

Examples

    ls *.log | xargs rm

    echo a b c | xargs -n 1 echo

    cat filelist.txt | xargs -I F cp F backup/

Exit status

0 if every invocation succeeded, 1 if any invocation reported failure.

See also

echo, find, ls

zip back to top ↑

create a .zip archive (Windows-style)

Synopsis

    zip [/r] [/p[:<password>]] <archive.zip> <file_or_dir> [more...]

Description

Creates a .zip archive from the listed files and/or directories.
Existing archives are overwritten. Entry paths inside the archive
use forward slashes and are relative to each argument's leaf name
(so `zip pkg.zip src` produces entries `src/...`, not absolute paths).

Supports password protection with AES-256 encryption via /p.

Options

    /r, --recursive
        Recurse into subdirectories when an argument is a directory.

    /p[:<password>]
        Encrypt entries with AES-256. Bare /p prompts on the console
        with confirm. /p:<value> uses the literal password (suitable
        for scripts; note the password ends up in process args and
        shell history).

    <archive.zip>
        Output path. Overwritten if it exists.

    <file_or_dir>...
        One or more inputs. Mix of files and directories ok.

Examples

    zip backup.zip src docs README.md
        Bundle two directories + a file.

    zip /r site.zip public
        Recursively archive the public/ tree.

    zip /p:s3cret secret.zip notes.txt
        Encrypted with literal password.

    zip /p secret.zip notes.txt
        Encrypted; prompts for password on the console.

Exit status

    0       Archive created.
    1       Bad arguments or I/O error (see stderr).

Notes

The Windows-style `zip` builds ZIP archives. For tar/tar.gz/tar.bz2,
see `tar`. To extract or list, see `unzip`.

See also

unzip, tar