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

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

Delayed Expansion

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

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

Control Flow

Conditional Execution

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

Compound Commands

FOR Loops

GOTO and Labels

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

Command-Line Arguments

Argument Parsing Pattern

String Processing

Substrings

Search and Replace

Substring Containment Test

Functions

Functions use labels, CALL, and SETLOCAL/ENDLOCAL:

• 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:

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

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

Error Handling

Error Level Conventions

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

Fail-Fast Pattern

Setting Exit Codes

Essential Commands Reference

File Operations

Text Search and Processing

System Information

Network

Scheduling and Automation

Shell Utilities

Shell Syntax and Expressions

Parentheses for Grouping

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

Escape Characters

The caret ^ escapes the next character:

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)

Redirection Summary

Writing Production-Quality Batch Files

Standard Script Structure

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

Cross-Platform and Extended Tools

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

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

Reference Files

The references/ folder contains detailed documentation:

Asset Templates

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