# Command Implementation Status

This document tracks the implementation status of commands in the WinuxCmd project, which now uses a pipeline-based architecture for command processing.

## Categories

### File Management

| Command | Status | Priority | Description | Parameters/Options | Implementation Notes |
|---------|--------|----------|-------------|-------------------|---------------------|
| `ls` | ✅ Done | High | List directory contents | `-a, --all`: Do not ignore entries starting with `.`<br>`-A, --almost-all`: Do not list implied `.` and `..`<br>`-b, --escape`: Print C-style escapes for nongraphic characters<br>`-d, --directory`: List directories themselves, not their contents<br>`-f`: List all entries in directory order<br>`-F, --classify`: Append indicator characters to entries<br>`--file-type`: Append type indicators but not `*` for executables<br>`-I, --ignore=PATTERN`: Ignore entries matching PATTERN<br>`--hide=PATTERN`: Hide entries matching PATTERN unless `-a` or `-A` is active<br>`-l, --long, --long-list`: Use a long listing format<br>`--full-time`: Equivalent to `-l --time-style=full-iso`<br>`--author`: Show an author column in long format<br>`-h, --human-readable`: With `-l`, print sizes in human readable format<br>`-r, --reverse`: Reverse order while sorting<br>`-t`: Sort by modification time<br>`-U`: Do not sort; list entries in directory order<br>`-v`: Natural sort of version-like numbers<br>`-X, --sort=WORD`: Sort by a selected key such as `extension`<br>`-n, --numeric-uid-gid`: Like `-l`, but list numeric user and group IDs<br>`-g`: Like `-l`, but do not list owner<br>`-o`: Like `-l`, but do not list group information<br>`-1`: List one file per line<br>`-C`: List entries by columns<br>`-w, --width`: Set output width to COLS<br>`--indicator-style=WORD`: Select slash/file-type/classify/none suffixes<br>`--color`: Colorize output | Implemented with pipeline architecture, supports color output, SmallVector optimization, now preserves GNU-style directory headers for surviving directory/junction operands when sibling operands fail, routes missing-path `cannot access` diagnostics to stderr with GNU-style exit status `2`, keeps `-F/--classify/--file-type` indicators on the symlink/junction name itself rather than on the displayed target, reports Windows directory junction sizes as `0` in long format instead of reusing the rendered target-path length, trims raw Windows namespace prefixes such as `\??\` / `\\?\` from displayed junction targets, accepts command-line directory/junction operands with trailing separators such as `dir/` or `junc/` while preserving the original operand spelling, in long colorized output now colors the link name and displayed target separately instead of painting the whole `name -> target` span as one link-colored block, now accepts GNU `--long` as a direct alias of `-l`, now accepts both singular and plural `--dereference-command-line-symlink(s)-to-dir` long forms, now accepts GNU `--full-time` as `-l --time-style=full-iso` while still letting later format/time-style options override it, now treats GNU `-g`, `-n`, and `-o` as long-format requests like `-l` while still letting later explicit format options override them, now also suppresses the corresponding owner/group columns for GNU `-g`, `-o`, and `--no-group`, `--hide=PATTERN` now matches GNU/Microsoft behavior by hiding matching names only in default mode while `-a` / `-A` override it and `--ignore=PATTERN` still filters even in all-mode listings, GNU `--author` is now accepted and emits an extra long-format author column using the same Windows owner approximation as Microsoft/Coreutils, now mirrors Microsoft Coreutils' Windows permission approximation by showing writable entries as `rwxrwxrwx` and read-only ones as `r-xr-xr-x`, now re-probes real directory metadata for long-format `.` / `..` entries so parent-directory size and `total` no longer collapse to synthetic zeroes, now also keeps the synthetic `.` entry on the dereferenced target-directory view for `ls -laL DIRLINK` style directory-symlink or junction listings, now keeps default `-s` output plus directory `total` lines on the closer Windows/Coreutils allocated-byte convention instead of pre-dividing by 1K blocks, and on Windows `--block-size=SIZE` / `-k` now rescale only the long-format size column while `-s` plus directory `total` stay on that byte-based view unless `-h` or `--si` is selected; C/shell/escape quoting now also applies to the displayed symlink target in long format too instead of leaving the target path raw |
| `cat` | ✅ Done | High | Concatenate files and print on the standard output | `-A, --show-all`: Equivalent to `-vET`<br>`-b, --number-nonblank`: Number only non-empty output lines<br>`-e`: Equivalent to `-vE`<br>`-E, --show-ends`: Display $ at end of each line<br>`-n, --number`: Number all output lines<br>`-s, --squeeze-blank`: Squeeze multiple adjacent empty lines<br>`-t`: Equivalent to `-vT`<br>`-T, --show-tabs`: Display TAB characters as `^I`<br>`-u`: GNU compatibility placeholder, currently ignored<br>`-v, --show-nonprinting`: Show nonprinting characters | Simple file reading and writing with pipeline structure, SmallVector optimization |
| `cp` | ✅ Done | High | Copy files and directories | `-a, --archive`: Recursive copy and preserve Windows timestamps/attributes<br>`-p`: Preserve Windows timestamps/attributes<br>`-i, --interactive`: Prompt before overwrite<br>`-r, -R, --recursive`: Copy directories recursively<br>`-t, --target-directory`: Copy all SOURCE arguments into DIRECTORY<br>`-T, --no-target-directory`: Treat DEST as a normal file<br>`--strip-trailing-slashes`: Strip trailing `/` or `\` from each source operand before lookup<br>`-n, --no-clobber`: Do not overwrite an existing file<br>`-u, --update`: Copy only when SOURCE is newer than DEST<br>`-v, --verbose`: Explain what is being done<br>`-f, --force`: Force copy without prompt | File system operations with error handling; owner/mode preservation is a Windows approximation, and GNU-style source trailing slash stripping is now supported |
| `mv` | ✅ Done | High | Move (rename) files | `-i, --interactive`: Prompt before overwrite<br>`-I`: Prompt once before larger batches<br>`-v, --verbose`: Explain what is being done<br>`-f, --force`: Do not prompt before overwriting<br>`-n, --no-clobber`: Do not overwrite an existing file<br>`--interactive[=WHEN]`: GNU-style overwrite prompt mode with last-option precedence | File system operations with error handling, SmallVector optimization |
| `rm` | ✅ Done | High | Remove files or directories | `-f, --force`: Ignore nonexistent files and arguments, never prompt<br>`-i, --interactive`: Prompt before every removal<br>`-r, -R, --recursive`: Remove directories and their contents recursively<br>`-v, --verbose`: Explain what is being done | File system operations with error handling; missing operands now also print the GNU-style `Try 'rm --help' for more information.` hint |
| `mkdir` | ✅ Done | High | Make directories | `-p, --parents`: No error if existing, make parent directories as needed<br>`-v, --verbose`: Print a message for each created directory<br>`-m, --mode`: Set file mode (as in chmod) | File system operations with error handling; missing operands now include the GNU-style help hint |
| `rmdir` | ✅ Done | Medium | Remove empty directories | `--ignore-fail-on-non-empty`: Ignore each failure to remove a directory that is non-empty<br>`-p, --parents`: Remove DIRECTORY and its ancestors<br>`-v, --verbose`: Print a message for each removed directory | File system operations with error handling; missing operands now include the GNU-style help hint, file operands now report the more GNU-shaped `Not a directory` diagnostic, `-v` now prints the GNU/uutils-shaped `removing directory, 'DIR'` line before every attempted removal including failures, and `-p` now returns failure if ancestor cleanup stops on a non-empty parent |
| `touch` | ✅ Done | Medium | Change file timestamps or create empty files | `-a`: Change only the access time<br>`-m`: Change only the modification time<br>`-c, --no-create`: Do not create any files<br>`-d, --date`: Parse STRING and use it instead of current time<br>`-r, --reference`: Use this file's times instead of current time<br>`-t, --time`: Use the specified timestamp instead of the current time<br>`-h, --no-dereference`: Change each symbolic link rather than any referenced file<br>`--time=WORD`: Change the specified time type | File system operations with error handling |
| `basename` | ✅ Done | Low | Strip directory and suffix from file names | `-a, --multiple`: Support multiple arguments and treat each as a NAME<br>`--mul`: Accepted abbreviation for `--multiple`<br>`-s, --suffix=SUFFIX`: Remove a trailing SUFFIX and imply multi-name mode even when `SUFFIX` is empty<br>`--suf`: Accepted abbreviation for `--suffix`<br>`-z, --zero`: End each output line with NUL<br>`--ze`: Accepted abbreviation for `--zero`<br>GNU-shaped operand diagnostics: missing operand help hint and non-`-a` extra operand rejection<br>Slash-only root inputs such as `/`, `//`, and `///` now normalize to a single root separator<br>GNU suffix rule: do not strip a suffix that is identical to the entire remaining basename | File name processing |
| `dirname` | ✅ Done | Low | Strip last component from file name | `-z, --zero`: End each output line with NUL<br>GNU-shaped operand diagnostics: missing operand help hint<br>Slash-only root inputs such as `/`, `//`, and `///` now normalize to a single root separator<br>Absolute top-level paths such as `/usr/` keep `/` as the parent directory | File name processing |
| `readlink` | ✅ Done | Low | Print resolved symbolic links or canonical file names | `-f, --canonicalize`: Canonicalize by following every symlink<br>`-e, --canonicalize-existing`: Canonicalize by following every symlink and verify existence<br>`-m, --canonicalize-missing`: Canonicalize by following every symlink and verify existence without requirement<br>`-n, --no-newline`: Do not output the trailing delimiter<br>`-q, -s, --quiet, --silent`: Suppress most diagnostics<br>`-v, --verbose`: Report diagnostics<br>`-z, --zero`: End each output line with NUL<br>GNU-shaped operand diagnostics: missing operand help hint | Symbolic link resolution; default diagnostics stay quiet, both the canonicalization mode family plus `-q/-s/-v` now follow last-occurrence precedence, and `POSIXLY_CORRECT` now restores GNU-style regular-file diagnostics while ignoring `-q/-s` |
| `realpath` | ✅ Done | Low | Print the resolved absolute path | `-e, --canonicalize-existing`: All components of the path must exist<br>`-E, --canonicalize`: All but the last path component must exist<br>`-m, --canonicalize-missing`: No path components need to exist<br>`-L, --logical`: Accepted; Windows path normalization is used<br>`-P, --physical`: Accepted; Windows path normalization is used<br>`-q, --quiet`: Suppress error messages<br>`-s, --strip, --no-symlinks`: Don't expand symlinks<br>`--relative-to=DIR`: Print the resolved path relative to DIR<br>`--relative-base=DIR`: Print relative output only for paths below DIR<br>`-z, --zero`: End each output line with NUL<br>GNU-shaped operand diagnostics: missing operand help hint and invalid empty-string rejection | Path resolution; at least one path operand is now required, `-e`, `-E`, and `-m` follow last-occurrence precedence, empty path/relative operands are rejected as invalid empty strings, `-e` now requires `--relative-to` / `--relative-base` to resolve to directories, and full GNU `-L` versus `-P` symlink ordering is still partial |
| `stat` | ✅ Done | Medium | Display file or file system status | `-c, --format=FORMAT`: Use the specified FORMAT instead of the default and append a newline<br>`--printf=FORMAT`: Like `--format`, but interpret backslash escapes and do not append a newline<br>`-f, --file-system`: Display file system status instead of file status<br>`-L, --dereference`: Follow symbolic links<br>`-t, --terse`: Display the information in terse form<br>Common format fields: `%n`, `%N`, `%s`, `%b`, `%B`, `%F`, `%A`, `%a`, `%h`, `%i`, `%d`, `%D`, `%o`, `%u`, `%g`, `%U`, `%G`, `%x/%X`, `%y/%Y`, `%z/%Z`, `%w/%W` | Windows-backed file status display; missing operands now also print the GNU-style `Try 'stat --help' for more information.` hint, and `-t`, `-c/--format`, plus `--printf` now follow GNU/uutils-style last-occurrence precedence, while owner/group and symlink details remain Windows approximations |
| `link` | ✅ Done | Medium | Create a hard link between two files | No regular options | Hard-link creation; missing-source failures and existing-destination failures now use GNU-shaped `cannot create link 'LINK' to 'FILE'` diagnostics instead of raw Win32 error codes, wrong operand counts now collapse to the uutils-shaped `2 values required` diagnostic, option parsing for this optionless command now emits GNU-style `unrecognized option` help hints, `-V/--version` now succeeds, and source wildcards now follow the shared file-input policy: exact-one match expands, multi-match collapses back to the same `2 values required` operand-count failure a shell-expanded call would trigger, and zero-match falls back to the literal path |
| `unlink` | ✅ Done | Low | Remove a single file | No options | File removal; missing-path and directory failures now use GNU-shaped `cannot unlink` diagnostics instead of raw Win32 error codes, operand errors keep their help hint on stderr and now name the offending extra operand, unknown options on this optionless command now emit GNU-style `unrecognized option` help hints, `-V/--version` now succeeds, wildcard inputs that expand to multiple paths now fail with a GNU-style `extra operand` hint, unmatched wildcard inputs fall back to the literal path, and directory symlinks/junctions are now removed as links rather than deleting their targets |
| `truncate` | ✅ Done | Low | Shrink or extend the size of a file | `-c, --no-create`: Do not create files<br>`-s, --size=SIZE`: Set or adjust the file size by SIZE bytes<br>`-r, --reference=RFILE`: Base the size of FILE on the size of RFILE | File size modification |
| `sync` | ✅ Done | Low | Synchronize cached writes to persistent storage | `-d, --data`: Sync only file data for the named files<br>`-f, --file-system`: Sync the file systems that contain the named files | File system synchronization; GNU `sync`'s `-d/--data` and `-f/--file-system` option surface is now accepted, existing directory operands now succeed for plain `sync` and `--data`, `--data` without file operands now fails with the uutils-shaped `--data needs at least one argument` diagnostic, `--data` and `--file-system` now fail together as mutually exclusive options, `--file-system` now accepts existing file and directory operands as filesystem references, invalid options now emit GNU-style `unrecognized option` help hints, and missing file operands are now all reported with GNU/uutils-shaped `error opening 'FILE': No such file or directory` diagnostics instead of stopping after the first failure; Windows still uses an approximation rather than true Unix filesystem sync semantics |
| `install` | ✅ Done | Medium | Copy files and set attributes | `-b, --backup[=CONTROL]`: Make a backup of each existing destination file<br>`-C, --compare`: Compare each pair of source and destination files<br>`-d, --directory`: Treat all arguments as directory names<br>`-D, --create-leading-dirs`: Create all leading components of DEST except the last<br>`-g, --group=GROUP`: Set group ownership<br>`-m, --mode=MODE`: Set permission mode<br>`-o, --owner=OWNER`: Set ownership<br>`-p, --preserve-timestamps`: Apply access/modification times of SOURCE files<br>`-s, --strip`: Strip symbol tables<br>`-t, --target-directory=DIRECTORY`: Install all SOURCE arguments into DIRECTORY<br>`-T, --no-target-directory`: Treat DEST as a normal file<br>`-v, --verbose`: Print the name of each directory as it is created | File installation with attributes |
| `find` | ✅ Done | High | Search for files in a directory hierarchy | `-name PATTERN`: Base file name matches shell pattern PATTERN<br>`-iname PATTERN`: Base file name matches shell pattern PATTERN, case-insensitive<br>`-path PATTERN`: Full path matches shell pattern PATTERN<br>`-ipath PATTERN`: Full path matches shell pattern PATTERN, case-insensitive<br>`-type X`: File is of type X (currently `f`, `d`, `l`)<br>`-size N`: File uses N units of space; supports `+N/-N/N` and `c/k/M/G` units<br>`-empty`: File or directory is empty<br>`-mtime N`: File data was last modified N*24 hours ago<br>`-mmin N`: File data was last modified N minutes ago<br>`-mindepth N`: Begin tests only after depth N<br>`-maxdepth N`: Descend at most N levels<br>`-print`: Print the full file name on standard output<br>`-print0`: Print the full file name followed by NUL<br>`-printf FORMAT`: Print selected GNU-style file fields (`%p`, `%f`, `%h`, `%H`, `%P`, `%d`, `%D`, `%F`, `%g`, `%G`, `%l`, `%o`, `%u`, `%U`, `%S`, `%y`, `%Y`, `%s`, `%b`, `%k`, `%m`, `%M`, `%n`, `%i`, `%A@`, `%B@`, `%C@`, `%T@`, plus the zero-padded local component subset `%A{Y,m,d,H,M,S,j}`, `%B{Y,m,d,H,M,S,j}`, `%C{Y,m,d,H,M,S,j}`, `%T{Y,m,d,H,M,S,j}`, `%%`) and common escapes including GNU-style `\c` plus octal `\NNN`<br>`-prune`: Skip descending into directories in the current traversal<br>`-quit`: Stop the search immediately<br>`-L`: Follow symbolic links during traversal<br>`-H`: Follow command-line symlink roots only; traversal-time symlinks still require `-L`<br>`-delete`: Delete matched files/directories using depth-first traversal<br>`-exec COMMAND {} ;`: Execute once per match with `{}` replacement<br>`-exec COMMAND {} +`: Batch matched paths at the end of COMMAND<br>`-ok COMMAND {} ;`: Prompt before executing once per match<br>`-ok COMMAND {} +`: Prompt once before executing a batched command | File searching with GNU-style expression precedence and short-circuiting; current-directory-rooted default `-print` / `-print0` output now uses a Microsoft-style `.\` prefix while keeping the remainder of the relative path stable; junction-style directory reparse points are treated as link-like entries for `-type l` and related `-printf` fields, `%S` reports the Win32 allocated-size to logical-size ratio as the closest sparseness analogue for regular files, the `%A/%B/%C/%T` component subset now exposes a deterministic local time surface beyond the `@` forms, and some deeper GNU regex and `-printf` semantics still remain open |
| `xargs` | ✅ Done | High | Build and execute command lines from input | `-n, --max-args=MAX-ARGS`: Use at most MAX-ARGS arguments per command line<br>`-L, --max-lines=MAX-LINES`: Use at most MAX-LINES nonblank input lines per command line<br>`-l[LINES]`: Deprecated alias for `-L`; bare form defaults to 1 line<br>`-I R-STR`: Replace occurrences of R-STR in the initial arguments with names read from standard input<br>`-i, --replace[=R-STR]`: Deprecated alias for `-I`; bare form defaults to `{}`<br>`-P, --max-procs=MAX-PROCS`: Run at most MAX-PROCS processes at a time<br>`-a, --arg-file=FILE`: Read items from FILE instead of standard input<br>`-E EOF`: Set the logical EOF string<br>`-e[EOF], --eof[=EOF]`: Deprecated alias for `-E`; bare form leaves EOF disabled<br>`--show-limits`: Display command-line length limits<br>`-t, --verbose`: Print the command line on standard error before executing it<br>`-0, --null`: Input items are terminated by a null character instead of white space<br>`-d, --delimiter=DELIM`: Input items are terminated by DELIM instead of white space<br>`-o, --open-tty`: Reopen standard input as the console for children<br>`-r, --no-run-if-empty`: Do not run the command when input is empty<br>`-x, --exit`: Exit if the size limit is exceeded<br>`--process-slot-var=VAR`: Export a slot variable to children | Execute commands from input, SmallVector optimization; stdin items still stay literal data, while command-template arguments now consume the shared wildcard policy so `xargs cmd ... *.txt` behaves closer to a shell-expanded GNU call on Windows and still falls back to the literal token when the glob has no matches; parent-directory wildcard segments such as `dir*\\*.txt` and `dir?\\*.txt` now expand too instead of staying spuriously literal; malformed `-d` escape forms such as `\\x` and unknown named escapes now return specific delimiter-escape diagnostics instead of the older generic single-character error |

### Text Processing

| Command | Status | Priority | Description | Parameters/Options | Implementation Notes |
|---------|--------|----------|-------------|-------------------|---------------------|
| `echo` | ✅ Done | High | Display a line of text | `-n`: Do not output the trailing newline<br>`-e`: Enable interpretation of backslash escapes<br>`-E`: Disable interpretation of backslash escapes<br>`-u, --upper`: Convert text to uppercase<br>`-r, --repeat N`: Repeat output N times | Implemented with pipeline architecture, serves as reference implementation, supports escape sequences including `\n`, `\t`, `\xHH`, `\uHHHH`, GNU old-style octal escapes like `\43` and `\101`, bare `echo` now matches GNU/uutils by succeeding with a single trailing newline instead of treating empty args as an error, `-e` / `-E` now follow GNU/uutils last-occurrence precedence, unknown or incomplete escapes such as `\ ` and `\x` without hex digits now keep their leading backslash like GNU/uutils, `\xFF` style non-UTF-8 bytes and UTF-8 byte sequences such as `\xf0\x9f\x98\x82` are now covered by tests, and `POSIXLY_CORRECT` now enables escape processing by default while still honoring `-n`, ignoring `-E`, and treating non-leading-`-n` option-like arguments such as `--help`, `--version`, and `-nE` as literal text |
| `grep` | ✅ Done | High | Print lines matching a pattern | `-E, --extended-regexp`: Interpret PATTERNS as extended regular expressions<br>`-F, --fixed-strings`: Interpret PATTERNS as fixed strings<br>`-G, --basic-regexp`: Interpret PATTERNS as basic regular expressions<br>`-e, --regexp=PATTERNS`: Use PATTERNS for matching; repeatable<br>`-f, --file=FILE`: Read patterns from FILE; repeatable<br>`-i, --ignore-case`: Ignore case distinctions<br>`-w, --word-regexp`: Match only whole words<br>`-x, --line-regexp`: Match only whole lines<br>`-z, --null-data`: Use NUL-delimited records<br>`-v, --invert-match`: Invert the sense of matching<br>`-m, --max-count=NUM`: Stop after NUM selected lines<br>`-b, --byte-offset`: Prefix byte offsets<br>`-n, --line-number`: Prefix line numbers<br>`-H, --with-filename`: Print file name prefixes<br>`-h, --no-filename`: Suppress file name prefixes<br>`-o, --only-matching`: Print only matching parts<br>`-q, --quiet`: Suppress normal output<br>`-r, --recursive`: Recurse into directories<br>`-R, --dereference-recursive`: Recurse and follow directory symlinks<br>`--include=GLOB`, `--exclude=GLOB`, `--exclude-from=FILE`, `--exclude-dir=GLOB`: Filter searched files<br>`-A/-B/-C`: Print context<br>`--group-separator=SEP`, `--no-group-separator`: Control context group separators<br>`--binary-files=TYPE`, `-a`, `-I`: Binary-file policy<br>`-D, --devices=ACTION`: Use `read` or `skip` for devices/FIFOs/sockets<br>`--color`: Highlight matches | Pattern matching with regex support, wildcard file operands, repeatable option storage, and SmallVector optimization |
| `sort` | ✅ Done | Medium | Sort lines of text files | `-b, --ignore-leading-blanks`: Ignore leading blanks<br>`-d, --dictionary-order`: Consider only blanks and alphanumerics<br>`-f, --ignore-case`: Fold lower case to upper case characters<br>`-g, --general-numeric-sort`: Compare according to general numeric value<br>`-h, --human-numeric-sort`: Compare according to human-readable numeric value<br>`-i, --ignore-nonprinting`: Ignore nonprinting characters<br>`-k, --key`: Repeatable key sort using `F[.C][OPTS][,F[.C][OPTS]]` ranges<br>`-M, --month-sort`: Sort by month name<br>`-n, --numeric-sort`: Compare according to string numerical value<br>`-r, --reverse`: Reverse the result of comparisons<br>`-R, --random-sort`: Random sort order<br>`--random-source=FILE`: Get deterministic random bytes from FILE<br>`-S, --buffer-size=SIZE`: Accept GNU SIZE forms as a memory hint<br>`--parallel=N`: Accept a validated concurrency hint<br>`--batch-size=N`: Accept a validated merge hint<br>`--compress-program=PROG`: Accept a validated non-empty compression hint<br>`-T, --temporary-directory=DIR`: Accept an existing-directory temporary hint<br>`-s, --stable`: Stable sort<br>`-u, --unique`: With -c, check for strict ordering<br>`-C, --check-silent`: Quietly check whether input is sorted<br>`-t, --field-separator`: Use SEP instead of non-blank to blank transition<br>`-z, --zero-terminated`: Line delimiter is NUL, not newline<br>`-o FILE`: Write the result to FILE instead of standard output | Sorting with ordered multi-key, key ranges, character positions, common per-key modifiers, GNU-style quiet check mode, plus validated `--parallel`, `--batch-size`, `--compress-program`, and `-T/--temporary-directory` hints that currently do not change the single-threaded merge/temp-file implementation |
| `wc` | ✅ Done | Medium | Print newline, word, and byte counts for each file | `-c, --bytes`: Print the byte counts<br>`-l, --lines`: Print the newline counts<br>`-w, --words`: Print the word counts<br>`-m, --chars`: Print the character counts<br>`-L, --max-line-length`: Print the maximum display width<br>`--files0-from=FILE`: Read file names from a NUL-separated list<br>`--total=WHEN`: Control how totals are printed | Character counting with multiple modes, SmallVector optimization |
| `head` | ✅ Done | Low | Output the first part of files | `-c, --bytes=[-]NUM`: Print the first N bytes, or count backward from the end with a negative value<br>`-n, --lines=[-]NUM`: Print the first N lines, or count backward from the end with a negative value<br>`-q, --quiet, --silent`: Never print headers giving file names<br>`-v, --verbose`: Always print headers giving file names<br>`-z, --zero-terminated`: Line delimiter is NUL, not newline | File head extraction with byte/line options, SmallVector optimization |
| `tail` | ✅ Done | Low | Output the last part of files | `-c, --bytes=[+]NUM`: Output the last N bytes, or start from an offset with a positive value<br>`-n, --lines=[+]NUM`: Output the last N lines, or start from an offset with a positive value<br>`-q, --quiet, --silent`: Never print headers giving file names<br>`-v, --verbose`: Always print headers giving file names<br>`-z, --zero-terminated`: Line delimiter is NUL, not newline<br>`-f, --follow`: Output appended data as the file grows<br>`--follow=name`: Follow by file name instead of descriptor<br>`-F`: Same as `--follow=name --retry`<br>`-s, --sleep-interval=SECONDS`: Pause between follow iterations<br>`--pid=PID`: Stop following after PID dies<br>`--retry`: Keep trying to open inaccessible files<br>`--use-polling`: Explicitly select polling follow mode<br>`--max-unchanged-stats=N`: Reopen an unchanged followed name after N iterations | File tail extraction with follow-by-name support; the `-F` / `--follow=descriptor|name` family now follows last-occurrence precedence, and `--use-polling` maps to the current polling-based follow implementation |
| `sed` | ✅ Done | Medium | Stream editor for filtering and transforming text | `-e, --expression`: Add SCRIPT to the commands to be executed; repeatable and order-preserving with `-f`<br>`-f, --file`: Add the contents of SCRIPT-FILE to the commands; repeatable and order-preserving with `-e`<br>`-n, --quiet, --silent`: Suppress automatic printing of pattern space<br>`-i, --in-place`: Edit files in place | Text stream editing with ordered repeatable script support, SmallVector optimization |
| `uniq` | ✅ Done | Medium | Report or omit repeated lines | `-c, --count`: Prefix lines by the number of occurrences<br>`-d, --repeated`: Only print duplicate lines, one for each group<br>`-D, --all-repeated[=METHOD]`: Print all repeated lines for each group<br>`-f, --skip-fields`: Avoid comparing the first N fields<br>`-i, --ignore-case`: Ignore differences in case when comparing<br>`-s, --skip-chars`: Avoid comparing the first N characters<br>`--group[=METHOD]`: Group repeated lines in the output<br>`-u, --unique`: Only print unique lines<br>`-w, --check-chars`: Compare no more than N characters in lines<br>`-z, --zero-terminated`: Line delimiter is NUL, not newline | Duplicate line detection and filtering, SmallVector optimization; grouping modes are wired, while exact GNU separator edge cases still need polish |
| `cut` | ✅ Done | Medium | Remove sections from each line of files | `-b, --bytes`: Cut by byte position<br>`-c, --characters`: Cut by character position<br>`-d, --delimiter`: Use DELIM instead of TAB for field delimiter<br>`-w`: Use runs of spaces or tabs as field delimiters (Microsoft/FreeBSD extension)<br>`-f, --fields`: Select only these fields<br>`--complement`: Select the complement of specified bytes, characters, or fields<br>`--output-delimiter=STRING`: Use STRING between selected fields or byte/character ranges<br>`-s, --only-delimited`: Do not print lines not containing delimiters<br>`-z, --zero-terminated`: Line delimiter is NUL, not newline | Field, byte, and character extraction; `-w` now follows Microsoft's whitespace-field splitting shape, including TAB output and `-d` conflict handling |
| `ptx` | ✅ Done | Low | Produce a permuted index of file contents | `-f, --ignore-case`: Ignore case differences<br>`-r, --references`: Output word references only<br>`-w, --width`: Set output width | Permuted index generation |
| `expand` | ✅ Done | Low | Convert tabs to spaces | `-t, --tabs=tab1[,tab2]...`: Set tab stops<br>`-i, --initial`: Do not convert tabs after non-blanks | Tab to space conversion |
| `unexpand` | ✅ Done | Low | Convert spaces to tabs | `-t, --tabs=tab1[,tab2]...`: Set tab stops<br>`-a, --all`: Convert all whitespace, not just initial<br>`-f, --first-only`: Only convert the first run of spaces<br>`-U, --no-utf8`: Treat file input as raw 8-bit bytes | Space to tab conversion; default file reads strip a UTF-8 BOM, while `-U` preserves it |
| `fold` | ✅ Done | Low | Wrap each input line to fit specified width | `-w, --width=WIDTH`: Use WIDTH columns instead of 80<br>`-b, --bytes`: Count bytes rather than columns<br>`-c, --characters`: Count characters rather than columns<br>`-s, --spaces`: Break at spaces | Line wrapping; ordinary newline-delimited mode trims trailing `\r` from CRLF records, `-c` now counts UTF-8 code points without splitting multibyte sequences, and default column mode keeps common UTF-8 wide characters intact while treating them as two display columns |
| `fmt` | ✅ Done | Low | Simple optimal text formatter | `-w, --width=WIDTH`: Maximum line width (default 75)<br>`-T, --tab-width=TABWIDTH`: Measure tabs as TABWIDTH spaces while preserving tabs in output<br>`-p, --prefix=STRING`: Only format lines starting with STRING<br>`-P, --skip-prefix=STRING`: Leave matching lines unformatted<br>`-x, --exact-prefix`: Do not ignore leading whitespace for `-p`<br>`-X, --exact-skip-prefix`: Do not ignore leading whitespace for `-P`<br>`-c, --crown-margin`: Preserve crown margins<br>`-m, --preserve-headers`: Detect simple mail headers and continuation lines<br>`-t, --tagged-paragraph`: Preserve tagged paragraphs<br>`-s, --split-only`: Only split long lines<br>`-u, --uniform-spacing`: Fix spacing | Text formatting; prefix mode now preserves the matched prefix attachment, `-x` keeps indented lines out of `-p` matching, `-P/-X` cover the common skip-prefix cases we matched against Microsoft, `-m` now preserves simple `Header: value` blocks with merged continuation lines while using the wider wrap behavior we observed on Microsoft, and tab-indented paragraphs now follow the Microsoft/Coreutils default 8-column tab width unless `-T` overrides the measurement width |
| `nl` | ✅ Done | Low | Number lines of files | `-b, --body-numbering=STYLE`: Use STYLE for numbering body lines<br>`-n, --number-format=FORMAT`: Insert line numbers according to FORMAT<br>`-s, --number-separator=STRING`: Add STRING after (possible) line numbers<br>`-f, --footer-numbering=STYLE`: Footer numbering style<br>`-h, --header-numbering=STYLE`: Header numbering style<br>`-i, --line-increment=NUMBER`: Line increment<br>`-l, --join-blank-lines=NUMBER`: Join blank lines<br>`-v, --starting-line-number=NUMBER`: Starting line number<br>`-w, --number-width=NUMBER`: Number width | Line numbering |
| `paste` | ✅ Done | Low | Merge lines of files | `-d, --delimiters=LIST`: Reuse characters from LIST instead of TABs<br>`-s, --serial`: Paste one file at a time instead of in parallel<br>`-z, --zero-terminated`: End lines with NUL | Line merging |
| `pr` | ✅ Done | Low | Convert text files for printing | `+FIRST_PAGE[:LAST_PAGE]`: Begin [stop] printing with page FIRST_PAGE<br>`-C, --columns=NUM`: Output NUM columns and print columns down<br>`-a, --across`: Print columns across<br>`-d, --double-space`: Double-space the output<br>`-h, --header=HEADER`: Use a centered HEADER instead of filename<br>`-l, --length=PAGE_LENGTH`: Set the page length to PAGE_LENGTH lines<br>`-o, --indent=MARGIN`: Offset each line with MARGIN spaces<br>`-T, --omit-pagination`: Omit pagination controls | Text file formatting for printing |
| `tr` | ✅ Done | Medium | Translate or delete characters | `-c, -C, --complement`: Use the complement of SET1<br>`-d, --delete`: Delete characters in SET1<br>`-s, --squeeze-repeats`: Replace each sequence of a repeated character<br>`-t, --truncate-set1`: First truncate SET1 to length of SET2 | Character translation and deletion; operand-count diagnostics now distinguish missing `SET2`, `-d -s` missing the squeeze set, and delete-mode extra operands with GNU-style help hints |
| `rev` | ✅ Done | Low | Reverse lines of a file | No options | Line reversal |
| `tac` | ✅ Done | Low | Concatenate and print files in reverse | `-b, --before`: Attach the separator before instead of after<br>`-r, --regex`: Interpret the separator as a regular expression<br>`-s, --separator=STRING`: Use STRING as the separator | Reverse concatenation |
| `shuf` | ✅ Done | Low | Shuffle input lines | `-e, --echo`: Treat each ARG as an input line<br>`-i, --input-range=LO-HI`: Treat each number LO through HI as an input line<br>`-n, --head-count=COUNT`: Output at most COUNT lines<br>`-o, --output=FILE`: Write result to FILE instead of standard output<br>`--random-seed=STRING`: Use STRING for reproducible output<br>`--random-source=FILE`: Read random bytes from FILE<br>`-r, --repeat`: Allow repeated output<br>`-z, --zero-terminated`: Use NUL as line terminator | Line shuffling; `--random-seed` now follows the closer Microsoft/uutils seeded algorithm surface for permutation and `-r` sampling, `--random-source` now follows the closer GNU/Microsoft entropy-recycling adapter for repeat sampling and shuffle selection, repeated `-n/--head-count` now takes the lowest supplied count, and `--random-seed` is rejected together with `--random-source` |
| `split` | ✅ Done | Low | Split a file into pieces | `-l, --lines=NUMBER`: Put NUMBER lines per output file<br>`-b, --bytes=SIZE`: Put SIZE bytes per output file<br>`-C, --line-bytes=SIZE`: Put SIZE bytes per output file without splitting lines<br>`--filter=COMMAND`: Run COMMAND on each output file<br>`-n, --number=CHUNKS`: Produce CHUNKS chunks<br>`-a, --suffix-length=N`: Generate suffixes of length N<br>`-d, --numeric-suffixes[=FROM]`: Use numeric suffixes<br>`-x, --hex-suffixes[=FROM]`: Use hexadecimal suffixes<br>`--additional-suffix=SUFFIX`: Append SUFFIX to output files<br>`-e, --elide-empty-files`: Do not generate empty output files<br>`-t, --separator=SEP`: Use SEP as the record separator<br>`-u, --unbuffered`: Flush output after each line<br>`--verbose`: Print output file names | File splitting; the input operand uses the shared wildcard policy and ambiguous matches are rejected unless they resolve to exactly one file, while a third positional operand now fails with a GNU-style `extra operand` help hint |
| `csplit` | ✅ Done | Low | Split a file into context-determined pieces | `-f, --prefix=PREFIX`: Use PREFIX as output file name prefix<br>`-b, --suffix-format=FORMAT`: Use FORMAT for suffixes<br>`-n, --digits=DIGITS`: Use specified number of digits<br>`-k, --keep-files`: Do not remove output files on errors<br>`--suppress-matched`: Suppress matching lines in output files<br>`-z, --elide-empty-files`: Elide empty output files<br>`-s, -q, --quiet, --silent`: Do not print output file sizes | Context-determined file splitting; the input operand uses the shared wildcard policy and ambiguous matches are rejected unless they resolve to exactly one file, missing input/pattern diagnostics now include the GNU-style help hint, and line-number patterns with `--suppress-matched` now preserve GNU/uutils-style empty-tail behavior |
| `join` | ✅ Done | Low | Join lines of two files on a common field | `-1 FIELD`: Join on this FIELD of file 1<br>`-2 FIELD`: Join on this FIELD of file 2<br>`-a FILE-NUMBER`: Print unpairable lines from file NUMBER<br>`--check-order`: Check that input is correctly sorted<br>`--nocheck-order`: Do not check sort order<br>`-e STRING`: Replace empty output fields with STRING<br>`--header`: Treat first line of each file as header<br>`-i, --ignore-case`: Ignore case when comparing keys<br>`-j FIELD`: Join on FIELD in both files<br>`-o FIELD-LIST`: Output fields according to FIELD-LIST<br>`-t, --separator=CHAR`: Use CHAR as input and output field separator<br>`-v FILE-NUMBER`: Print only unpairable lines from file NUMBER<br>`-z, --zero-terminated`: Use NUL as line terminator | Line joining |
| `comm` | ✅ Done | Low | Compare two sorted files line by line | `-1`: Suppress lines unique to FILE1<br>`-2`: Suppress lines unique to FILE2<br>`-3`: Suppress lines that appear in both files<br>`--check-order`: Check that input is correctly sorted<br>`--nocheck-order`: Do not check sort order<br>`--output-delimiter=STRING`: Use STRING between columns<br>`--total`: Print totals<br>`-z, --zero-terminated`: Use NUL as line terminator | Sorted file comparison |

### System Information

| Command | Status | Priority | Description | Parameters/Options | Implementation Notes |
|---------|--------|----------|-------------|-------------------|---------------------|
| `which` | ✅ Done | High | Locate a command in PATH | `-a, --all`: Print all matching pathnames of each argument<br>`--read-alias`, `--skip-alias`: Read or skip alias expansion<br>`--read-functions`, `--skip-functions`: Read or skip shell function expansion<br>`--skip-dot`: Skip directories in PATH that start with a dot<br>`--show-dot`: Allow directories that start with a dot to be shown<br>`--skip-tilde`: Skip directories in PATH that start with a tilde<br>`--show-tilde`: Allow directories that start with a tilde to be shown<br>`--tty-only`: Show matches only on a tty | Path searching with PATHEXT support, SmallVector optimization |
| `env` | ✅ Done | Medium | Run a command in a modified environment | `-i, --ignore-environment`: Start with an empty environment<br>`-u, --unset=NAME`: Remove variable from the environment; repeatable<br>`-0, --null`: End each printed environment entry with NUL; rejected when COMMAND is present with GNU/uutils-style exit `125`<br>`-f, --file=FILE`: Load `.env`-style `NAME=VALUE` pairs before `-u` and command-line assignments; blank lines and `#` comments are ignored<br>`-S, --split-string=S`: Split S into arguments using the current lightweight parser; unterminated quotes now fail with exit `125`<br>`-v, --debug`: Emit processing diagnostics on standard error; repeated debug flags such as `-vv` also dump raw input arguments<br>`-a, --argv0=STRING`: Override the child process `argv[0]` while still executing the original program<br>`-C, --chdir=DIR`: Change working directory before running COMMAND; GNU-style usage requires that a command be present<br>`NAME=VALUE`: Add or override an environment variable<br>`COMMAND [ARG]...`: Run COMMAND with the modified environment | Prints or executes with a materialized Windows environment block; parse-time invalid options now also return GNU/uutils-style exit `125` with the standard help hint, `-f/--file` now loads simple trimmed `.env` entries before `-u` and command-line `NAME=VALUE`, file-open failures return a regular command failure instead of a usage error, `-a/--argv0`, `-C/--chdir`, and `-S/--split-string` now follow last-occurrence precedence, `-0/--null` is limited to environment-printing mode and now fails with `cannot specify --null (-0) with command` when combined with a command, missing child commands now report a GNU-shaped `failed to run command 'CMD': ...` diagnostic while preserving the conventional `127` not-found exit, and full GNU `-S` parsing plus remaining GNU debug/signal details remain gaps |
| `pwd` | ✅ Done | High | Print working directory | `-L, --logical`: Use an absolute `PWD` from the environment when it still names the current directory<br>`-P, --physical`: Avoid all symlinks | Working directory display; `-L` now prefers `PWD` only when it is absolute, still resolves to the current directory, and contains no `.` / `..` components, `POSIXLY_CORRECT` now switches bare `pwd` to the logical default, `-L/-P` follow last-occurrence precedence, and extra non-option operands now warn with GNU-shaped `ignoring non-option arguments` stderr output |
| `ps` | ✅ Done | High | Report process status | `-e, -A`: Select all processes<br>`-a`: Select all processes except both session leaders and processes not associated with a terminal<br>`-x`: Select processes without controlling ttys<br>`-f`: Full-format listing<br>`-l`: Long format<br>`-u USER`: Select by effective user ID or name<br>`-w`: Wide output<br>`--no-headers`: Print no header<br>`--sort=KEY`: Sort by column | Process listing and filtering; this is a repo-local implementation, not a GNU Coreutils manual page |
| `tee` | ✅ Done | Medium | Read from stdin and write to stdout and files | `-a, --append`: Append to the given FILEs, do not overwrite<br>`-i, --ignore-interrupts`: Ignore interrupt signals<br>`-p, --diagnose`: Write errors to standard error as they occur | Standard input/output redirection, SmallVector optimization |
| `chmod` | ✅ Done | Medium | Change file mode bits | `-c, --changes`: Like verbose but report only when a change is made<br>`-f, --silent, --quiet`: Suppress most error messages<br>`-v, --verbose`: Output a diagnostic for every file processed<br>`-R, --recursive`: Change files and directories recursively<br>`--reference=RFILE`: Use RFILE's mode instead of MODE values | File permission modification; file operands use the shared wildcard policy, `-R --preserve-root /` now stops with the GNU/uutils-style failsafe, `--reference=RFILE FILE...` now copies the reference file's Windows read-only approximation with GNU-shaped missing-reference diagnostics, malformed modes such as `u+gr` now fail before file access with the GNU-style help hint, and GNU-style negative symbolic modes such as `-w`, `file -w`, and repeated `-w -w` are now accepted |
| `chcon` | ✅ Done | Medium | Change SELinux file context | `--reference=RFILE`: Use RFILE's security context<br>`-u, --user=USER`: Set the user component<br>`-r, --role=ROLE`: Set the role component<br>`-t, --type=TYPE`: Set the type component<br>`-l, --range=RANGE`: Set the range component<br>`-R, --recursive`: Operate on files and directories recursively<br>`-H`, `-L`, `-P`, `-h`, `--dereference`: GNU-compatible symlink traversal/dereference surface<br>`-v, --verbose`: Output a diagnostic for every file processed | Windows compatibility placeholder: validates the GNU-shaped command line surface and existing file operands, then reports that SELinux file contexts are not supported on Windows |
| `chroot` | ✅ Done | Medium | Change the root directory | `--groups=GROUP1,GROUP2...`: Specify supplementary groups<br>`--userspec=USER:GROUP`: Specify user and group before running COMMAND<br>`--skip-chdir`: Do not change working directory to `/` after changing root<br>`NEWROOT [COMMAND [ARG]...]`: GNU operand form | Windows compatibility placeholder: validates the GNU-shaped command line surface and that `NEWROOT` exists as a directory, then reports that changing the root directory is not supported on Windows |
| `chown` | ✅ Done | Medium | Change file owner and group | `-c, --changes`: Like verbose but report only when a change is made<br>`-f, --silent, --quiet`: Suppress most error messages<br>`-v, --verbose`: Output a diagnostic for every file processed<br>`-R, --recursive`: Change files and directories recursively<br>`--from=CURRENT_OWNER:CURRENT_GROUP`: Change only from the current owner/group<br>`--reference=RFILE`: Use RFILE's owner and group instead of USER:GROUP | File ownership modification; explicit `OWNER` / `GROUP` names and the current-owner/group names supplied to `--from` are now validated up front so invalid names fail with GNU-shaped `invalid user` / `invalid group` diagnostics before traversal, malformed specs such as `::`, `..`, `1001:`, and `1001.` now fail with the closer GNU/uutils-shaped `invalid group` / `invalid spec` diagnostics, dot-separated forms such as `OWNER.` and `OWNER.GROUP` now emit the GNU/uutils-style `warning: '.' should be ':'` warning before proceeding, `--from` now filters existing targets by their current Windows owner/group before applying `--reference` or continuing with a direct change attempt, mismatching `--from` filters now keep the target unchanged and `-v` reports retained ownership, matching `--from` filters no longer emit the old Windows-placeholder `not supported` diagnostic, direct no-op specs such as `:` and `CURRENT_OWNER:` now also report retained ownership instead of a fake `changing ownership ... to` line, missing reference files now report `failed to get attributes of 'RFILE': No such file or directory`, `-v --reference=RFILE FILE...` now emits a retained-ownership diagnostic on stderr, and `--preserve-root -R /` now stops before traversal with the GNU/uutils-style two-line failsafe diagnostic |
| `chgrp` | ✅ Done | Medium | Change group ownership | `-c, --changes`: Like verbose but report only when a change is made<br>`-f, --silent, --quiet`: Suppress most error messages<br>`-v, --verbose`: Output a diagnostic for every file processed<br>`-R, --recursive`: Change files and directories recursively<br>`--from=GROUP`: Change only if the current group matches GROUP<br>`--reference=RFILE`: Use RFILE's group instead of GROUP | File group ownership modification; invalid `GROUP` operands now fail early with the GNU/uutils-shaped `invalid group: 'GROUP'` diagnostic plus the standard help hint, invalid `--from=GROUP` operands now fail with the matching uutils-shaped `invalid user: 'GROUP'` diagnostic, `--from=GROUP` now filters each existing target by its current Windows group name before applying `--reference` or a direct change attempt, numeric `--from=gid` and `--from=:gid` forms are now accepted and matched against the target group SID's final RID as a Windows approximation, missing `--reference=RFILE` files now report `failed to get attributes of 'RFILE': No such file or directory`, `--reference=RFILE FILE...` accepts the GNU operand form and validates the reference file on Windows, `-v --reference=RFILE FILE...` emits a retained-group diagnostic on stderr only when the `--from` filter matches, `--preserve-root -R /` now stops before traversal with the GNU/uutils-style two-line failsafe diagnostic, and the current implementation still treats actual group changes as Windows-limited behavior |
| `ln` | ✅ Done | Medium | Make links between files | `-s, --symbolic`: Make symbolic links instead of hard links<br>`-f, --force`: Remove existing destination files<br>`-i, --interactive`: Prompt whether to remove destinations<br>`-v, --verbose`: Print name of each linked file<br>`-n, --no-dereference`: Treat LINK_NAME as a normal file if it is a symbolic link to a directory<br>`-t, --target-directory=DIRECTORY`: Create links in DIRECTORY<br>`-T, --no-target-directory`: Treat LINK_NAME as a normal file always | File linking (hard/symbolic); `ln TARGET` now creates the link in the current directory using `basename(TARGET)`, `ln SOURCE DIR` now treats an existing second-operand directory as the target directory unless `-T` is active, missing-source failures, existing-target failures, and forced remove failures now report GNU-shaped text instead of raw Win32/local wording, multi-operand invocation follows GNU `TARGET... DIRECTORY` semantics instead of treating one source as many direct targets, and `-t` / `-T` now conflict explicitly |
| `diff` | ✅ Done | Medium | Compare files line by line | `-u, --unified=NUM`: Output NUM (default 3) lines of unified context<br>`-q, --brief`: Output only whether files differ<br>`-i, --ignore-case`: Ignore case differences in file contents<br>`-w, --ignore-all-space`: Ignore all white space<br>`-B, --ignore-blank-lines`: Ignore changes whose lines are all blank<br>`-y, --side-by-side`: Output in two columns<br>`-r, --recursive`: Recursively compare any subdirectories [NOT SUPPORT] | File comparison; file operands use the shared wildcard policy, must resolve to exactly two files, and now reject extra operands with a GNU-style help hint |
| `diff3` | ✅ Done | Low | Compare three files | `-e`: Output an ed script<br>`-3`: Like -e, but incorporate changes from the third file<br>`-m, --merge`: Output the merged file<br>`-i`: Like -e, but bracket changes<br>`-A`: Incorporate all changes from older to yours<br>`-E`: Ignore changes from older to yours<br>`-X`: Overwrite overlapping changes from older to yours | Three-way file comparison; file operands use the shared wildcard policy, must resolve to exactly three files, and now reject extra operands with a GNU-style help hint |
| `sdiff` | ✅ Done | Low | Side-by-side merge of file differences | `-o FILE`: Write output to FILE<br>`-w NUM`: Set output width to NUM columns<br>`-l`: Print only the left column when lines are common<br>`-s, --suppress-common-lines`: Do not print common lines<br>`-E`: Ignore tab expansion<br>`-b`: Ignore changes in the amount of white space<br>`-W`: Ignore all white space<br>`-B`: Ignore changes whose lines are all blank | Side-by-side diff; empty files are accepted, file operands now reject extra operands with a GNU-style help hint, and file-like wildcards resolve before the fixed two-file arity check |
| `patch` | ✅ Done | Medium | Apply a diff file to an original | `-p NUM`: Strip NUM leading components from file names<br>`-i, --input=PATCHFILE`: Read patch from PATCHFILE<br>`-d, --directory=DIR`: Change to DIR<br>`-R, --reverse`: Assume patch was created with old and new files swapped<br>`-N, --forward`: Assume patch was created with old and new files swapped | Patch file application |
| `cmp` | ✅ Done | Low | Compare two files byte by byte | `-b, --print-bytes`: Print differing bytes<br>`-i, --ignore-initial=SKIP` / `-i SKIP1:SKIP2`: Skip the specified initial bytes from one or both inputs<br>`-l, --verbose`: Output byte numbers and differing byte values for every difference<br>`-n, --bytes=LIMIT`: Compare at most LIMIT bytes<br>`-s, --quiet`: Suppress normal output<br>`FILE1 FILE2 [SKIP1 [SKIP2]]`: GNU positional skip operands are accepted | Byte comparison; default difference output now includes both byte and line numbers, `-l/--verbose` lists every differing byte using GNU-style octal values relative to the comparison start, the `-l/--verbose` and `-s/--quiet` output-mode family now follows GNU/uutils-style last-occurrence precedence, GNU positional `SKIP1`/`SKIP2` plus `-i SKIP1:SKIP2` now work, skip counts accept GNU-style decimal/octal/hex prefixes with common byte suffixes, and skipping past the shorter file no longer underflows the comparison range |
| `file` | ✅ Done | Medium | Determine file type | `-b, --brief`: Do not prepend filenames to output lines<br>`-i, --mime`: Output mime type strings<br>`-z, --compress`: Try to look inside compressed files<br>`--mime-type`: Output the MIME type only<br>`--mime-encoding`: Output the MIME encoding only | File type detection |
| `cksum` | ✅ Done | Low | CRC checksum and byte counts | `-a, --algorithm=TYPE`: Select `sysv`, `bsd`, or `crc`<br>`-c, --check=FILE`: Read and verify checksums from FILE<br>`--ignore-missing`: Skip missing listed files during check mode<br>`-q, --quiet`: Suppress successful `OK` lines during check mode<br>`-s, --status`: Suppress normal check-mode output and use exit status<br>`-w, --warn`: Report malformed checksum lines with locations<br>`--strict`: Fail when malformed checksum lines are present<br>`--tag`: Emit BSD-style tagged output<br>`--untagged`: Force untagged output<br>`-z, --zero`: End output records with NUL<br>`--raw`: Emit raw digest bytes<br>`--base64`: Emit base64 digest bytes<br>`-l, --length=BITS`: Select digest length when supported<br>`--debug`: Print debug output | Checksum calculation; check mode now verifies untagged size fields, supports GNU-style `--quiet` / `--status`, and treats malformed check lines like GNU with `--warn` / `--strict` |
| `sum` | ✅ Done | Low | Print checksum and block counts | `-r`: Use BSD checksum format<br>`-s`: Use System V checksum format | Legacy checksum compatibility |
| `md5sum` | ✅ Done | Low | Compute and check MD5 message digest | `-b, --binary`: Read in binary mode<br>`-c, --check`: Read MD5 sums from the FILEs and check them<br>`--tag`: Create a BSD-style checksum<br>`-t, --text`: Read in text mode<br>`-z, --zero`: End each output line with NUL | MD5 checksum |
| `sha1sum` | ✅ Done | Low | Compute and check SHA1 message digest | `-b, --binary`: Read in binary mode<br>`-c, --check`: Read SHA1 sums from the FILEs and check them<br>`--tag`: Create a BSD-style checksum<br>`-t, --text`: Read in text mode<br>`-z, --zero`: End each output line with NUL | SHA1 checksum |
| `sha224sum` | ✅ Done | Low | Compute and check SHA224 message digest | `-b, --binary`: Read in binary mode<br>`-c, --check`: Read SHA224 sums from the FILEs and check them<br>`--tag`: Create a BSD-style checksum<br>`-t, --text`: Read in text mode<br>`-z, --zero`: End each output line with NUL | SHA224 checksum |
| `sha256sum` | ✅ Done | Low | Compute and check SHA256 message digest | `-b, --binary`: Read in binary mode<br>`-c, --check`: Read SHA256 sums from the FILEs and check them<br>`--tag`: Create a BSD-style checksum<br>`-t, --text`: Read in text mode<br>`-z, --zero`: End each output line with NUL | SHA256 checksum |
| `sha384sum` | ✅ Done | Low | Compute and check SHA384 message digest | `-b, --binary`: Read in binary mode<br>`-c, --check`: Read SHA384 sums from the FILEs and check them<br>`--tag`: Create a BSD-style checksum<br>`-t, --text`: Read in text mode<br>`-z, --zero`: End each output line with NUL | SHA384 checksum |
| `sha512sum` | ✅ Done | Low | Compute and check SHA512 message digest | `-b, --binary`: Read in binary mode<br>`-c, --check`: Read SHA512 sums from the FILEs and check them<br>`--tag`: Create a BSD-style checksum<br>`-t, --text`: Read in text mode<br>`-z, --zero`: End each output line with NUL | SHA512 checksum |
| `b2sum` | ✅ Done | Low | Compute and check BLAKE2 message digest | `-b, --binary`: Read in binary mode<br>`-c, --check`: Read BLAKE2 sums from the FILEs and check them<br>`--tag`: Create a BSD-style checksum<br>`-t, --text`: Read in text mode<br>`-z, --zero`: End each output line with NUL | BLAKE2 checksum |
| `base64` | ✅ Done | Low | Base64 encode/decode data | `-d, --decode`: Decode data<br>`-i, --ignore-garbage`: When decoding, ignore non-alphabet characters<br>`-w, --wrap=COLS`: Wrap encoded lines after COLS characters | Base64 encoding/decoding; extra file operands now follow GNU-style `extra operand 'FILE'` diagnostics and print the standard `Try 'base64 --help' for more information.` hint |
| `base32` | ✅ Done | Low | Base32 encode/decode data | `-d, --decode`: Decode data<br>`-w, --wrap=COLS`: Wrap encoded lines after COLS characters | Base32 encoding/decoding; extra file operands now follow GNU-style `extra operand 'FILE'` diagnostics and print the standard `Try 'base32 --help' for more information.` hint |
| `basenc` | ✅ Done | Low | Encode/decode data with various algorithms | `-d, --decode`: Decode data<br>`-b, --base64`: Base64<br>`-z, --z85`: Z85<br>`-w, --wrap=COLS`: Wrap encoded lines after COLS characters | Various encoding/decoding; extra file operands now follow GNU-style `extra operand 'FILE'` diagnostics and print the standard `Try 'basenc --help' for more information.` hint |
| `xxd` | ✅ Done | Low | Make a hexdump or do the reverse | `-b, --bits`: Switch to bits (binary digits)<br>`-c, --cols COLS`: Format COLS octets per line<br>`-g, --groupsize BYTES`: Number of octets per group in normal output<br>`-l, --len LENGTH`: Stop after LENGTH octets<br>`-p, --ps`: Output in postscript continuous hexdump style<br>`-r, --reverse`: Reverse operation: convert (or patch) hexdump into binary<br>`-s, --seek OFFSET`: Start at OFFSET | Hexdump and reverse |
| `od` | ✅ Done | Low | Dump files in octal and other formats | `-A, --address-radix=RADIX`: Select the base in which file offsets are printed<br>`-j, --skip-bytes=BYTES`: Skip BYTES input bytes first<br>`-N, --read-bytes=BYTES`: Limit dump to BYTES bytes<br>`-t, --format=TYPE`: Select output format(s)<br>`-v, --output-duplicates`: Do not use * to mark line suppression<br>`-w, --width BYTES`: Output BYTES bytes per output line | Octal dump |
| `cpio` | ✅ Done | Low | Copy files to and from archives | `-o, --create`: Create the archive<br>`-i, --extract`: Extract files from an archive<br>`-t, --list`: List the contents of an archive<br>`-d, --make-directories`: Create leading directories where needed<br>`-m, --preserve-modification-time`: Retain previous file modification times when creating files | Archive copying |
| `dd` | ✅ Done | Medium | Convert and copy a file | `if=FILE`: Read from FILE instead of stdin<br>`of=FILE`: Write to FILE instead of stdout<br>`bs=BYTES`: Read and write up to BYTES bytes at a time<br>`ibs=BYTES`: Read up to BYTES bytes at a time<br>`obs=BYTES`: Write BYTES bytes at a time<br>`cbs=BYTES`: Convert BYTES bytes at a time [parsed]<br>`count=N`: Copy only N input blocks<br>`skip=N`: Skip N ibs-sized input blocks<br>`seek=N`: Skip N obs-sized output blocks<br>`conv=CONVS`: Supports `notrunc` and `sync`; accepts `noerror` as a placeholder<br>`status=none|noxfer|progress`: Control diagnostic output | File conversion and copying |
| `expr` | ✅ Done | Medium | Evaluate expressions | `--help`: Display help<br>`--version`: Output version information | Expression evaluation |
| `factor` | ✅ Done | Low | Print prime factors | No options | Prime factorization |
| `tsort` | ✅ Done | Low | Perform topological sort | No options | Topological ordering of pair lists |
| `seq` | ✅ Done | Low | Print a sequence of numbers | `-f, --format=FORMAT`: Use printf style floating-point FORMAT<br>`-s, --separator=STRING`: Use STRING to separate numbers<br>`-t, --terminator=STRING`: Use STRING instead of the final newline<br>`-w, --equal-width`: Equalize width by padding with leading zeroes | Sequence generation; missing and extra operands now include GNU-style help hints, `-w` now rejects an explicit `-f/--format` string with the GNU/uutils-style conflict diagnostic, `-t/--terminator` now replaces only the final output separator while leaving intermediate separators unchanged, and zero increments now use the closer GNU/uutils `invalid Zero increment value: 'ARG'` diagnostic |
| `yes` | ✅ Done | Low | Output a string repeatedly | `STRING...`: Strings to join with spaces before repeating | Repeated output; GNU/uutils-style multi-operand invocations now join all operands with single spaces instead of using only the first operand, and `-V/--version` now succeeds instead of being misparsed as an unknown option |
| `sleep` | ✅ Done | Low | Delay for a specified time | `NUMBER[SUFFIX]`: Pause for NUMBER seconds | Sleep delay; missing operands now include the GNU-style help hint, malformed or negative durations now use GNU-shaped `invalid time interval` diagnostics, multiple invalid duration operands are now all reported before the final help hint, leading whitespace remains accepted, and trailing whitespace is now rejected like GNU/uutils |
| `stdbuf` | ✅ Done | Medium | Run COMMAND with modified buffering operations for its standard streams | `-i, --input=MODE`: Adjust standard input stream buffering<br>`-o, --output=MODE`: Adjust standard output stream buffering<br>`-e, --error=MODE`: Adjust standard error stream buffering | Buffer modification; missing-command, invalid-mode, and invalid-option usage/parse failures now return GNU/uutils-style exit `125` while keeping the help hint on stderr, child arguments are now quoted with Windows `CreateProcessW` rules so spaces stay within one argv entry, and the implementation still only adjusts parent-process buffering |
| `shred` | ✅ Done | Medium | Overwrite a file to hide its contents | `-f, --force`: Change permissions to allow writing<br>`-n, --iterations=N`: Overwrite N times instead of the default (3)<br>`-s, --size=N`: Shred this many bytes<br>`-u, --remove`: Delete and truncate file after overwriting<br>`-v, --verbose`: Show progress<br>`-z, --zero`: Add a final overwrite with zeros | Secure file deletion |
| `pathchk` | ✅ Done | Low | Check whether file names are valid or portable | `-p, --portability`: Check based on POSIX<br>`-P, --posix`: Check based on POSIX<br>`--help`: Display help<br>`--version`: Output version information<br>GNU-shaped operand diagnostics: missing operand help hint stays on stderr<br>Current-filesystem checks accept normal Windows drive-letter absolute paths, repeated/trailing separators no longer trip false `empty file name` failures under `-P`-style checks, and the default empty-path diagnostic now uses the GNU/uutils-style `pathchk: '': No such file or directory` shape, including one line per invalid operand | Path validation |
| `tree` | ✅ Done | Medium | List contents of directories in a tree-like format | `-a, --all`: All files are listed<br>`-d, --directory-list`: List directories only<br>`-f, --full-path`: Print full path prefix for each file<br>`-L, --level=LEVEL`: Descend only level directories deep<br>`--help`: Display help<br>`--version`: Output version information | Tree display |
| `less` | ✅ Done | High | View file (or stdin) with scrollable page | `-E, --QUIT-AT-EOF`: Quit at EOF<br>`-F, --quit-if-one-screen`: Quit if entire file fits on first screen<br>`-R, --RAW-CONTROL-CHARS`: Output "raw" control characters<br>`-S, --chop-long-lines`: Chops long lines | File viewer |
| `cat` | ✅ Done | High | Concatenate files and print on the standard output | `-n, --number`: Number all output lines<br>`-b, --number-nonblank`: Number non-empty output lines<br>`-E, --show-ends`: Display $ at end of each line<br>`-s, --squeeze-blank`: Squeeze multiple adjacent empty lines<br>`-T, --show-tabs`: Display TAB characters as `^I` | Simple file reading and writing with pipeline structure, SmallVector optimization |
| `cp` | ✅ Done | High | Copy files and directories | `-i, --interactive`: Prompt before overwrite<br>`-r, --recursive`: Copy directories recursively<br>`-v, --verbose`: Explain what is being done<br>`-f, --force`: Force copy without prompt<br>`--strip-trailing-slashes`: Strip trailing `/` or `\` from each source operand before lookup | File system operations with error handling |
| `mv` | ✅ Done | High | Move (rename) files | `-i, --interactive`: Prompt before overwrite<br>`-I`: Prompt once before larger batches<br>`-v, --verbose`: Explain what is being done<br>`-f, --force`: Do not prompt before overwriting<br>`-n, --no-clobber`: Do not overwrite an existing file<br>`--interactive[=WHEN]`: GNU-style overwrite prompt mode with last-option precedence | File system operations with error handling, SmallVector optimization |
| `rm` | ✅ Done | High | Remove files or directories | `-f, --force`: Ignore nonexistent files and arguments, never prompt<br>`-i, --interactive`: Prompt before every removal<br>`-r, -R, --recursive`: Remove directories and their contents recursively<br>`-v, --verbose`: Explain what is being done | File system operations with error handling |
| `mkdir` | ✅ Done | High | Make directories | `-p, --parents`: No error if existing, make parent directories as needed<br>`-v, --verbose`: Print a message for each created directory<br>`-m, --mode`: Set file mode (as in chmod) | File system operations with error handling; missing operands now include the GNU-style help hint |
| `rmdir` | ✅ Done | Medium | Remove empty directories | `--ignore-fail-on-non-empty`: Ignore each failure to remove a directory that is non-empty<br>`-p, --parents`: Remove DIRECTORY and its ancestors<br>`-v, --verbose`: Print a message for each removed directory | File system operations with error handling; verbose output now uses the GNU/uutils-shaped `removing directory, 'DIR'` line before each attempted removal, including failed parent-cleanup attempts |

### Network

| Command | Status | Priority | Description | Parameters/Options | Implementation Notes |
|---------|--------|----------|-------------|-------------------|---------------------|
| `ping` | ❌ TODO | High | Send ICMP ECHO_REQUEST to network hosts | `-c COUNT`: Stop after sending COUNT ECHO_REQUEST packets<br>`-i INTERVAL`: Wait INTERVAL seconds between sending each packet | Not yet implemented |
| `curl` | ❌ TODO | Medium | Transfer data from or to a server | `-s, --silent`: Silent mode<br>`-o, --output`: Write output to a file instead of stdout | Not yet implemented |
| `wget` | ❌ TODO | Medium | Non-interactive network downloader | `-O, --output-document=FILE`: Write documents to FILE<br>`-q, --quiet`: Turn off wget's output | Not yet implemented |

### Testing and Terminal Control

| Command | Status | Priority | Description | Parameters/Options | Implementation Notes |
|---------|--------|----------|-------------|-------------------|---------------------|
| `test` | ✅ Done | High | Check file types and compare values | `-b FILE`: FILE exists and is block special<br>`-c FILE`: FILE exists and is character special<br>`-d FILE`: FILE exists and is a directory<br>`-e FILE`: FILE exists<br>`-f FILE`: FILE exists and is a regular file<br>`-g FILE`: FILE exists and is set-group-ID<br>`-G FILE`: FILE exists and is owned by the effective group ID<br>`-h FILE`: FILE exists and is a symbolic link<br>`-k FILE`: FILE exists and has its sticky bit set<br>`-L FILE`: FILE exists and is a symbolic link<br>`-O FILE`: FILE exists and is owned by the effective user ID<br>`-p FILE`: FILE exists and is a named pipe<br>`-r FILE`: FILE exists and read permission is granted<br>`-s FILE`: FILE exists and has a size greater than zero<br>`-S FILE`: FILE exists and is a socket<br>`-t FD`: File descriptor FD is opened on a terminal<br>`-u FILE`: FILE exists and its set-user-ID bit is set<br>`-w FILE`: FILE exists and write permission is granted<br>`-x FILE`: FILE exists and execute permission is granted<br>`-z STRING`: the length of STRING is zero<br>`-n STRING`: the length of STRING is nonzero<br>`STRING1 = STRING2`: the strings are equal<br>`STRING1 != STRING2`: the strings are not equal<br>`INTEGER1 -eq INTEGER2`: INTEGER1 is equal to INTEGER2<br>`INTEGER1 -ne INTEGER2`: INTEGER1 is not equal to INTEGER2<br>`INTEGER1 -gt INTEGER2`: INTEGER1 is greater than INTEGER2<br>`INTEGER1 -ge INTEGER2`: INTEGER1 is greater than or equal to INTEGER2<br>`INTEGER1 -lt INTEGER2`: INTEGER1 is less than INTEGER2<br>`INTEGER1 -le INTEGER2`: INTEGER1 is less than or equal to INTEGER2<br>`! EXPR`: EXPR is false<br>`EXPR1 -a EXPR2`: Both EXPR1 and EXPR2 are true<br>`EXPR1 -o EXPR2`: Either EXPR1 or EXPR2 is true | File type checking and value comparison |
| `[` | ✅ Done | High | Check file types and compare values (same as test) | Same as test | Alias for test |
| `test_bracket` | ✅ Done | High | Internal entry point for `[` | Same as test | Shared syntax and dispatch wrapper for `test` / `[` |
| `true` | ✅ Done | Low | Return a successful result | No options | Always returns 0 for normal execution, and `-V/--version` now succeeds instead of being misparsed as an unknown option |
| `false` | ✅ Done | Low | Return an unsuccessful result | No options | Always returns 1 for normal execution, and `-V/--version` now succeeds instead of being misparsed as an unknown option |
| `clear` | ✅ Done | High | Clear the terminal screen | No options | Uses system call to clear screen |
| `reset` | ✅ Done | Low | Reinitialize the terminal | No options | Terminal reset |
| `tput` | ✅ Done | Low | Initialize a terminal or query terminfo database | `STRING`: Terminfo capability to query | Terminal capability query |
| `tic` | ✅ Done | Low | Terminfo entry-description compiler | No options | Terminfo compilation |
| `toe` | ✅ Done | Low | Table of (terminfo) entries | No options | Terminfo table display |
| `tty` | ✅ Done | Low | Print the file name of the terminal connected to standard input | `-s, --silent`: Print nothing, only return an exit status<br>`--quiet`: Alias for `--silent` | Terminal file name display; extra operands and invalid options now keep GNU-shaped diagnostics plus the help hint on stderr with exit 2, non-tty stdin returns exit 1 in silent and non-silent modes, broken stdout during non-silent output now returns GNU/uutils-shaped exit 3, and tty detection still uses simplified Windows console detection |
| `stty` | ✅ Done | Medium | Change and print terminal line settings | `-a, --all`: Print all current settings<br>`-g, --save`: Print all current settings in stty-readable form<br>`-F, --file=DEVICE`: Open and use the specified DEVICE instead of stdin | Terminal settings |
| `infocmp` | ✅ Done | Low | Compare or print out terminfo descriptions | `-d, --differences`: Print differences<br>`-c, --compare`: Print comparisons<br>`-I, --use-terminfo`: Use the terminfo names | Terminfo comparison |
| `getconf` | ✅ Done | Low | Query system configuration variables | `-a, --all`: Print all configuration variables<br>`-v, --variable-specification`: Return variable based on variable specification | System configuration query |
| `locale` | ✅ Done | Low | Get locale-specific information | `-a, --all-locales`: List all available locales<br>`-m, --charmaps`: List available charmaps<br>`-c, --category-name`: List names of available categories<br>`-k, --keyword-name`: List names of available keywords | Locale information |
| `localedef` | ✅ Done | Medium | Compile locale definition files | `-f, --charmap=FILE`: Symbolic character names defined in FILE<br>`-i, --inputfile=FILE`: Locale definition file<br>`-u, --alias-file=FILE`: Alias file for locale names | Locale definition compilation |
| `tzset` | ✅ Done | Low | Initialize timezone information | No options | Timezone initialization |
| `iconv` | ✅ Done | Medium | Convert text from one encoding to another | `-f, --from-code=NAME`: Encoding of original text<br>`-t, --to-code=NAME`: Encoding for output<br>`-l, --list`: List all known coded character sets<br>`-c`: Omit invalid characters<br>`-s`: Suppress warnings | Encoding conversion |
| `cygpath` | ✅ Done | Medium | Convert Windows and POSIX path names | `-u, --unix`: Print Unix (POSIX) form of path<br>`-w, --windows`: Print Windows form of path<br>`-m, --mixed`: Print Windows form, with regular slashes<br>`-a, --absolute`: Output absolute path | Path conversion |
| `dos2unix` | ✅ Done | Low | Convert DOS line endings to Unix format | No options | Line ending conversion |
| `unix2dos` | ✅ Done | Low | Convert Unix line endings to DOS format | No options | Line ending conversion |
| `d2u` | ✅ Done | Low | Alias for dos2unix | No options | Line ending conversion |
| `u2d` | ✅ Done | Low | Alias for unix2dos | No options | Line ending conversion |
| `printf` | ✅ Done | High | Format and print data | `FORMAT`: Format string<br>`ARGUMENTS`: Arguments to format | Formatted output |

### System Utilities

| Command | Status | Priority | Description | Parameters/Options | Implementation Notes |
|---------|--------|----------|-------------|-------------------|---------------------|
| `date` | ✅ Done | Medium | Print or set system date/time | `-d, --date=STRING`: Display time described by STRING<br>`--debug`: Print date-parsing diagnostics<br>`-f, --file=DATEFILE`: Read date strings from a file<br>`-I, --iso-8601[=TIMESPEC]`: ISO 8601 output<br>`-r, --reference=FILE`: Use FILE's time<br>`--resolution`: Print time resolution<br>`-R, --rfc-email`: RFC 5322-style date output<br>`--rfc-3339=TIMESPEC`: RFC 3339-style output<br>`-s, --set=STRING`: Set the system time<br>`-u, --utc, --universal`: Print or set Coordinated Universal Time (UTC)<br>`+FORMAT`: Output format string | Date/time display and formatting |
| `df` | ✅ Done | Medium | Report file system disk space usage | `-h, --human-readable`: Print sizes in powers of 1024<br>`-H, --si`: Print sizes in powers of 1000<br>`-k`: Use 1K blocks<br>`-T, --print-type`: Print file system type<br>`-i, --inodes`: List inode-shaped information instead of block usage; Windows prints placeholder inode columns<br>File operands use the shared wildcard policy<br>`-t, --type=TYPE`, `-x, --exclude-type=TYPE`, `-a, --all`: tracked in the GNU parity ledger | Disk space reporting |
| `du` | ✅ Done | Medium | Estimate file space usage | `-a, --all`: Write counts for all files, not just directories<br>`-B, --block-size=SIZE`: Scale sizes by SIZE before printing<br>`-b, --bytes`: Equivalent to apparent-size with block size 1<br>`-c, --total`: Produce a grand total<br>`-d, --max-depth=N`: Print entries only if they are N or fewer levels below the command line argument<br>`-h, --human-readable`: Print sizes in powers of 1024<br>`--si`: Print sizes in powers of 1000<br>`-H, --dereference-args`: Accept GNU dereference-args surface on Windows<br>`-k`: Use 1K blocks<br>`-m`: Use 1M blocks<br>`-0, --null`: End each output record with NUL instead of newline<br>`-S, --separate-dirs`: Exclude subdirectory totals from each parent directory's reported size<br>`--time[=WORD]`: Show the latest selected timestamp for each emitted entry; supports `mtime`, `atime|access|use`, and `ctime|status`<br>`-X, --exclude-from=FILE`: Read exclude glob patterns from FILE<br>`--files0-from=FILE`: Read NUL-delimited path operands from FILE<br>`-s, --summarize`: Display only a total for each argument | File/directory size estimation; `--files0-from` rejects extra command-line paths, file operands otherwise use the shared wildcard policy, `--exclude-from` patterns feed the same matcher as `--exclude`, block counts round up, and `ctime`/`status` currently map to creation time on Windows |
| `dir` | ✅ Done | Medium | List directory contents in columns by default | `OPTION... FILE...`: Forward the GNU `dir` wrapper surface to `ls -C` | Wrapper around `ls` with column output as the default; forwarded argv now keeps the original option/operand order, so GNU wrapper options such as `-a` and `-d` actually reach `ls`, and single arguments containing spaces are preserved via Windows `CreateProcessW` quoting rules |
| `kill` | ✅ Done | High | Send a signal to processes | `-l, --list`: List all signal names<br>`-s, --signal=SIGNAL`: Send the specified signal<br>`-t, --table`: List signals in a table<br>`SIGNAL`: Signal number or name (e.g., -9, -KILL, -15, -TERM) | Process signal sending |
| `nice` | ✅ Done | Medium | Run a program with modified scheduling priority | `-n, --adjustment=N`: Add integer N to the scheduling priority<br>Legacy GNU adjustment forms such as `-1`, `--1`, and `-+1` are accepted before COMMAND<br>`--help`: Display help<br>`--version`: Output version information | Process priority modification; bare `nice` now prints the current niceness, explicit adjustments without a command now fail with the GNU/uutils-style `A command must be given with an adjustment.` usage error and exit `125`, legacy bare adjustments like `-1`, `--1`, and `-+1` now rewrite to GNU `-n` semantics before the command starts, huge positive/negative adjustments are clamped instead of failing in option parsing, invalid adjustment strings such as `-2+4` return exit `125` with a GNU-shaped usage error, invalid option parse failures now also return `125`, child arguments are now quoted with Windows `CreateProcessW` rules so spaces stay within a single argv entry, and missing child commands now report a GNU-shaped `failed to run command 'CMD': ...` diagnostic while preserving the conventional `127` not-found exit |
| `nohup` | ✅ Done | Medium | Run a command immune to hangups | `--help`: Display help<br>`--version`: Output version information<br>GNU-shaped operand/parse diagnostics: missing-operand and invalid-option help hints stay on stderr, and those usage errors return `127` under `POSIXLY_CORRECT` instead of the default `125` | Immune to hangups; child arguments are now quoted with Windows `CreateProcessW` rules so spaces stay within one argv entry, and missing command invocation now reports a GNU-shaped `failed to run command 'CMD': ...` diagnostic and preserves the conventional `127` not-found exit |
| `runcon` | ✅ Done | Medium | Run a command in a SELinux process context | `-c, --compute`: Compute process transition context before modifying<br>`-u, --user=USER`: Set the user component<br>`-r, --role=ROLE`: Set the role component<br>`-t, --type=TYPE`: Set the type component<br>`-l, --range=RANGE`: Set the range component<br>`CONTEXT COMMAND [ARG]...`: GNU plain-context form | Windows compatibility placeholder: accepts the GNU-shaped command line surface, validates the plain-context form's required command operand, and reports that SELinux process contexts are not supported on Windows |
| `renice` | ✅ Done | Medium | Alter priority of running processes | `-n, --priority NUM`: Specify scheduling priority<br>`-p, --pid PID`: Interpret argument as process ID<br>`-u, --user USER`: Interpret argument as username<br>`-g, --pgrp PGID`: Interpret argument as process group ID | Alter process priority |
| `top` | ✅ Done | High | Display Linux processes | `-b, --batch`: Batch mode<br>`-d, --delay=SECONDS`: Delay between updates<br>`-n, --iterations=NUM`: Number of iterations<br>`-p, --pid=PID`: Monitor specific PIDs<br>`-u, --user=USER`: Monitor specific user<br>`-c, --command`: Show command line<br>`-o, --field-sort=FIELD`: Sort by field (CPU, MEM, TIME, PID, NAME)<br>`-h, --help`: Display help<br>`-v, --version`: Output version information | Real-time process monitor with interactive controls |
| `watch` | ✅ Done | Medium | Execute a program periodically | `-n, --interval=SECONDS`: Seconds to wait between updates<br>`-d, --differences[=cumulative]`: Highlight changes between updates<br>`-t, --no-title`: Turn off the header<br>`-x, --exec`: Pass command to exec instead of sh | Periodic execution |
| `timeout` | ✅ Done | Medium | Run a command with a time limit | `-s, --signal=SIGNAL`: Send this signal on timeout<br>`--preserve-status`: Exit with the same status as COMMAND<br>`--foreground`: When not running timeout directly from a shell prompt, allow COMMAND to read from the TTY<br>`-k, --kill-after=DURATION`: If the command is still running after the initial timeout, send this signal | Time-limited execution; missing operand / missing command now include the GNU-style help hint and return exit `125`, parse-time invalid options also return `125` with the standard help hint, `--foreground` no longer disables timeout enforcement on Windows, invalid signal / duration / kill-after usage errors also return `125` with GNU-shaped diagnostics, verbose timeout reports prefer signal names like `TERM`, `-s0` with `-k/--kill-after` now defers the forced termination to the KILL phase and returns `137` like GNU/uutils, and child argv is now quoted with Windows `CreateProcessW` rules so spaced arguments stay single arguments |
| `vdir` | ✅ Done | Medium | List directory contents in long format by default | `OPTION... FILE...`: Forward the GNU `vdir` wrapper surface to `ls -l` | Wrapper around `ls` with long-format output as the default; forwarded argv now keeps the original option/operand order, so GNU wrapper options such as `-a` and `-d` actually reach `ls`, and single arguments containing spaces are preserved via Windows `CreateProcessW` quoting rules |
| `jobs` | ✅ Done | Medium | Display status of jobs in the current shell | `-l, --list`: List process IDs in addition to the normal information<br>`-n, --names`: List only jobs that have changed status since the last notification<br>`-p, --pid`: List only the process IDs of the job's process group leader<br>`-r, --running`: List only running jobs<br>`-s, --stopped`: List only stopped jobs | Job status display |
| `bg` | ✅ Done | Medium | Resume a job in the background | JOB_SPEC: Job specification or - for current job | Background job resume |
| `fg` | ✅ Done | Medium | Resume a job in the foreground | JOB_SPEC: Job specification or - for current job | Foreground job resume |
| `disown` | ✅ Done | Medium | Remove jobs from current shell | `-a, --all`: Remove all jobs if JOB_SPEC is not supplied<br>`-h, --help`: Display help<br>`-r, --running`: Remove only running jobs | Job removal |
| `wait` | ✅ Done | Medium | Wait for process to finish | PID: Process ID to wait for | Process wait |
| `env` | ✅ Done | Medium | Run a command in a modified environment | `-i, --ignore-environment`: Start with an empty environment<br>`-u, --unset=NAME`: Remove variable from the environment; repeatable<br>`-0, --null`: End each printed environment entry with NUL; rejected when COMMAND is present with GNU/uutils-style exit `125`<br>`-S, --split-string=S`: Split S into arguments using the current lightweight parser; unterminated quotes now fail with exit `125`<br>`-v, --debug`: Emit processing diagnostics on standard error; repeated debug flags such as `-vv` also dump raw input arguments<br>`-a, --argv0=STRING`: Override the child process `argv[0]` while still executing the original program<br>`-C, --chdir=DIR`: Change working directory before running COMMAND; GNU-style usage requires that a command be present<br>`NAME=VALUE`: Add or override an environment variable<br>`COMMAND [ARG]...`: Run COMMAND with the modified environment | Prints or executes with a materialized Windows environment block; parse-time invalid options now also return GNU/uutils-style exit `125` with the standard help hint, `-a/--argv0`, `-C/--chdir`, and `-S/--split-string` now follow last-occurrence precedence, `-0/--null` is limited to environment-printing mode and now fails with `cannot specify --null (-0) with command` when combined with a command, missing child commands now report a GNU-shaped `failed to run command 'CMD': ...` diagnostic while preserving the conventional `127` not-found exit, and full GNU `-S` parsing plus remaining GNU debug/signal details remain gaps |
| `printenv` | ✅ Done | Medium | Print all or part of environment | `-0, --null`: End each output line with NUL | Environment variable display; named empty variables still emit an empty record, mixed found/missing names keep the found output while returning status `1`, variable-name operands containing `=` are silently ignored while still causing exit status `1`, invalid options now follow GNU/uutils by returning exit `2` with the standard help hint, and full enumeration skips hidden Windows `=...` pseudo-entries |
| `export` | ✅ Done | Medium | Set an environment variable | No options | Environment variable export |
| `unset` | ✅ Done | Medium | Unset values and attributes of shell variables | No options | Variable unset |
| `logname` | ✅ Done | Low | Print user's login name | No regular options | Login name display; dispatcher-level `-V/--version` now succeeds |
| `whoami` | ✅ Done | Low | Print effective userid | No regular options | User ID display; dispatcher-level `-V/--version` now succeeds |
| `id` | ✅ Done | Medium | Print user and group information | `-a, --all`: Ignore, for compatibility with other versions<br>`-g, --group`: Print only the effective group ID<br>`-G, --groups`: Print all group IDs<br>`-n, --name`: Print a name instead of a number<br>`-r, --real`: Print the real ID instead of the effective ID<br>`-u, --user`: Print only the effective user ID | User and group information |
| `users` | ✅ Done | Low | Print the user names of users currently logged in | No options | Logged-in users display |
| `who` | ✅ Done | Low | Show who is logged on | `-a, --all`: Same as -b -d --login -p -r -t -T -u<br>`-b, --boot`: Time of last system boot<br>`-d, --dead`: Print dead processes<br>`-H, --heading`: Print line of column headings<br>`-l, --login`: Print system login processes<br>`-m`: Only hostname and user associated with stdin<br>`-p, --process`: Print active processes spawned by init<br>`-q, --count`: All login names and number of users logged on<br>`-r, --runlevel`: Print current runlevel<br>`-s, --short`: Print only name, line, and time<br>`-t, --time`: Print last system clock change<br>`-u, --users`: List users logged in | User information |
| `groups` | ✅ Done | Low | Print the groups a user is in | `--help`: Display help<br>`--version`: Output version information | Group information |
| `hostname` | ✅ Done | Low | Show or set the system's host name | `-a, --alias`: Alias names<br>`-A, --all-fqdns`: All long host names<br>`-d, --domain`: DNS domain name<br>`-f, --fqdn`: FQDN<br>`-i, --ip-address`: Addresses for the host name<br>`-I, --all-ip-addresses`: All addresses for the host<br>`-s, --short`: Short host name<br>`-y, --yp, --nis`: NIS/YP domain name | Host name display |
| `hostid` | ✅ Done | Low | Print the numeric identifier of the current host | No regular options | Host ID display; dispatcher-level `-V/--version` now succeeds |
| `uname` | ✅ Done | Medium | Print system information | `-a, --all`: Print all information<br>`-s, --kernel-name`: Print the kernel name<br>`-n, --nodename`: Print the network node hostname<br>`-r, --kernel-release`: Print the kernel release<br>`-v, --kernel-version`: Print the kernel version<br>`-m, --machine`: Print the machine hardware name<br>`-p, --processor`: Print the processor type<br>`-i, --hardware-platform`: Print the hardware platform<br>`-o, --operating-system`: Print the operating system | System information |
| `arch` | ✅ Done | Low | Print machine architecture | No regular options | Architecture display; dispatcher-level `-V/--version` now succeeds |
| `uptime` | ✅ Done | Medium | Tell how long the system has been running | `-p, --pretty`: Show uptime in pretty format<br>`-s, --since`: System up since<br>`-h, --help`: Display help<br>`-V, --version`: Output version information | System uptime |
| `date` | ✅ Done | Medium | Print or set system date/time | `-d, --date=STRING`: Display time described by STRING<br>`--debug`: Print date-parsing diagnostics<br>`-f, --file=DATEFILE`: Read date strings from a file<br>`-I, --iso-8601[=TIMESPEC]`: ISO 8601 output<br>`-r, --reference=FILE`: Use FILE's time<br>`--resolution`: Print time resolution<br>`-R, --rfc-email`: RFC 5322-style date output<br>`--rfc-3339=TIMESPEC`: RFC 3339-style output<br>`-s, --set=STRING`: Set the system time<br>`-u, --utc, --universal`: Print or set Coordinated Universal Time (UTC)<br>`+FORMAT`: Output format string | Date/time display and formatting |
| `cal` | ✅ Done | Low | Display a calendar | `-1, --one`: Show only the current month (default)<br>`-3, --three`: Show previous, current and next month<br>`-s, --sunday`: Sunday as first day of week<br>`-m, --monday`: Monday as first day of week<br>`-j, --julian`: Output Julian dates<br>`-y, --year`: Show whole current year<br>`-Y, --year=YEAR`: Show whole year<br>`-w, --week[=TYPE]`: Show week numbers | Calendar display |
| `uptime` | ✅ Done | Medium | Tell how long the system has been running | `-p, --pretty`: Show uptime in pretty format<br>`-s, --since`: System up since | System uptime |
| `df` | ✅ Done | Medium | Report file system disk space usage | `-h, --human-readable`: Print sizes in powers of 1024<br>`-H, --si`: Print sizes in powers of 1000<br>`-k`: Use 1K blocks<br>`-T, --print-type`: Print file system type<br>`-i, --inodes`: List inode-shaped information instead of block usage; Windows prints placeholder inode columns<br>File operands use the shared wildcard policy<br>`-t, --type=TYPE`, `-x, --exclude-type=TYPE`, `-a, --all`: tracked in the GNU parity ledger | Disk space reporting |
| `du` | ✅ Done | Medium | Estimate file space usage | `-a, --all`: Write counts for all files, not just directories<br>`-B, --block-size=SIZE`: Scale sizes by SIZE before printing<br>`-b, --bytes`: Equivalent to apparent-size with block size 1<br>`-c, --total`: Produce a grand total<br>`-d, --max-depth=N`: Print entries only if they are N or fewer levels below the command line argument<br>`-h, --human-readable`: Print sizes in powers of 1024<br>`--si`: Print sizes in powers of 1000<br>`-H, --dereference-args`: Accept GNU dereference-args surface on Windows<br>`-k`: Use 1K blocks<br>`-m`: Use 1M blocks<br>`-0, --null`: End each output record with NUL instead of newline<br>`-S, --separate-dirs`: Exclude subdirectory totals from each parent directory's reported size<br>`--time[=WORD]`: Show the latest selected timestamp for each emitted entry; supports `mtime`, `atime|access|use`, and `ctime|status`<br>`-X, --exclude-from=FILE`: Read exclude glob patterns from FILE<br>`--files0-from=FILE`: Read NUL-delimited path operands from FILE<br>`-s, --summarize`: Display only a total for each argument | File/directory size estimation; file operands use the shared wildcard policy, `--exclude-from` patterns feed the same matcher as `--exclude`, block counts round up, and `ctime`/`status` currently map to creation time on Windows |
| `free` | ✅ Done | Medium | Display amount of free and used memory in the system | `-b, --bytes`: Display the amount of memory in bytes<br>`-k, --kilo`: Display the amount of memory in kilobytes<br>`-m, --mega`: Display the amount of memory in megabytes<br>`-g, --giga`: Display the amount of memory in gigabytes<br>`--tera`: Display the amount of memory in terabytes<br>`-h, --human`: Show human-readable output<br>`-l, --lohi`: Show detailed low and high memory statistics | Memory usage display |
| `lsof` | ✅ Done | Medium | List open files | No options | Open file listing |
| `pwd` | ✅ Done | High | Print working directory | `-L, --logical`: Use an absolute `PWD` from the environment when it still names the current directory<br>`-P, --physical`: Avoid all symlinks | Working directory display; `-L` now prefers `PWD` only when it is absolute, still resolves to the current directory, and contains no `.` / `..` components, `-L/-P` follow last-occurrence precedence, the current default remains physical-mode output, and extra non-option operands now warn with GNU-shaped `ignoring non-option arguments` stderr output |
| `ps` | ✅ Done | High | Report process status | `-e, -A`: Select all processes<br>`-a`: Select all processes except both session leaders and processes not associated with a terminal<br>`-x`: Select processes without controlling ttys<br>`-f`: Full-format listing<br>`-l`: Long format<br>`-u USER`: Select by effective user ID or name<br>`-w`: Wide output<br>`--no-headers`: Print no header<br>`--sort=KEY`: Sort by column | Process listing and filtering; this is a repo-local implementation, not a GNU Coreutils manual page |
| `which` | ✅ Done | High | Locate a command in PATH | `-a, --all`: Print all matching pathnames of each argument<br>`--read-alias`, `--skip-alias`: Read or skip alias expansion<br>`--read-functions`, `--skip-functions`: Read or skip shell function expansion<br>`--skip-dot`: Skip directories in PATH that start with a dot<br>`--show-dot`: Allow directories that start with a dot to be shown<br>`--skip-tilde`: Skip directories in PATH that start with a tilde<br>`--show-tilde`: Allow directories that start with a tilde to be shown<br>`--tty-only`: Show matches only on a tty | Path searching with PATHEXT support, SmallVector optimization |
| `nproc` | ✅ Done | Low | Print the number of processing units available | `--all`: Print the number of installed processing units<br>`--ignore=N`: If possible, exclude N processing units | Processor count |
| `numfmt` | ✅ Done | Low | Convert numbers from/to human-readable strings | `-d, --delimiter=X`: Use X instead of whitespace for field delimiter<br>`-f, --format=FORMAT`: Use printf style floating-point FORMAT<br>`--from=UNIT`: Auto-scale input numbers to UNITs<br>`--to=UNIT`: Auto-scale output numbers to UNITs<br>`--round=METHOD`: Use METHOD for rounding<br>`--padding=N`: Pad the output to N characters | Number formatting |
| `column` | ✅ Done | Low | Columnate lists | `-c, --output-width=WIDTH`: Set output width<br>`-t, --table`: Determine the number of columns the table contains<br>`-s, --separator SEPARATOR`: Specify the possible input item delimiters<br>`-o, --output-separator STRING`: Specify the column separator for table output<br>`-x, --fillrows`: Fill rows before filling columns | Column formatting |
| `jq` | ✅ Done | Medium | Command-line JSON processor | `-c, --compact-output`: Compact instead of pretty-printed output<br>`-r, --raw-output`: Output raw strings<br>`-s, --slurp`: Read (slurp) all inputs into an array<br>`-R, --raw-input`: Read raw strings<br>`-M, --monochrome-output`: Don't colorize JSON | JSON processing |
| `tr` | ✅ Done | Medium | Translate or delete characters | `-c, -C, --complement`: Use the complement of SET1<br>`-d, --delete`: Delete characters in SET1<br>`-s, --squeeze-repeats`: Replace each sequence of a repeated character<br>`-t, --truncate-set1`: First truncate SET1 to length of SET2 | Character translation and deletion; operand-count diagnostics now distinguish missing `SET2`, `-d -s` missing the squeeze set, and delete-mode extra operands with GNU-style help hints |
| `mktemp` | ✅ Done | Medium | Create a temporary file or directory | `-d, --directory`: Create a directory, not a file<br>`-u, --dry-run`: Do not actually create anything<br>`-q, --quiet`: Fail silently if an error occurs<br>`--suffix=SUFFIX`: Append SUFFIX to TEMPLATE; SUFFIX must not contain a path separator<br>`-p, --tmpdir[=DIR]`: Interpret TEMPLATE relative to DIR<br>`-t`: Generate a template (using the temporary directory's path) | Temporary file/directory creation; explicit `--suffix=SUFFIX` now appends the suffix after template substitution, rejects suffixes containing `/` or `\` with a GNU/Microsoft-shaped diagnostic, and preserves generated paths in output when `--tmpdir` or a directory-bearing template is used |
| `mkfifo` | ✅ Done | Medium | Create named pipes (FIFOs) | `-m, --mode=MODE`: Set file permission bits<br>`-Z`: Set the SELinux security context to default type<br>`--context[=CTX]`: Set the SELinux security context<br>`NAME...`: FIFO names to create | Windows compatibility placeholder: validates the GNU-shaped option surface, preserves GNU-shaped `missing operand` and `File exists` diagnostics, and reports that filesystem FIFOs are not supported on Windows |
| `mknod` | ✅ Done | Medium | Create special files | `-m, --mode=MODE`: Set file permission bits<br>`-Z`: Set the SELinux security context to default type<br>`--context[=CTX]`: Set the SELinux security context<br>`NAME TYPE [MAJOR MINOR]`: GNU operand form; `TYPE` accepts `b`, `c`/`u`, `p` | Windows compatibility placeholder: validates GNU operand combinations such as `p` versus `b/c` major/minor rules, preserves GNU-shaped `missing operand` and `File exists` diagnostics, and reports that special files are not supported on Windows |
| `mpicalc` | ✅ Done | Low | Simple arbitrary-precision calculator | No options | Arbitrary precision calculation |
| `hmac256` | ✅ Done | Low | Compute HMAC-SHA256 | `--help`: Display help<br>`--version`: Output version information | HMAC computation |
| `pinky` | ✅ Done | Low | Lightweight finger | `-l`: Produce long format output<br>`-b`: Omit the user's home directory and shell<br>`-h`: Omit the user's project file<br>`-p`: Omit the user's plan file<br>`-s`: Do short format output | User information |
| `seq` | ✅ Done | Low | Print a sequence of numbers | `-f, --format=FORMAT`: Use printf style floating-point FORMAT<br>`-s, --separator=STRING`: Use STRING to separate numbers<br>`-t, --terminator=STRING`: Use STRING instead of the final newline<br>`-w, --equal-width`: Equalize width by padding with leading zeroes | Sequence generation; missing and extra operands now include GNU-style help hints, `-t/--terminator` now replaces only the final output separator while leaving intermediate separators unchanged, and `-w` now rejects an explicit `-f/--format` string with the GNU/uutils-style conflict diagnostic |
| `sleep` | ✅ Done | Low | Delay for a specified time | `NUMBER[SUFFIX]`: Pause for NUMBER seconds | Sleep delay; missing operands now include the GNU-style help hint, malformed or negative durations now use GNU-shaped `invalid time interval` diagnostics, multiple invalid duration operands are now all reported before the final help hint, leading whitespace remains accepted, and trailing whitespace is now rejected like GNU/uutils |
| `yes` | ✅ Done | Low | Output a string repeatedly | `STRING...`: Strings to join with spaces before repeating | Repeated output; GNU/uutils-style multi-operand invocations now join all operands with single spaces instead of using only the first operand, and `-V/--version` now succeeds instead of being misparsed as an unknown option |

### System Utilities

| Command | Status | Priority | Description | Parameters/Options | Implementation Notes |
|---------|--------|----------|-------------|-------------------|---------------------|
| `help` | ✅ Done | High | Display help information about commands | `COMMAND`: Display help for specific command | Uses command metadata for help generation |
| `man` | ✅ Done | Low | Display manual pages | `COMMAND`: Display the manual page for a command | Repo-local manual lookup with `.exe` handling |
| `exit` | ✅ Done | High | Exit the shell | No options | Simple exit call with pipeline structure |
| `clear` | ✅ Done | High | Clear the terminal screen | No options | Uses system call to clear screen |
| `cd` | ✅ Done | High | Change the current directory | `-L, --logical`: Force symbolic links to be followed<br>`-P, --physical`: Use the physical directory structure without following symbolic links | Uses SetCurrentDirectory API with pipeline structure |
| `type` | ❌ TODO | Medium | Describe command type | `COMMAND`: Describe specific command | Not yet implemented |
| `alias` | ❌ TODO | Low | Create an alias for a command | `NAME=VALUE`: Define an alias<br>`-p`: Print all defined aliases | Not yet implemented |

## Implementation Guidelines

### General Structure

Each command should follow this general structure:

1. **Module Declaration**: Start with `export module cmd.<command>;`
2. **Imports**: Import necessary modules (`import core;`, `import utils;`, etc.)
3. **Constants Namespace**: Define command-specific constants
4. **Option Definitions**: Define command options using the `OPTION` macro
5. **Pipeline Components**: Implement pipeline components for command processing
6. **Command Implementation**: Implement the main command logic
7. **Registration**: Register the command using `REGISTER_COMMAND` macro

### Example Structure

```cpp
export module cmd.echo;

import core;
import utils;

using cmd::meta::OptionMeta;
using cmd::meta::OptionType;

namespace echo_constants {
    // Command-specific constants
}

// Define options
export auto constexpr ECHO_OPTIONS =
    std::array{
        OPTION("-n", "--no-newline", "do not output the trailing newline"),
        OPTION("-e", "--escape", "enable interpretation of backslash escapes"),
    };

namespace echo_pipeline {
    namespace cp = core::pipeline;

    // Validate arguments
    auto validate_arguments(std::span<const std::string_view> args) -> cp::Result<std::vector<std::string>> {
        std::vector<std::string> validated_args;
        for (auto arg : args) {
            validated_args.push_back(std::string(arg));
        }
        return validated_args;
    }

    // Build text from arguments
    auto build_text(const std::vector<std::string>& args) -> std::string {
        std::string text;
        for (size_t i = 0; i < args.size(); ++i) {
            text += args[i];
            if (i < args.size() - 1) {
                text += " ";
            }
        }
        return text;
    }

    // Handle escape sequences
    auto to_uppercase(std::string text) -> std::string {
        std::ranges::transform(text, text.begin(), ::toupper);
        return text;
    }

    // Process command
    template<size_t N>
    auto process_command(const CommandContext<N>& ctx)
        -> cp::Result<std::string>
    {
        auto args_result = validate_arguments(ctx.positionals);
        if (!args_result) {
            return args_result.error();
        }
        auto args = *args_result;
        return build_text(args);
    }

}

REGISTER_COMMAND(echo,
                 /* name */
                 "echo",

                 /* synopsis */
                 "echo [SHORT-OPTION]... [STRING]...",

                 /* description */
                 "Display a line of text.",

                 /* examples */
                 "  echo Hello World      Display 'Hello World'\n"
                 "  echo -n Hello         Display 'Hello' without trailing newline\n"
                 "  echo -e Hello\\nWorld  Display 'Hello' and 'World' on separate lines",

                 /* see_also */
                 "cat, printf",

                 /* author */
                 "WinuxCmd Team",

                 /* copyright */
                 "Copyright © 2026 WinuxCmd",

                 /* options */
                 ECHO_OPTIONS
) {
    using namespace echo_pipeline;

    auto result = process_command(ctx);
    if (!result) {
        cp::report_error(result, L"echo");
        return 1;
    }

    auto text = *result;

    // Get options
    bool no_newline = ctx.get<bool>("--no-newline", false);
    bool escape = ctx.get<bool>("--escape", false);

    // Handle escape sequences if enabled
    if (escape) {
        // Implement escape sequence handling
    }

    // Output result
    std::cout << text;
    if (!no_newline) {
        std::cout << std::endl;
    }

    return 0;
}
```

### Best Practices

1. **Pipeline Architecture**: Use pipeline components for modular processing
2. **Type Safety**: Use `CommandContext` for type-safe option access
3. **Error Handling**: Use `core::pipeline::Result` for consistent error handling
4. **Documentation**: Provide clear documentation for each command
5. **Testing**: Test commands with various inputs and options
6. **Performance**: Optimize for performance where appropriate
7. **Compatibility**: Follow POSIX standards where possible

### Testing

Each command should be tested with:

1. **Basic functionality**: Test the command with no options
2. **All options**: Test each option individually
3. **Combined options**: Test multiple options together
4. **Edge cases**: Test with empty inputs, large inputs, etc.
5. **Error cases**: Test with invalid inputs and options

## Migration Guide

### From Legacy Implementation

To migrate a command from the legacy implementation to the new pipeline-based structure:

1. **Update module declaration**: Use `export module cmd.<command>;`
2. **Add imports**: Add necessary imports (`import core;`, `import utils;`)
3. **Define options**: Use the `OPTION` macro to define options
4. **Create pipeline namespace**: Implement pipeline components
5. **Update command implementation**: Use `CommandContext` for option access
6. **Register command**: Use the new `REGISTER_COMMAND` macro

### Example Migration

#### After (Pipeline-Based Architecture)

```cpp
export module cmd.echo;

import core;
import utils;

using cmd::meta::OptionMeta;
using cmd::meta::OptionType;

namespace echo_constants {
    // Command-specific constants can be defined here
}

// Define options
export auto constexpr ECHO_OPTIONS =
    std::array{
        OPTION("-n", "--no-newline", "do not output the trailing newline"),
        OPTION("-e", "--escape", "enable interpretation of backslash escapes"),
    };

namespace echo_pipeline {
    namespace cp = core::pipeline;

    // Validate arguments
    auto validate_arguments(std::span<const std::string_view> args) -> cp::Result<std::vector<std::string>> {
        std::vector<std::string> validated_args;
        for (auto arg : args) {
            validated_args.push_back(std::string(arg));
        }
        return validated_args;
    }

    // Build text from arguments
    auto build_text(const std::vector<std::string>& args) -> std::string {
        std::string text;
        for (size_t i = 0; i < args.size(); ++i) {
            text += args[i];
            if (i < args.size() - 1) {
                text += " ";
            }
        }
        return text;
    }

    // Process command
    template<size_t N>
    auto process_command(const CommandContext<N>& ctx)
        -> cp::Result<std::string>
    {
        auto args_result = validate_arguments(ctx.positionals);
        if (!args_result) {
            return args_result.error();
        }
        auto args = *args_result;
        return build_text(args);
    }

}

REGISTER_COMMAND(echo,
                 /* name */
                 "echo",

                 /* synopsis */
                 "echo [SHORT-OPTION]... [STRING]...",

                 /* description */
                 "Display a line of text.",

                 /* examples */
                 "  echo Hello World      Display 'Hello World'\n"
                 "  echo -n Hello         Display 'Hello' without trailing newline\n"
                 "  echo -e Hello\\nWorld  Display 'Hello' and 'World' on separate lines",

                 /* see_also */
                 "cat, printf",

                 /* author */
                 "WinuxCmd Team",

                 /* copyright */
                 "Copyright © 2026 WinuxCmd",

                 /* options */
                 ECHO_OPTIONS
) {
    using namespace echo_pipeline;

    auto result = process_command(ctx);
    if (!result) {
        cp::report_error(result, L"echo");
        return 1;
    }

    auto text = *result;

    // Get options using CommandContext
    bool no_newline = ctx.get<bool>("--no-newline", false);
    bool escape = ctx.get<bool>("--escape", false);

    // Handle escape sequences if enabled
    if (escape) {
        // Implement escape sequence handling
    }

    // Output result
    std::cout << text;
    if (!no_newline) {
        std::cout << std::endl;
    }

    return 0;
}
```

## Reference Implementation

The `echo.cppm` file serves as the reference implementation for the new pipeline-based architecture. It demonstrates:

1. **Pipeline Components**: Separate validation and processing logic
2. **Option Handling**: Use of `CommandContext` for type-safe option access
3. **Error Handling**: Use of `core::pipeline::Result` for error reporting
4. **Command Registration**: Proper use of `REGISTER_COMMAND` macro

All new commands should follow this pattern for consistency and maintainability.