winuxcmd

name	winuxcmd
description	Repository-local WinuxCmd workflow for AI agents: download a released WinuxCmd build, integrate it into .winuxcmd/bin, activate the workspace without touching global PATH, use man.exe on Windows, run MSVC builds/tests, and package the skill for release. Use when working in this repository or preparing WinuxCmd release assets and the skill bundle.

WinuxCmd

Use this skill when working inside the WinuxCmd repository or when preparing a WinuxCmd release bundle.

Start Here

1. If you are already in the repo, activate the workspace-local command directory for the current shell:

.\scripts\activate-workspace.ps1

2. If you are in cmd, use:

scripts\activate-workspace.cmd

3. If you are starting from a downloaded WinuxCmd release, register the release binary in the workspace first:

.\scripts\setup-workspace-bin.ps1 -WinuxCmdPath "C:\path\to\winuxcmd.exe"
.\scripts\activate-workspace.ps1

4. When you need command help on Windows, call man.exe, not man.

Why man.exe

• PowerShell resolves aliases before native executables.
• man is often an alias for PowerShell help, so man.exe is the unambiguous WinuxCmd command.
• Use explicit .exe names whenever an alias could collide with a WinuxCmd tool.

Workspace Activation

• .winuxcmd/bin is the repo-local command directory.
• scripts/setup-workspace-bin.ps1 creates the command links there.
• scripts/activate-workspace.ps1 prepends .winuxcmd/bin to the current PowerShell session only and clears common alias collisions for that session.
• scripts/activate-workspace.cmd does the same for CMD sessions.
• scripts/install-workspace-profile-hook.ps1 adds a per-user PowerShell 7 / Windows PowerShell 5.1 hook so new shells auto-activate in this repository.
• If you are already inside an extracted release directory, scripts/create_links.ps1 can generate the release-side command links there.

Typical commands after activation:

man.exe ls
grep.exe -n TODO README.md
winuxcmd.exe help sort

Rules

• Do not modify user PATH or machine PATH.
• Do not rely on PowerShell aliases such as man or ls.
• Use the repository-local .winuxcmd\bin directory for command execution.
• If a command exists both as a PowerShell alias and as a WinuxCmd executable, always call the executable with .exe.

Build and Test

• Use scripts/build-with-vs.ps1 when you need an MSVC build/test run.
• Default target: winuxcmd-tests.
• Default build directory: build-vs.
• Default environment script: vcvars64.bat.

Command Guidance

