/batch-files

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 Repl