batch-files

Batch Files

A comprehensive skill for creating, editing, debugging, and maintaining Windows batch files (.bat/.cmd) using cmd.exe. Applies to CLI tool development, system administration automation, scheduled tasks, file operations scripting, and PATH-based executable scripts.

When to Use This Skill

• Creating or editing .bat or .cmd files
• Automating Windows tasks (file operations, deployments, backups)
• Building CLI tools intended for a bin/ folder on PATH
• Writing scheduled task scripts (SCHTASKS, Task Scheduler)
• Debugging batch script issues (variable expansion, error levels, quoting)
• Integrating batch scripts with external tools (curl, git, Node.js, Python)
• Scaffolding new batch-based projects with structured templates

Prerequisites

• Windows NT-based OS (Windows 7 or later)
• cmd.exe (built-in)
• Optional: a bin/ directory on PATH for distributing scripts as commands
• Optional: PATHEXT configured to include .BAT;.CMD (default on Windows)

Command Interpretation

cmd.exe processes each line through four stages in order:

1. Variable substitution — %VAR% tokens are replaced with environment variable values. %0–%9 reference batch arguments. %* expands to all arguments.
2. Quoting and escaping — Caret ^ escapes special characters (& | < > ^). Quotation marks prevent interpretation of enclosed special characters. In batch files, %% yields a literal %.
3. Syntax parsing — Lines are split into pipelines (|), compound commands (&, &&, ||), and parenthesized groups ( ).
4. Redirection — > overwrites, >> appends, < reads input, 2> redirects stderr, 2>&1 merges stderr into stdout, >NUL discards output.

Variables

Environment Variables

set _MY_VAR=Hello World
echo %_MY_VAR%
set _MY_VAR=

• set with no arguments lists all variables
• set _PREFIX lists variables starting with _PREFIX
• No spaces around = — set name = val sets variable "name " to " val"

Special Variables

| Variable | Value |

|----------|-------|

| %CD% | Current directory |

| %DATE% | System date (locale-dependent) |

| %TIME% | System time HH:MM:SS.mm |

| %RANDOM% | Pseudorandom number 0–32767 |

| %ERRORLEVEL% | Exit code of last command |

| %USERNAME% | Current user name |

| %USERPROFILE% | Current user profile path |

| %TEMP% / %TMP% | Temporary file directory |

| %PATHEXT% | Executable extensions list |

| %COMSPEC% | Path to cmd.exe |

Scoping with SETLOCAL / ENDLOCAL

setlocal
set _LOCAL_VAR=scoped value
endlocal
REM _LOCAL_VAR is no longer defined here

To return a value from a scoped block:

endlocal & set _RESULT=%_LOCAL_VAR%

Delayed Expansion

Variables inside parenthesized blocks are expanded at parse time. Use delayed expansion for runtime evaluation:

setlocal EnableDelayedExpansion
set _COUNT=0
for /l %%i in (1,1,5) do (
    set /a _COUNT+=1
    echo !_COUNT!
)
endlocal

• !VAR! expands at execution time (delayed)
• %VAR% expands at parse time (immediate)

Control Flow

Conditional Execution

if exist "output.txt" echo File found
if not defined _MY_VAR echo Variable not set
if "%_STATUS%"=="ready" (echo Go) else (echo Wait)
if %ERRORLEVEL% neq 0 echo Command failed

Comparison operators: equ, neq, lss, leq, gtr, geq. Use /i for case-insensitive string comparison.

Compound Commands

command1 & command2        & REM Always run both
command1 && command2       & REM Run command2 only if command1 succeeds
command1 || command2       & REM Run command2 only if command1 fails

FOR Loops

REM Iterate over a set of values
for %%i in (alpha beta gamma) do echo %%i

REM Numeric range: start, step, end
for /l %%i in (1,1,10) do echo %%i

REM Files in a directory
for %%f in (*.txt) do echo %%f

REM Recursive file search
for /r %%f in (*.log) do echo %%f

REM Directories only
for /d %%d in (*) do echo %%d

REM Parse command output
for /f "tokens=1,2 delims=:" %%a in ('ipconfig ^| findstr "IPv4"') do echo %%b