• After activation, bare ls, cp, mv, rm, and similar common commands should resolve to WinuxCmd in the current session.
• Use the repo's GNU-parity flags when they reduce AI mistakes:
  • ls: -d, -b, -f, -I, -U, -X, -v, -i, -s, -h/--human-readable, --block-size=SIZE, -Q, -b, -q, -N, --quoting-style=WORD; directory long listings include total, hard-link counts come from Windows file metadata, -h humanizes long sizes and -s/total, sort/time/quoting-affecting options use last-occurrence precedence, and wildcard matches that are directories list contents unless -d is active
  • cp: -a/--archive, -p, -t, -T, -n, -u, -b/--backup, -S/--suffix; -t requires an existing directory, -t and -T conflict, self-copy is refused except --force --backup, and plain file copies do not create missing parents
  • mv: -t, -T, -n, -u, -b; -t requires an existing directory, -t and -T conflict, and ordinary multi-source moves require an existing target directory after wildcard expansion
  • rm: -f, -d/--dir, -r/-R/--recursive, -I, -i, --interactive[=never|once|always], --one-file-system; rm -f with no operands succeeds, -d removes only empty directories, and -f/-i/-I/--interactive=WHEN use last-option precedence for prompting/force behavior
  • install: -D, -d, -t, -T; -t and -T conflict, multi-source installs require an existing target directory after wildcard expansion, -D -t creates the target directory, and -d creates parent directories
  • sort: repeatable -k/--key with F[.C][OPTS][,F[.C][OPTS]], --sort=WORD, -M, -R, --random-source, -S/--buffer-size, -s, -t \0, -u, -V; -t \0 uses NUL as the field separator, global ordering modes use last-occurrence precedence, -n does not accept leading + or exponent notation, -h compares sign then SI suffix then value, -u uses sort-key equality and disables last-resort whole-line ordering, -c/-C -u rejects adjacent equal keys, -b affects -k F.C character counts, and end position .0 means field end
  • grep: -E, -F, -G, repeatable -e/--regexp, repeatable -f/--file, -i, -v, -n, -c, -l, -L, -H/-h, --label, --line-buffered, repeatable --include/--exclude/--exclude-from/--exclude-dir, -A/-B/-C context output, -o, -D/--devices, --color[=WHEN]; bare --color defaults to auto, invalid color modes fail, zero-byte -f pattern files match nothing, include/exclude file rules keep command-line order and the last matching rule wins, command-line file operands match include/exclude globs by name suffix, --exclude-dir skips matching command-line directories and ignores trailing slashes, context ranges merge, match prefixes use :, context prefixes use -, -o warns while ignoring context options, and wildcard operands that expand to directories recurse when -r/-R is active
  • sed: ordered repeatable -e/--expression and -f/--file, -i[SUFFIX] / --in-place[=SUFFIX], -n/--quiet/--silent, -E, -r, -s, -z/--null-data/--zero-terminated, -u/--unbuffered, -b/--binary; in-place editing creates no backup when suffix is omitted, appends suffix when it has no *, and replaces each * with the current filename otherwise; s/// supports &, \1-\9, numeric occurrence flags, g, p, and I/i; address negation with !, first~step, 0~step, and /regex/I are supported
  • head: -c, -n, -q, -v, -z; GNU count suffixes are accepted (KB/MB/.../QB decimal, K/M/.../Q binary, and KiB/.../QiB IEC) with overflow rejected; first-argument obsolete -[num][bkm][cqv] is accepted for compatibility, but prefer -c NUM or -n NUM
  • tail: -c, -n, -q, -v, -z, -f, -F, -s, --max-unchanged-stats, repeatable --pid, --debug, --retry; GNU count suffixes are accepted (KB/MB/.../QB decimal, K/M/.../Q binary, and KiB/.../QiB IEC) with overflow rejected; obsolete -[num][bcl][f] is accepted when it does not conflict with normal parsing, but prefer -c NUM, -n NUM, and -f
  • find: -L, -H, -name, -iname, -path, -ipath, -regex, -iregex, -type, -size, -empty, -mtime, -mmin, -newer, -mindepth, -maxdepth, -depth, -true, -false, !, -not, implicit AND, -a/-and, -o/-or, comma expressions, parentheses, -print, -print0, -printf (%p, %f, %h, %d, %y, %s, %m, %T@, %%), -delete, -prune, -quit, -exec ... {} ;, -exec ... {} +, -ok ... {} ;, -ok ... {} +; predicate operators and these common actions follow GNU expression precedence and short-circuit behavior; -H follows only command-line symlink roots unless -L is active; remaining gaps are full -printf, full GNU regex dialect details, and -delete plus -prune interaction edge cases
  • cut: -b/--bytes, -c/--characters, -f/--fields, --complement, --output-delimiter, -z
  • df: -h, -H, -k, -T/--print-type, -i/--inodes
  • du: -a, -A/--apparent-size, -B/--block-size, -b/--bytes, -c/--total, -d/--max-depth, -h, --si, -H/--dereference-args, -k, -m, -0/--null, -S/--separate-dirs, -s, -t/--threshold, --time[=WORD], --exclude=PATTERN, -X/--exclude-from, --files0-from; default output uses 1024-byte blocks, later size-display options override earlier ones, --block-size=human-readable|si is accepted, --max-depth=0 prints only the root total, --time=atime|access|use|ctime|status|mtime uses last-occurrence precedence, ctime/status currently map to creation time on Windows, --exclude patterns stay literal option patterns, Windows size reporting uses file length as the allocated/apparent-size approximation, and -H is not SI output
  • env: -i/--ignore-environment, repeatable -u/--unset=NAME, -0/--null, -C/--chdir=DIR, NAME=VALUE COMMAND [ARG]...
  • printenv: -0/--null; named empty variables still emit empty records, mixed found/missing names preserve found output while returning status 1, and full enumeration skips Windows hidden =... pseudo-entries
  • tty: -s/--silent, --quiet; extra operands keep GNU-style stderr diagnostics with exit 2, non-tty stdin returns 1, and broken stdout during non-silent output returns GNU/uutils-style exit 3
  • pwd: -L/--logical, -P/--physical; default output remains physical, -L prefers an absolute PWD environment value when present, and the -L/-P family uses last-occurrence precedence
  • realpath: -e, -E, -m, -q, -s, -z, --relative-to, --relative-base; at least one path operand is required, canonicalization-mode options use last-occurrence precedence, empty path / relative-option operands are rejected as invalid empty strings, and under -e the relative-option operands must resolve to directories
  • readlink: -f, -e, -m, -n, -q, -s, -v, -z; canonical modes normalize Windows paths, default diagnostics stay quiet, and the -q/-s/-v family uses last-occurrence precedence
  • xargs: -n/--max-args, -L/--max-lines, -l, -I, -i/--replace, -P/--max-procs, -p/--interactive, -0/--null, -d/--delimiter, -a/--arg-file, -E, -e/--eof, --show-limits, -t/--verbose, -o/--open-tty, -r/--no-run-if-empty, -s/--max-chars, -x/--exit, --process-slot-var; -p prompts before each command and runs only for y/Y, default echo output has no trailing space; mutually exclusive -I/-i, -L/-l, and -n families use the last conflicting family and warn, except -I ... -n1; child failures map GNU-style for common cases (1..125 -> 123, 255 -> 124, not found -> 127)
  • dd: if=, of=, bs=, ibs=, obs=, count=, skip=, seek=, conv=sync, conv=notrunc, status=none|noxfer|progress
• Treat wildcard characters as syntax unless the operand is a file input: grep patterns, sed scripts, jq filters, xargs input items, and destination operands such as tee OUT or install SRC DEST stay literal. File input operands such as grep PATTERN *.txt and sed SCRIPT *.txt expand inside WinuxCmd.
• For fixed-arity file commands such as diff, diff3, split, and csplit, let wildcard expansion resolve to the exact number of operands the command expects; do not guess a first match.
• Keep the implementation matrix and GNU parity ledger synchronized with code changes in the same batch.
• If a command is already available as a WinuxCmd executable, prefer it over a PowerShell alias or external fallback.

Release Packaging

• When packaging the skill, load references/release-packaging.md first.
• Confirm the bundle layout, then package the standalone bundle with the Windows binaries.
• Keep the skill bundle rooted at winuxcmd/ with SKILL.md at the top level of the archive.
• Keep the skill bundle small and release-ready; long-form details belong in references/.

References

• references/workspace-integration.md
• references/download-and-integrate.md
• references/command-guidance.md
• references/release-packaging.md