Core Concepts

Commands

Patchloom has 20 commands:

• search / replace -- text-level find and replace across files
• patch -- apply unified diffs
• md -- markdown-aware editing (sections, bullets, tables, headings)
• doc -- parser-backed JSON, YAML, and TOML mutations
• tidy -- whitespace and line-ending normalization
• create / delete / rename -- file lifecycle
• read -- file content inspection with optional line range (supports multiple files)
• status -- uncommitted change summary from git
• tx -- atomic multi-operation transactions
• batch -- line-oriented multi-operation format (delegates to tx engine)
• completions -- shell completion generation
• agent-rules -- print end-user agent documentation for patchloom
• schema -- export operation schemas with tier filtering and system prompts
• explain -- summarize a tx plan in plain English before applying
• undo -- restore files from a backup created by --apply
• init -- set up patchloom in a project (agent rules, completions, MCP)
• mcp-server -- MCP protocol server exposing patchloom tools for AI agents

For feature-by-feature Use when guidance on commands, operations, and notable modes, see the reference guide.

Write modes

Every write command supports four modes:

These modes are mutually exclusive. Patchloom is safe by default: nothing is written unless you pass --apply or confirm an interactive prompt.

Write policy

A write policy controls transformations applied to all content before it reaches disk:

• --ensure-final-newline -- non-empty files always end with \n
• --normalize-eol <lf|crlf> -- standardize line endings
• --trim-trailing-whitespace -- remove trailing spaces on every line
• --respect-editorconfig -- read policy from .editorconfig if present

Standalone write commands use these flags directly. In tx, the same flags act as defaults for all writes, and plan-level write_policy entries override conflicting CLI flags for self-contained plans.

In tx plans, set these at the plan level:

{
  "version": "1",
  "write_policy": { "ensure_final_newline": true },
  "operations": [...]
}

Project configuration

Create a .patchloom.toml in your project root to set per-project defaults. CLI flags override config values.

[write_policy]
ensure_final_newline = true
normalize_eol = "lf"
trim_trailing_whitespace = true

[exclude]
globs = ["target/**", "node_modules/**"]

[output]
color = "auto"

The config file is searched from the working directory upward, so it works in subdirectories too.

Undo safety net

Before any --apply write, patchloom saves the original content of each affected file to .patchloom/backups/. If something goes wrong:

patchloom undo --list          # see available backups
patchloom undo                 # dry-run: show what would change
patchloom undo --apply         # actually restore files

Backups older than 7 days are auto-pruned.

Color output

Patchloom colorizes diffs and search results when stdout is a terminal. Override with:

• --color=always -- force color (useful when piping to a pager like less -R)
• --color=never -- disable color
• NO_COLOR=1 -- environment variable that disables color for all tools (no-color.org)

Machine-readable modes (--json, --jsonl, --quiet) never produce color.

Transaction plans

The tx command runs multiple operations atomically. If any operation fails, all changes are rolled back and no files are written.

Plans are JSON objects with three lifecycle arrays:

1. operations -- the mutations (replace, doc.set, md.replace_section, etc.)
2. format -- shell commands that run after writes (e.g., cargo fmt)
3. validate -- shell commands that verify correctness (e.g., make check)

With "strict": true, a format or validation failure reverts all writes (exit 7). Without strict mode, writes stay on disk (exit 6).

Exit codes

Every command returns a specific exit code:

These codes let CI pipelines and agent frameworks branch on outcomes without parsing output.

Glob filtering

Most commands accept --glob <pattern> (repeatable) to restrict which files are processed:

patchloom replace "old" --to "new" --glob "*.rs" --glob "*.toml" --apply

Glob patterns match either the basename or the path relative to the input root. For example, if you search src/, then --glob 'sub/*.txt' matches src/sub/file.txt.

In tx plans, individual operations can use "glob" instead of "path" to target multiple files.

Security model

Patchloom runs with the privileges of the invoking user and treats all inputs (command-line arguments, plan files, stdin) as trusted. This is the same trust model as make, sh, or cargo.

What this means in practice:

• Plans can execute arbitrary shell commands. The format and validate lifecycle steps pass their cmd field to sh -c (or cmd /C on Windows) with the user's full privileges. Only load plans you trust.
• File operations are unrestricted. create, delete, read, replace, patch, and all tx operations accept any path the invoking user can access. There is no sandbox, chroot, or path restriction.
• Plan cwd overrides the working directory. A plan's cwd field changes the working directory for all subsequent operations and lifecycle steps. Relative values resolve from the invocation root, not from the plan file location. In normal CLI use this still runs with the invoking user's filesystem access; in MCP mode the resolved directory must stay under the server root.

For AI agent authors: Do not construct plans from untrusted conversational input without validation. A plan is equivalent to a shell script. Treat plan files with the same care you would treat a Makefile or a bash script from an unknown source.