REM Parse file lines
for /f "usebackq tokens=*" %%a in ("data.txt") do echo %%a

GOTO and Labels

goto :main_logic
:usage
echo Usage: %~nx0 [options]
exit /b 1

:main_logic
echo Running main logic...
goto :eof

goto :eof exits the current batch or subroutine. Labels start with :.

Command-Line Arguments

| Syntax | Value |

|--------|-------|

| %0 | Script name as invoked |

| %1–%9 | Positional arguments |

| %* | All arguments (unaffected by SHIFT) |

| %~1 | Argument 1 with enclosing quotes removed |

| %~f1 | Full path of argument 1 |

| %~d1 | Drive letter of argument 1 |

| %~p1 | Path (without drive) of argument 1 |

| %~n1 | File name (no extension) of argument 1 |

| %~x1 | Extension of argument 1 |

| %~dp0 | Drive and path of the batch file itself |

| %~nx0 | File name with extension of the batch file |

| %~z1 | File size of argument 1 |

| %~$PATH:1 | Search PATH for argument 1 |

Argument Parsing Pattern

:parse_args
if "%~1"=="" goto :args_done
if /i "%~1"=="--help" goto :usage
if /i "%~1"=="--output" (
    set "_OUTPUT_DIR=%~2"
    shift
)
shift
goto :parse_args
:args_done

String Processing

Substrings

set _STR=Hello World
echo %_STR:~0,5%       & REM "Hello"
echo %_STR:~6%         & REM "World"
echo %_STR:~-5%        & REM "World"
echo %_STR:~0,-6%      & REM "Hello"

Search and Replace

set _STR=Hello World
echo %_STR:World=Earth%       & REM "Hello Earth"
echo %_STR:Hello=%            & REM " World" (remove "Hello")

Substring Containment Test

if not "%_STR:World=%"=="%_STR%" echo Contains "World"

Functions

Functions use labels, CALL, and SETLOCAL/ENDLOCAL:

@echo off
call :greet "Jane Doe"
echo Result: %_GREETING%
exit /b 0

:greet
setlocal
set "_MSG=Hello, %~1"
endlocal & set "_GREETING=%_MSG%"
exit /b 0

• call :label args invokes a function
• exit /b returns from the function (not the script)
• Use the endlocal & set trick to pass values out of a scoped block

Arithmetic

set /a performs 32-bit signed integer arithmetic:

set /a _RESULT=10 * 5 + 3
set /a _COUNTER+=1
set /a _REMAINDER=14 %% 3       & REM Use %% for modulo in batch files
set /a _BITS="255 & 0x0F"       & REM Bitwise AND

Supported operators: + - * / %% ( ) and bitwise & | ^ ~ << >>.

Hexadecimal (0xFF) and octal (077) literals are supported.

Error Handling

Error Level Conventions

• 0 = success
• Non-zero = failure (typically 1)

mycommand.exe
if %ERRORLEVEL% neq 0 (
    echo ERROR: mycommand failed with code %ERRORLEVEL%
    exit /b %ERRORLEVEL%
)

Fail-Fast Pattern

command1 || (echo command1 failed & exit /b 1)
command2 || (echo command2 failed & exit /b 1)

Setting Exit Codes

exit /b 0        & REM Return success from a batch/function
exit /b 1        & REM Return failure
cmd /c "exit /b 42"   & REM Set ERRORLEVEL to 42 inline

Essential Commands Reference

File Operations

| Command | Purpose |

|---------|---------|

| DIR | List directory contents |

| COPY | Copy files |

| XCOPY | Extended copy with subdirectories (legacy) |

| ROBOCOPY | Robust copy with retry, mirror, logging |

| MOVE | Move or rename files |

| DEL | Delete files |

| REN | Rename files |

| MD / MKDIR | Create directories |

| RD / RMDIR | Remove directories |

| MKLINK | Create symbolic or hard links |

| ATTRIB | View or set file attributes |

| TYPE | Print file contents |

| MORE | Paginated file display |

| TREE | Display directory structure |

| REPLACE | Replace files in destination with source |

| COMPACT | Show or set NTFS compression |

| EXPAND | Extract from .cab files |

| MAKECAB | Create .cab archives |

| TAR | Create or extract tar archives |

