patchling-apply Command-Line Tool
Patchling everywhere: this library also ships for browser and Node as patchling — see it running live in nanoodle.com, a no-server visual AI workflow editor built on it.
patchling-apply is a companion tool to Patchling that applies unified diffs directly to your project using Patchling’s patch logic.
Overview
patchling-apply accepts diffs either directly via a command-line argument or from a file. It first attempts to apply the diff using standard patch logic. If that fails, it falls back to a smart apply mechanism that leverages AI-powered conflict resolution.
Usage
Apply Diff from Command Line
patchling-apply --diff "<diff text>"
Apply Diff from a File
patchling-apply path/to/diff.patch
Options
- --project-dir: Specify the target directory for applying the diff (default: current directory)
- --model: (Optional) Starting in 0.9.5, selects the model used to apply the diff. This overrides
GPTDIFF_SMARTAPPLY_MODEL. The default isopenai/gpt-4.1-mini. - --max_tokens: (Optional) Maximum tokens to use for LLM responses
- --nobeep: Disable the completion beep notification
- --dumb: Attempt to apply the diff using standard patch logic (like git apply) before falling back to smart apply
Workflow
By default, patchling-apply uses an AI-powered smart apply mechanism to apply the diff directly. If the --dumb flag is specified, it first attempts to apply the diff using standard patch logic (similar to git apply). If that fails, it falls back to the smart apply mechanism with AI-powered conflict resolution.
Exit status and recovery
Starting in 0.9.5, the command exits with status 0 when every file succeeds. Deleting a file
that is already absent is a successful no-op. An empty or invalid diff, an
unsafe path, a model refusal or empty response, and a filesystem failure
produce status 1.
Files are applied independently. If one file fails, successful writes or
deletions to other files may remain; they are not rolled back. The failure
summary lists each failed file and its reason. Inspect the project before
retrying, and make automation check the exit status before continuing.
The same failure status applies to patchling "…" --apply and the legacy
gptdiff / gptpatch command aliases. The in-memory library smartapply
retains its existing return and exception behavior.
Agent Loop Integration
patchling-apply is what makes Patchling agent loops production-ready. When running continuous improvement loops:
while true; do
patchling "improve code quality" --apply || exit 1
done
The --apply flag uses patchling-apply internally. Each iteration may encounter:
- Code drift - Files changed since the diff was generated
- Merge conflicts - Overlapping changes from previous iterations
- Partial matches - Context lines that shifted
Successful iterations can continue automatically. A nonzero exit status requires the loop to stop or explicitly handle the reported failure before continuing.
For production-ready loop patterns and real metrics (18→127 tests, 8 SQL injections→0), see the Agent Loops Guide.
For further details about Patchling and its companion tools, please refer to the Patchling Documentation.