---

name: batch-files description: 'Expert-level Windows batch file (.bat/.cmd) skill for writing, debugging, and maintaining CMD scripts. Use when asked to "create a batch file", "write a .bat script", "automate a Windows task", "CMD scripting", "batch automation", "scheduled task script", "Windows shell script", or when working with .bat/.cmd files in the workspace. Covers cmd.exe syntax, environment variables, control flow, string processing, error handling, and integration with system tools.'

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