Text Search and Processing

| Command | Purpose |

|---------|---------|

| FIND | Search for literal strings |

| FINDSTR | Search with limited regular expressions |

| SORT | Sort lines alphabetically |

| CLIP | Copy piped input to clipboard |

| FC | Compare two files |

| COMP | Binary file comparison |

| CERTUTIL | Encode/decode Base64, compute hashes |

System Information

| Command | Purpose |

|---------|---------|

| SYSTEMINFO | Full system configuration |

| HOSTNAME | Display computer name |

| VER | Windows version |

| WHOAMI | Current user and group info |

| TASKLIST | List running processes |

| TASKKILL | Terminate processes |

| WMIC | WMI queries (drives, OS, memory) |

| SC | Service control (query, start, stop) |

| DRIVERQUERY | List installed drivers |

| REG | Registry operations (query, add, delete) |

| SETX | Set persistent environment variables |

Network

| Command | Purpose |

|---------|---------|

| PING | Test network connectivity |

| IPCONFIG | IP configuration |

| NSLOOKUP | DNS lookup |

| NETSTAT | Network connections and ports |

| TRACERT | Trace route to host |

| NET USE | Map/disconnect network drives |

| NET USER | Manage user accounts |

| NETSH | Network configuration utility |

| ARP | ARP cache management |

| ROUTE | Routing table management |

| CURL | HTTP requests (Windows 10+) |

| SSH | Secure shell (Windows 10+) |

Scheduling and Automation

| Command | Purpose |

|---------|---------|

| SCHTASKS | Create and manage scheduled tasks |

| TIMEOUT | Wait N seconds (Vista+) |

| START | Launch programs asynchronously |

| RUNAS | Run as different user |

| SHUTDOWN | Shutdown or restart |

| FORFILES | Find files by date and execute commands |

Shell Utilities

| Command | Purpose |

|---------|---------|

| WHERE | Locate executables in PATH |

| DOSKEY | Create command macros |

| CHOICE | Prompt for single-key input |

| MODE | Configure console size and ports |

| SUBST | Map folder to drive letter |

| CHCP | Get or set console code page |

| COLOR | Set console colors |

| TITLE | Set console window title |

| ASSOC / FTYPE | File type associations |

Shell Syntax and Expressions

Parentheses for Grouping

Parentheses turn compound commands into a single unit for redirection or conditional execution:

(echo Line 1 & echo Line 2) > output.txt
if exist "data.csv" (
    echo Processing...
    call :process "data.csv"
) else (
    echo No data found.
)

Escape Characters

The caret ^ escapes the next character:

echo Total ^& Summary          & REM Outputs: Total & Summary
echo 100%% complete            & REM Outputs: 100% complete (in batch)
echo Line one^
Line two                       & REM Caret escapes the newline

After a pipe, triple caret is needed: echo x ^^^& y | findstr x

Wildcards

• * matches any sequence of characters
• ? matches a single character (or zero at end of period-free segment)

dir *.txt           & REM All .txt files
ren *.jpeg *.jpg    & REM Bulk rename

Redirection Summary

command > file.txt          & REM Overwrite stdout to file
command >> file.txt         & REM Append stdout to file
command 2> errors.log       & REM Redirect stderr
command > all.log 2>&1      & REM Merge stderr into stdout
command < input.txt         & REM Read stdin from file
command > NUL 2>&1          & REM Discard all output

Writing Production-Quality Batch Files

Standard Script Structure

@echo off
setlocal EnableDelayedExpansion

REM ============================================================
REM  Script: example.bat
REM  Purpose: Describe what this script does
REM ============================================================

call :main %*
exit /b %ERRORLEVEL%

:main
    call :parse_args %*
    if not defined _TARGET (
        echo ERROR: --target is required. 1>&2
        call :usage
        exit /b 1
    )
    echo Processing: %_TARGET%
    exit /b 0

:parse_args
    if "%~1"=="" exit /b 0
    if /i "%~1"=="--target" set "_TARGET=%~2" & shift
    if /i "%~1"=="--help"   call :usage & exit /b 0
    shift
    goto :parse_args

:usage
    echo Usage: %~nx0 --target ^<path^> [--help]
    echo.
    echo Options:
    echo   --target   Path to process (required)
    echo   --help     Show this help message
    exit /b 0

Best Practices

1. Always start with @echo off and setlocal — Prevents noisy output and variable leakage to the caller.
2. Validate inputs before processing — Check required arguments and file existence early. Use if not defined and if not exist.
3. Quote paths and variables — Use "%~1" and "%_MY_PATH%" to handle spaces and special characters safely.
4. Use exit /b instead of exit — Avoids closing the parent console window.
5. Return meaningful exit codes — exit /b 0 for success, non-zero for specific failures.
6. Use %~dp0 for script-relative paths — Ensures the script works regardless of the caller's working directory.
7. Prefer ROBOCOPY over XCOPY — More reliable, supports retry, mirroring, and logging.
8. Use EnableDelayedExpansion when modifying variables inside loops or parenthesized blocks.
9. Write errors to stderr — echo ERROR: message 1>&2 keeps stdout clean for piping.
10. Use REM for comments — :: can cause issues inside FOR loop bodies.

Security Considerations

• Never store credentials in batch files — Use environment variables, credential stores, or prompts.
• Validate user input — Unquoted variables containing &, |, or > can inject commands. Always quote: "%_USER_INPUT%".
• Use SETLOCAL — Prevents variable values from leaking to parent processes.
• Sanitize file paths — Validate paths before passing to DEL, RD, or ROBOCOPY to prevent unintended deletion.
• Avoid SET /P for sensitive input — Input is visible and stored in console history. Use a dedicated credential tool when possible.

Debugging and Troubleshooting

| Technique | How |

|-----------|-----|

| Trace execution | Remove @echo off or use @echo on temporarily |

| Step through | Add PAUSE between sections |

| Check error level | echo Exit code: %ERRORLEVEL% after each command |

| Inspect variables | set _MY_ to list all variables starting with _MY_ |

| Delayed expansion issues | Variable inside ( ) block not updating? Enable !VAR! syntax |

| FOR loop %% vs % | Use %%i in batch files, %i on the command line |

| Spaces in SET | set name=value not set name = value |

| Caret in pipes | After a pipe, use ^^^ to escape special chars |

| Parentheses in SET /A | Escape with ^( and ^) inside if blocks, or use quotes |

| Double percent for modulo | set /a r=14 %% 3 in batch files |

Cross-Platform and Extended Tools

When batch scripting reaches its limits, these tools extend cmd.exe capabilities:

| Tool | Purpose |

|------|---------|

| Cygwin | Full POSIX environment on Windows (grep, sed, awk, ssh) |

| MSYS2 | Lightweight Unix tools and package manager (pacman) |

| WSL | Windows Subsystem for Linux — run native Linux binaries |

| GnuWin32 | Individual GNU utilities as native Windows executables |

| PowerShell | Modern Windows scripting with .NET integration |

Use batch when you need: fast startup, simple file operations, PATH-based CLI tools, or Task Scheduler integration. Consider PowerShell or WSL for complex data processing, REST APIs, or object-oriented scripting.

CMD Keyboard Shortcuts

| Shortcut | Action |

|----------|--------|

| Tab | Auto-complete file/folder names |

| Up / Down | Navigate command history |

| F7 | Show command history popup |

| F3 | Repeat last command |

| Esc | Clear current line |

| Ctrl+C | Cancel running command |

| Alt+F7 | Clear command history |

Reference Files

The references/ folder contains detailed documentation:

| File | Contents |

|------|----------|

| tools-and-resources.md | Windows tools, utilities, package managers, terminals |

| batch-files-and-functions.md | Example scripts, techniques, best practices links |

| windows-commands.md | Comprehensive A-Z Windows command reference |

| cygwin.md | Cygwin user guide and FAQ |

| msys2.md | MSYS2 installation, packages, and environments |

| windows-subsystem-on-linux.md | WSL setup, commands, and documentation |

Asset Templates

The assets/ folder contains starter batch file template data, but as text files:

| Template | Purpose |

|----------|---------|

| executable.txt | Standalone CLI tool with argument parsing |

| library.txt | Reusable function library with CALL-able labels |

| task.txt | Scheduled task / automation script |