Patchloom Reference

This is the reference for Patchloom's meaningful commands, actions, operations, and notable command modes.

  • Start with Quickstart if you want a first success.
  • Read Core Concepts for shared semantics like write modes, exit codes, and transaction behavior.
  • Use this file when you need to choose the right feature or mode for a job, or when a pull request adds meaningful CLI surface and the docs coverage test expects it here.

Global behaviors

Patchloom has a small set of global features that shape how other commands behave.

Write modes

Patchloom write commands default to preview mode. The canonical semantics live in Core Concepts. The sections below focus on when to choose each mode.

--diff

  • What it does: Prints the unified diff for a write command without mutating files.
  • Use when: You want a human review step before applying a change, or you want to inspect the exact patch Patchloom would write.
  • Prefer instead: Use --check for CI pass or fail behavior, or --apply to actually write files.

--apply

  • What it does: Writes the requested change to disk.
  • Use when: You have already previewed the change, or you trust the command and want the mutation to happen now.
  • Prefer instead: Use --diff when reviewing, or --check when you only need a clean or dirty signal.

--check

  • What it does: Calculates whether a write command would change files and returns exit code 2 when changes are pending.
  • Use when: You are wiring Patchloom into CI, pre-commit validation, or agent workflows that should fail on drift.
  • Prefer instead: Use --diff when you need the actual patch text, or --apply when you want the mutation.

--confirm

  • What it does: Shows the diff preview, then prompts Apply? [Y/n] on stderr. If confirmed, applies the change; if declined, exits without writing.
  • Use when: You want a single-command preview-then-apply workflow instead of running the command twice.
  • Prefer instead: Use --apply when scripting (no interactive prompt), or --diff when you only want the preview.

--diff, --apply, --check, and --confirm are mutually exclusive. Passing more than one is rejected with an error. When none is specified, --diff is the default. When --confirm is used and stdin is not a TTY, the command shows the diff without prompting (same as --diff).

Write policy flags

These flags shape how written content is normalized before it reaches disk.

--ensure-final-newline

  • What it does: Ensures non-empty written files end with \n.
  • Use when: You want simple newline hygiene on every touched file without running a separate cleanup command.
  • Prefer instead: Use tidy fix when the goal is repo cleanup, not just normalization of files already being edited.

--normalize-eol

  • What it does: Normalizes written line endings to keep, lf, or crlf.
  • Use when: A repo or downstream tool expects a specific line ending convention.
  • Prefer instead: Use --respect-editorconfig when the repo already declares the desired convention there.

--trim-trailing-whitespace

  • What it does: Removes trailing spaces and tabs from touched lines before writing.
  • Use when: You want text cleanup to happen automatically as part of another write command.
  • Prefer instead: Use tidy fix when the goal is to sweep existing files for whitespace problems.

--respect-editorconfig

  • What it does: Reads .editorconfig when present and applies matching write policy.
  • Use when: The repo already encodes formatting policy in .editorconfig and Patchloom should follow it automatically.
  • Prefer instead: Use explicit write flags, or tx write_policy, when the command should be self-contained and not depend on repo metadata.

Output and scope flags

These flags affect how Patchloom reports results or chooses which files to touch.

--json

  • What it does: Emits one machine readable JSON document for the command result.
  • Use when: Another tool, script, or agent needs structured output instead of human oriented text.
  • Prefer instead: Use --jsonl when you want one JSON object per result line for streaming style consumers.

--jsonl

  • What it does: Emits one compact JSON value per result line instead of one aggregate document.
  • Use when: A command naturally yields multiple result records, or you want compact machine-readable output from single-result commands like create, delete, rename, status, tx, explain, or undo.
  • Prefer instead: Use --json when you want one aggregate document for the whole command.

--quiet

  • What it does: Suppresses non-JSON human readable output.
  • Use when: Only the exit code or the file mutation matters and extra stdout noise would get in the way.
  • Prefer instead: Use --json when another tool still needs structured output.

--cwd

  • What it does: Sets the working directory used to resolve relative paths.
  • Use when: You are invoking Patchloom from outside the target repo, or you want scripts to behave predictably regardless of the caller's current directory.
  • Prefer instead: Use a plan level cwd in tx when the directory choice should travel with the plan itself, but keep it inside the invocation root. Relative plan cwd values resolve from the caller's working directory (--cwd or the process cwd), not from the plan file location.

--glob

  • What it does: Restricts candidate files by one or more glob patterns. Patterns match either the basename or the path relative to the input root, so sub/*.txt matches files under a searched sub/ directory.
  • Use when: A command should only see a narrow file type or subtree, even if the input path is broader.
  • Prefer instead: Use --files-from when another tool has already determined the exact file list.

--files-from

  • What it does: Reads the target file list from a file, or from stdin when passed -.
  • Use when: Another tool already selected the exact paths and Patchloom should operate only on that set.
  • Prefer instead: Use --glob for pattern based scoping, or direct path arguments when the target set is already small and obvious.

--color

  • What it does: Controls when ANSI color codes appear in output. auto (default) enables color when stdout is a terminal and the NO_COLOR environment variable is not set. always forces color even when piped. never disables color unconditionally.
  • Use when: You need to override the default terminal detection, for example forcing color into a pager or disabling it in a terminal that renders escape codes literally.
  • Prefer instead: Set the NO_COLOR environment variable when you want a global, tool-agnostic way to disable color across all CLI tools.

--verbose

  • What it does: Prints diagnostic messages to stderr prefixed with [patchloom]. Shows which operations are running, search parameters, selector evaluation steps, and MCP tool call timing. Can also be enabled by setting the PATCHLOOM_LOG environment variable to any value.
  • Use when: A command produces unexpected results and you need to see what Patchloom is doing internally without reading source code.
  • Prefer instead: Use --json when you need machine-readable output for downstream tools.

Exit codes

Use Core Concepts as the canonical exit code table. When integrating Patchloom into CI or agent workflows, branch on exit codes instead of parsing human readable output.

Commands

These are the main entry points. If you are deciding between commands, start here.

  • What it does: Searches text files with literal or regex matching, optional context, counts, and file only results. Binary and invalid UTF-8 files are skipped.
  • Use when: You need to locate candidate edits, audit repo state, or narrow inputs before changing files. For AI agents, native search/grep tools are typically faster for simple pattern matching.
  • Prefer instead: Use replace for actual text mutation, or doc, md, or patch when you already know the structured change you want.
  • Related: --glob, --files-from, replace

replace

  • What it does: Performs mechanical string replacement across one or many text files, with literal or regex matching. Binary and invalid UTF-8 files are skipped.
  • Use when: You are doing a rename, version bump, boilerplate rewrite, or another string level change where plain text semantics are enough. For AI agents doing single-file replacements, native search_replace tools are typically faster; use patchloom replace inside tx plans when batching multiple file edits.
  • Prefer instead: Use doc for structured data, md for heading aware markdown, or patch when you already have a unified diff.
  • Related: search, tx

patch

  • What it does: Checks or applies a unified diff.
  • Use when: The change already exists as a patch, or you want stale context detection instead of search and replace semantics.
  • Prefer instead: Use replace, doc, or md when you want to describe the mutation directly instead of carrying a diff artifact.
  • Related: patch check, patch apply, tx patch.apply

md

  • What it does: Performs heading aware markdown edits for sections, bullets, tables, and AGENTS linting.
  • Use when: Documentation needs semantic markdown edits that should not depend on raw byte offsets.
  • Prefer instead: Use replace for simple line level edits, or patch for exact diff application.
  • Related: md actions, tx markdown operations

doc

  • What it does: Performs parser backed JSON, YAML, and TOML queries and mutations.
  • Use when: Config or metadata changes should operate on keys and arrays instead of brittle text matching.
  • Prefer instead: Use replace for plain text, md for markdown, or patch for existing diffs.
  • Related: doc actions, tx document operations

tidy

  • What it does: Checks or fixes trailing whitespace, line endings, and final newlines in text files. Binary and invalid UTF-8 files are skipped.
  • Use when: You need repo text normalization, or a CI guard for basic text tidiness.
  • Prefer instead: Use write policy flags when the cleanup should only apply to files already being touched by another command.
  • Related: tidy check, tidy fix, tx tidy.fix

create

  • What it does: Creates a file from literal content or stdin. Exactly one of --content or --stdin is required. Passing both is rejected with --content and --stdin cannot be combined, and passing neither is rejected with either --content or --stdin must be provided. Directory targets are rejected in all modes. When combined with --confirm and --json or --jsonl, the structured output includes applied: true|false so callers can tell whether the prompt was accepted.
  • Use when: Generating a new tracked file is the whole task, or one step in a larger transaction. For AI agents creating a single file, native file creation tools are typically faster; use file.create inside tx plans when bundling with other edits.
  • Prefer instead: Use doc, md, or replace when the file already exists and only needs edits.
  • Related: delete, tx file.create

delete

  • What it does: Removes a file. Directory targets are rejected in all modes. When combined with --confirm and --json or --jsonl, the structured output includes applied: true|false so callers can tell whether the prompt was accepted.
  • Use when: A file should disappear outright and no other atomic edits are needed. For AI agents deleting a single file, native delete tools are typically faster; use file.delete inside tx plans when bundling with other edits.
  • Prefer instead: Use tx file.delete when the removal must be bundled atomically with other changes.
  • Related: create, tx file.delete

rename

  • What it does: Moves (renames) a file from one path to another. Source and destination must both be file paths, not directories. When combined with --confirm and --json or --jsonl, the structured output includes applied: true|false so callers can tell whether the prompt was accepted.
  • Use when: A file needs to be relocated and no other atomic edits are needed. Use file.rename inside tx plans when bundling with other edits.
  • Prefer instead: Use tx file.rename when the rename must be bundled atomically with other changes.
  • Related: create, delete, tx file.rename

tx

  • What it does: Runs multiple operations atomically, then optional format and validate steps.
  • Use when: Editing 3 or more files in one task. Batches N operations into 1 tool call, eliminating agent round-trips. Also provides atomicity, rollback, and format/validate lifecycle. For AI agents, this is the primary speed advantage: one call instead of N.
  • Prefer instead: Use standalone commands when one direct operation is enough.
  • Related: examples, tx fields, tx operations

batch

  • What it does: Executes multiple operations from a simple line-oriented format. Each line is one operation with positional arguments (e.g., doc.set config.json version "2.0.0"). Internally builds a tx plan and delegates to the tx engine.
  • Use when: Editing multiple files and the JSON tx plan format is too verbose. The line format covers 21 operations (doc.set, doc.delete, doc.merge, doc.ensure, doc.append, doc.prepend, doc.update, doc.move, doc.delete_where, replace, file.create, file.delete, file.rename, md.upsert_bullet, md.table_append, md.replace_section, md.insert_after_heading, md.insert_before_heading, md.dedupe_headings, md.lint_agents, tidy.fix) with minimal syntax. For AI agents, this is faster to generate than a full JSON plan.
  • Prefer instead: Use tx when you need format/validate lifecycle steps, strict mode, or operations not supported by the line format (patch.apply, replace with regex/nth, search, read).
  • Related: tx

read

  • What it does: Prints the contents of one or more files, optionally restricted to a line range. Multiple files get ==> path <== separators in text mode, a JSON array in --json mode, and one object per line in --jsonl mode. If at least one requested file is read successfully, the command still exits successfully and reports errors only for the missing files.
  • Use when: An agent needs to inspect one or several files before deciding on an edit. For AI agents, native read_file tools are typically faster for single-file reads.
  • Prefer instead: Use search when you need pattern matching, or doc get when the file is structured and you want a single value.
  • Related: search, doc get

status

  • What it does: Shows which files have uncommitted changes compared to git HEAD. This command is git-backed, so it must run inside a git repository.
  • Use when: An agent needs a quick summary of the working tree before committing, staging, or choosing which files to process. For AI agents, native git status or terminal commands are typically equivalent.
  • Prefer instead: Use git status directly when you need full git porcelain output or staging details.
  • Related: search, read

undo

  • What it does: Restores files from a backup created by a previous --apply operation. Before any --apply write, patchloom saves the original content of affected files to .patchloom/backups/<timestamp>/. In dry-run mode, undo reports what would be restored and exits with code 2 (CHANGES_DETECTED). --json or --jsonl emit that preview as structured output.
  • Use when: An --apply operation produced an undesirable result and you want to revert. Especially useful when the working tree was not committed before applying changes.
  • Notable flags:
    • --list shows available backup sessions. --json emits the full session list as one array, while --jsonl emits one session object per line.
    • --session <timestamp> targets a specific session (defaults to most recent).
    • --apply actually restores files (dry-run by default, showing what would change).
  • Prefer instead: Use git checkout or git stash when working in a committed git repo.
  • Related: tx, replace, tidy

explain

  • What it does: Parses a tx plan (JSON, YAML, or TOML) and prints a numbered, human-readable summary of each operation. Supports --json and --jsonl for structured output, plus --stdin for piped input. If both a path and --stdin are provided, stdin takes precedence and the path is ignored.
  • Use when: A user or agent wants to review what a tx plan will do before running tx --apply. Converts machine-readable plan format into plain English descriptions.
  • Prefer instead: Use tx directly (without --apply) to see the actual diff preview. Use explain when you want a quick overview without touching any files.
  • Related: tx, batch

schema

  • What it does: Exports the complete registry of patchloom operations with JSON Schemas, tier-filtered subsets, and LLM-ready system prompt fragments. Each operation is annotated with a minimum capability tier (weak, medium, strong).
  • Use when: You are building an AI agent that uses patchloom programmatically and need machine-readable operation schemas, or you want to generate a system prompt tailored to a specific model tier.
  • Notable flags:
    • --format json|prompt (default: json): json outputs operation schemas as JSON, prompt outputs markdown suitable for LLM system prompts.
    • --tier weak|medium|strong: Filter operations by minimum capability tier.
    • --examples: Include usage examples in JSON output (omitted by default).
  • Prefer instead: Nothing; this is the only programmatic way to discover available operations and their schemas.
  • Related: agent-rules, mcp-server

agent-rules

  • What it does: Prints an end-user AGENTS.md that teaches AI agents how to use patchloom. Includes command reference, exit codes, write modes, transaction plan format, and usage examples.
  • Use when: You are setting up a project where agents should use patchloom for file operations and need an AGENTS.md or SKILL.md that describes patchloom's interface.
  • Notable flags:
    • --mode cli|mcp|all (default: all): cli omits MCP section, mcp omits CLI shell examples, all includes everything.
    • --platform linux|windows|all (default: all): linux uses heredocs and single-quote syntax, windows uses file arguments and double-quote escaping, all shows both.
  • Prefer instead: Nothing; this is the only way to generate the end-user agent documentation.
  • Related: completions, mcp-server

init

  • What it does: Sets up patchloom in the current project: creates AGENTS.md if needed, otherwise appends the rules to an existing agent instructions file, prints shell completion instructions, and detects MCP configuration opportunities. When .vscode/ or .cursor/ already exists, it prints ready-to-copy .vscode/mcp.json or .cursor/mcp.json snippets.
  • Use when: You just installed patchloom and want a single command to configure a project instead of running agent-rules, completions, and MCP setup separately.
  • Notable flags:
    • -y, --yes: Skip confirmation prompts and auto-accept all actions.
  • Prefer instead: agent-rules if you only need the rules text, or completions if you only need shell completions.
  • Related: agent-rules, completions, mcp-server

mcp-server

  • What it does: Starts an MCP (Model Context Protocol) server on stdio, exposing patchloom operations as structured tool calls. Included by default in all builds.
  • Use when: An MCP-capable AI agent can call patchloom tools directly via structured tool calls instead of constructing shell commands. This eliminates the shell-syntax construction tax and reduces agent errors.
  • --allow-shell: By default, the MCP server rejects tx plans that contain format or validate lifecycle steps (which execute shell commands). Pass --allow-shell to permit these steps. This flag has no effect on the CLI tx command, which always allows lifecycle steps.
  • Prefer instead: Use the CLI directly when the agent does not support MCP, or when patchloom is invoked from scripts and CI.
  • Related: batch, tx

completions

  • What it does: Generates shell completion scripts for bash, zsh, fish, or elvish.
  • Use when: You are installing Patchloom into an interactive shell and want faster command discovery.
  • Prefer instead: Nothing, if Patchloom is only used from scripts or ephemeral CI runners.
  • Related: installation guide

Command modes

These are meaningful command-specific modes that change how a top-level command behaves, even though they are not separate subcommands.

search --files-with-matches

  • What it does: Emits only file paths that contain at least one match.
  • Use when: You need a path list to feed into another tool or command instead of the matching lines themselves.
  • Prefer instead: Use search --count when per-file match totals matter, or plain search when the matching lines matter.

search --count

  • What it does: Emits match counts per file instead of full matching lines.
  • Use when: You are auditing prevalence, comparing files, or gating on how many matches remain.
  • Prefer instead: Use plain search when you need the matching text, or search --files-with-matches when only file membership matters.

search --invert-match

  • What it does: Shows lines that do not match the pattern.
  • Use when: You are looking for non-conforming lines or excluding content that matches a known pattern.
  • Prefer instead: Use plain search when you want the matching lines themselves.

search --multiline

  • What it does: Lets regex matches span multiple lines by making . match newlines.
  • Use when: The pattern you care about is inherently block-shaped, such as a function body or multi-line stanza.
  • Prefer instead: Use plain search for line-oriented patterns because it is simpler and easier to reason about.

search --before-context

  • What it does: Shows N lines before each match but none after (unless combined with -A).
  • Use when: You need to see what precedes a match (function signature before a body, imports before usage) without cluttering output with lines after.
  • Prefer instead: Use --context (-C) when symmetric context is fine, or combine -B and -A for independent before/after counts.

search --after-context

  • What it does: Shows N lines after each match but none before (unless combined with -B).
  • Use when: You need to see what follows a match (function body after signature, error handling after a call) without lines before.
  • Prefer instead: Use --context (-C) when symmetric context is fine, or combine -B and -A for independent before/after counts.

search --case-insensitive

  • What it does: Matches regardless of case.
  • Use when: The target text may appear in inconsistent capitalization across files.
  • Prefer instead: Use case-sensitive search when exact spelling matters and false positives would be noisy.

search --assert-count

  • What it does: Succeeds (exit 0) only if the total match count equals the given number. Exits 2 otherwise.
  • Use when: An agent or CI pipeline needs to verify an invariant (e.g. "exactly 18 markers exist") in one call instead of searching and then comparing the count manually.
  • Prefer instead: Use plain search --count when you want to see counts without a pass/fail assertion.

replace --regex

  • What it does: Treats the pattern as a regex instead of a literal string.
  • Use when: The change is pattern-based, or capture groups should shape the replacement.
  • Prefer instead: Use literal replace for fixed text because it is simpler and less error-prone.

replace --if-exists

  • What it does: Returns success even when no matches are found.
  • Use when: The replacement is intentionally idempotent and should not fail if the repo is already in the desired state.
  • Prefer instead: Use default replace behavior when a missing match should be treated as drift or an error.

replace --nth

  • What it does: Replaces only the Nth occurrence of the target.
  • Use when: Replacing every occurrence would be too broad and the exact positional match matters.
  • Prefer instead: Use plain replace when every occurrence should change, or regex when the target can be narrowed semantically.

replace --insert-before

  • What it does: Inserts text before each match instead of replacing it. The matched text is preserved.
  • Use when: You need to add a line or annotation above an existing anchor without repeating the anchor in the replacement text.
  • Prefer instead: Use --to when the matched text should actually change, not just receive a prefix.

replace --insert-after

  • What it does: Inserts text after each match instead of replacing it. The matched text is preserved.
  • Use when: You need to append content after an existing anchor, such as adding a comment or tag after a specific line.
  • Prefer instead: Use --to when the matched text should actually change, not just receive a suffix.

replace --multiline

  • What it does: Lets regex replacement span multiple lines by making . match newlines.
  • Use when: The target pattern is a multi-line block rather than a single line.
  • Prefer instead: Use line-oriented replace when the match should stay local and easy to inspect.

replace --case-insensitive

  • What it does: Matches regardless of case during replacement.
  • Use when: The target text appears with inconsistent capitalization and should still be updated uniformly.
  • Prefer instead: Use case-sensitive replace when exact spelling is part of the safety boundary.

create --stdin

  • What it does: Reads the new file content from stdin instead of --content.
  • Use when: Another tool is generating the content, or shell composition is cleaner than embedding the full text in one argument.
  • Prefer instead: Use create --content for short inline content that should stay visible in the command itself.

create --force

  • What it does: Overwrites an existing file instead of failing.
  • Use when: File recreation is intentional and should replace previous contents deterministically.
  • Prefer instead: Use default create behavior when accidental overwrite would be dangerous.

patch FILE

  • What it does: Reads the unified diff from a file path (positional argument).
  • Use when: The patch already exists as a saved artifact that should be reviewed, reused, or passed around directly.
  • Prefer instead: Use patch --stdin when another tool is piping the patch text dynamically.

patch --stdin

  • What it does: Reads the unified diff from stdin instead of a file argument.
  • Use when: Another tool is generating or piping the patch text directly.
  • Prefer instead: Use patch FILE when the diff should be stored as a tangible artifact.

doc --predicate

  • What it does: Supplies the key-value predicate used by doc delete-where.
  • Use when: Array cleanup should target matching objects instead of deleting by fixed index or selector path alone.
  • Prefer instead: Use doc delete when one direct selector can remove the target without predicate filtering.

doc --stdin

  • What it does: Reads merge payload content from stdin for doc merge.
  • Use when: The object being merged is generated by another tool or is awkward to express inline.
  • Prefer instead: Use doc merge --value for short, self-contained object literals.

md --stdin

  • What it does: Reads replacement or inserted markdown content from stdin for the section-editing commands.
  • Use when: The markdown payload is generated, large, or easier to stream than to quote inline.
  • Prefer instead: Use --content when the inserted text is small and should stay visible in the command.

tx -

  • What it does: Reads the transaction plan from stdin instead of a plan file. Defaults to JSON; use --plan-format for YAML or TOML.
  • Use when: The plan is generated on the fly or piped from another tool.
  • Prefer instead: Use tx FILE when the plan should be stored, reviewed, or reused.

tx --plan-format yaml

  • What it does: Tells tx to parse the plan as YAML (or TOML) instead of JSON. Auto-detected from file extension for plan files; required when piping YAML from stdin.
  • Use when: The plan is easier to write or generate in YAML/TOML, or when JSON verbosity is friction for inline agent-generated plans.
  • Prefer instead: Use JSON plans when interoperability or strict schema validation matters more than writability.

doc actions

Use these when the top level doc command is right, but you need a specific structured operation.

Comment preservation: All doc write operations preserve inline comments, section comments, and formatting in YAML and TOML files. The parser edits the concrete syntax tree (CST) directly, so only the changed values are rewritten while surrounding comments and whitespace stay intact. This includes operations that change array length (append, prepend, delete-where), which use text-level splicing to preserve comments on the affected file.

doc get

  • What it does: Reads the value at a selector path from a JSON, YAML, or TOML file.
  • Use when: You need one precise value without mutating the document.
  • Prefer instead: Use doc flatten when you are exploring an unfamiliar file and need a broader map of its contents.

doc has

  • What it does: Checks whether a selector path exists.
  • Use when: A script or workflow needs a presence check before choosing a later action.
  • Prefer instead: Use doc ensure when the real goal is to create the value if it is missing.

doc keys

  • What it does: Lists the keys of an object at a selector path.
  • Use when: You want to inspect the shape of a structured object before choosing an edit.
  • Prefer instead: Use doc get when you already know the exact selector you want.

doc len

  • What it does: Counts items in an array or object.
  • Use when: You need a quick cardinality check in scripts, CI, or exploratory work.
  • Prefer instead: Use doc select or doc get when the actual values matter more than the count.

doc set

  • What it does: Sets or creates a value at a selector path.
  • Use when: One exact selector path should be updated deterministically.
  • Prefer instead: Use doc merge for multi field updates, or doc ensure when existing values should be preserved.

doc delete

  • What it does: Removes the value at a selector path.
  • Use when: A selector path or node is obsolete and should disappear cleanly.
  • Prefer instead: Use doc delete-where when the target is a subset of array items instead of one direct selector.

doc delete-where

  • What it does: Deletes array items that match a predicate.
  • Use when: You need to remove selected objects from a list without rebuilding the whole array by hand.
  • Prefer instead: Use doc delete when one direct selector can remove the target.

doc merge

  • What it does: Deep merges an object payload into an existing document.
  • Use when: Several related fields should be added or updated together.
  • Prefer instead: Use doc set when one exact path should change and merge semantics are unnecessary.

doc append

  • What it does: Appends a value to an array.
  • Use when: New items should appear at the end of the list.
  • Prefer instead: Use doc prepend when order or precedence means the new item should come first.

doc prepend

  • What it does: Inserts a value at the front of an array.
  • Use when: The new item should win by order, or defaults should be introduced at the front of the list.
  • Prefer instead: Use doc append when simple chronological growth is enough.

doc select

  • What it does: Reads only the values that match a selector or predicate.
  • Use when: You need a filtered read view of a larger structure.
  • Prefer instead: Use doc update or doc delete-where when the end goal is mutation rather than inspection.

doc update

  • What it does: Updates all matching nodes to the same value.
  • Use when: A broad but uniform change should apply across many selected elements.
  • Prefer instead: Use doc set when the change only targets one path.

doc move

  • What it does: Moves or renames a selector path.
  • Use when: Schema cleanup or path migration should preserve the value while changing the selector.
  • Prefer instead: Use doc set plus doc delete only when the move semantics are not a clean fit.

doc ensure

  • What it does: Creates a value only if it is currently missing.
  • Use when: You need idempotent config bootstrapping and must not overwrite existing values.
  • Prefer instead: Use doc set when the desired value should win even if the selector path already exists.

doc flatten

  • What it does: Lists leaf selector paths and their values.
  • Use when: You are discovering the shape of an unfamiliar structured file.
  • Prefer instead: Use doc get for one targeted read, or doc keys when only the object shape matters.

doc diff

  • What it does: Compares two structured files by their semantic content.
  • Use when: You care about structural value changes more than raw formatting differences.
  • Prefer instead: Use patch or ordinary diff tooling when the exact textual patch matters.

md actions

Use these when markdown structure matters more than raw text matching.

md replace-section

  • What it does: Replaces the body of a heading section.
  • Use when: A section should be treated as authoritative content that can be rewritten in one step.
  • Prefer instead: Use md insert-after-heading when existing section content should stay and you only need to add more text.

md insert-after-heading

  • What it does: Inserts content immediately after a heading.
  • Use when: You want to add a note, release entry, or status line while preserving the existing section body.
  • Prefer instead: Use md replace-section when the whole section should be regenerated.

md insert-before-heading

  • What it does: Inserts content immediately before a heading.
  • Use when: You want to add a preface or a new section boundary before an existing heading.
  • Prefer instead: Use md insert-after-heading when the addition belongs inside the section that starts at the heading.

md upsert-bullet

  • What it does: Ensures a bullet exists under a heading, without duplicating it.
  • Use when: Rules, checklists, or recurring notes should be added idempotently.
  • Prefer instead: Use md replace-section when the entire list should be rewritten.

md dedupe-headings

  • What it does: Removes duplicate headings.
  • Use when: Generated markdown or hand edited docs have accumulated repeated sections that should collapse to one.
  • Prefer instead: Use md lint-agents when the goal is diagnosis rather than mutation.

md lint-agents

  • What it does: Checks AGENTS style markdown for common problems.
  • Use when: You want a CI style guard for agent instruction files before they drift into invalid or confusing structure.
  • Prefer instead: Use md dedupe-headings when you already know the file should be auto corrected.

md table-append

  • What it does: Appends a row to the markdown table under a heading.
  • Use when: A docs table should grow without manually rebuilding its existing rows.
  • Prefer instead: Use md replace-section when the whole table should be regenerated from source data.

patch actions

Use these when the change already exists as a unified diff.

patch check

  • What it does: Verifies whether a patch applies cleanly, without writing files.
  • Use when: CI or review should fail early on stale patch context.
  • Prefer instead: Use patch apply when the patch should be written, or replace and doc when you do not actually need to carry a diff file.

patch apply

  • What it does: Applies a unified diff.
  • Use when: The desired change is already available as patch text and should be replayed directly.
  • Prefer instead: Use replace, md, or doc when you would rather describe the desired mutation at a higher level.

tidy actions

Use these when newline and whitespace correctness is the main concern.

tidy check

  • What it does: Reports missing final newlines, mixed line endings, and trailing whitespace in text files. Binary and invalid UTF-8 files are skipped.
  • Use when: You want a non mutating tidy audit for CI or local review.
  • Prefer instead: Use tidy fix when the goal is to normalize the files immediately.

tidy fix

  • What it does: Applies newline and whitespace normalization to text files. Binary and invalid UTF-8 files are skipped.
  • Use when: Existing files already need cleanup and the cleanup itself is the task.
  • Prefer instead: Use write policy flags when normalization should only apply to files already being touched by another write command.

tx reference

tx is the place where Patchloom's features compose. Use Core Concepts for the canonical explanation of rollback and exit codes, and examples for plan templates.

Plan fields

version

  • What it does: Declares the plan schema version. Patchloom rejects plans whose version does not match the version it supports.
  • Use when: Every plan must include this field. It ensures forward-compatibility safety so an old patchloom build does not silently misinterpret a plan written for a newer schema.
  • Required: Yes. Plans without a version field are rejected.

cwd

  • What it does: Sets the base directory used to resolve relative paths inside the plan.
  • Use when: You need plan operations and lifecycle steps to run from a specific subdirectory under the invocation root.
  • Important: Relative values resolve from the invocation working directory (--cwd or the process cwd), not from the plan file's directory. In MCP mode, the resolved directory must stay inside the server root. If the resolved path does not exist or is not a directory, the plan is rejected with PARSE_ERROR (exit 4).
  • Prefer instead: Use the CLI --cwd flag when the directory choice is a caller concern rather than part of the plan itself.

write_policy

  • What it does: Applies newline, EOL, and whitespace normalization across all pending writes in the plan.
  • Use when: Every write in the transaction should share the same normalization policy.
  • Fields: Supports ensure_final_newline (bool), normalize_eol (keep, lf, or crlf), and trim_trailing_whitespace (bool).
  • Precedence: Patchloom starts from the invocation's per-file write policy, including CLI flags and any --respect-editorconfig values, then overrides only the keys set here.
  • Prefer instead: Use CLI write flags when one invocation needs defaults, but the plan itself should stay generic.

strict

  • What it does: Rolls back file writes when a format or validation step fails.
  • Use when: Partial writes are unacceptable and post write failure should behave like a full transaction failure.
  • Prefer instead: Leave strict mode off when writes may stay on disk even if later validation reports a problem.

operations

  • What it does: Lists the ordered mutations that make up the transaction.
  • Use when: One logical change spans several steps or several mutation types.
  • Prefer instead: Use a standalone command when one direct operation is enough.

format

  • What it does: Runs shell commands after writes are staged to disk but before validation.
  • Use when: Generated or edited files should be normalized by tools like cargo fmt, prettier, or black as part of the same workflow.
  • Step fields: Each entry accepts cmd (required shell command) and timeout (seconds, default 60).
  • Failure behavior: Any non-zero exit or timeout fails the transaction. Error output reports the failing step number, exit status, the lifecycle working directory (cwd), and a truncated snippet of the command's stderr when available. With strict: true, Patchloom rolls back the staged writes.
  • Prefer instead: Run formatting outside tx when it does not need to participate in the transaction's success criteria.

validate

  • What it does: Runs shell commands that decide whether the transaction should be reported as valid.
  • Use when: Build, test, or policy checks are part of the definition of success for the change.
  • Step fields: Each entry accepts cmd (required shell command), required (bool, default false), and timeout (seconds, default 60).
  • Failure behavior: required: true makes the step gate transaction success. required: false still reports the validation problem to stderr. Error output reports the failing step number, exit status, the lifecycle working directory (cwd), and a truncated snippet of the command's stderr when available.
  • Prefer instead: Use standalone verification outside tx when the mutation and the validation lifecycle should stay separate.

Transaction operations

The operations below are the building blocks inside operations.

replace

  • What it does: Runs text replacement inside a transaction.
  • Use when: A text rewrite needs to share atomic rollback, formatting, or validation with other operations.
  • Requires: Exactly one of to, insert_before, or insert_after, matching top level replace.
  • Regex insert semantics: In regex mode, insert_before and insert_after preserve the matched text, they do not insert the raw pattern string.
  • Optional fields: case_insensitive (bool, default false), multiline (bool, default false), and if_exists (bool, default false) match the top level replace --case-insensitive, --multiline, and --if-exists flags.
  • Related: top level replace

doc.set

  • What it does: Runs a targeted structured set inside a transaction.
  • Use when: A precise config update must be bundled atomically with other repo changes.
  • Field naming: Use selector (not key) for the path expression in doc.set, doc.delete, doc.append, doc.prepend, doc.update, doc.ensure, and doc.delete_where.
  • Related: top level doc set

doc.delete

  • What it does: Removes a structured value inside a transaction.
  • Use when: Schema cleanup should happen as one step in a larger atomic change.
  • Related: top level doc delete

doc.merge

  • What it does: Deep merges structured content inside a transaction.
  • Use when: Several related structured fields should change together as part of one plan.
  • Related: top level doc merge

doc.append

  • What it does: Appends to an array inside a transaction.
  • Use when: List growth must stay atomic with other edits in the same plan.
  • Related: top level doc append

doc.prepend

  • What it does: Prepends to an array inside a transaction.
  • Use when: Ordered config precedence should change as part of a larger atomic mutation.
  • Related: top level doc prepend

doc.update

  • What it does: Updates all matching structured nodes inside a transaction.
  • Use when: A broad structured rewrite should be coupled to other edits and validations.
  • Related: top level doc update

doc.move

  • What it does: Moves or renames a structured selector path inside a transaction.
  • Use when: Schema migration must stay atomic with related code or docs edits.
  • Related: top level doc move

doc.ensure

  • What it does: Adds a structured value only if it is missing, inside a transaction.
  • Use when: Idempotent bootstrapping should happen together with other plan steps.
  • Related: top level doc ensure

doc.delete_where

  • What it does: Deletes array items matching a predicate inside a transaction.
  • Use when: Targeted list cleanup must be coordinated with other transactional edits.
  • Related: top level doc delete-where

md.replace_section

  • What it does: Replaces a markdown section inside a transaction.
  • Use when: Docs regeneration should be part of a larger all or nothing repo change.
  • Related: top level md replace-section

md.insert_after_heading

  • What it does: Inserts markdown content after a heading inside a transaction.
  • Use when: A release note or docs annotation must be added atomically with code or config changes.
  • Related: top level md insert-after-heading

md.insert_before_heading

  • What it does: Inserts markdown content before a heading inside a transaction.
  • Use when: Docs structure must change as one step in a broader plan.
  • Related: top level md insert-before-heading

md.upsert_bullet

  • What it does: Ensures a markdown bullet exists inside a transaction.
  • Use when: Idempotent docs or checklist updates should stay coupled to other edits.
  • Related: top level md upsert-bullet

md.table_append

  • What it does: Appends a markdown table row inside a transaction.
  • Use when: Documentation tables should be updated together with the code or metadata they describe.
  • Related: top level md table-append

md.dedupe_headings

  • What it does: Removes duplicate markdown headings inside a transaction.
  • Use when: Cleanup of generated docs should stay atomic with the rest of the plan.
  • Related: top level md dedupe-headings

md.lint_agents

  • What it does: Lints an AGENTS.md file for common problems (duplicate headings, dangerous commands outside code fences, missing final newline) inside a transaction.
  • Use when: Agent rules validation should be part of a larger plan, e.g., lint before and after markdown edits to confirm no new issues.
  • Related: top level md lint-agents, MCP md_lint

tidy.fix

  • What it does: Applies tidy normalization inside a transaction.
  • Use when: Text cleanup should be part of the same atomic success criteria as other edits.
  • Related: top level tidy fix

file.create

  • What it does: Creates a file inside a transaction.
  • Use when: New files must appear only if the full plan succeeds.
  • Related: top level create

file.delete

  • What it does: Deletes a file inside a transaction.
  • Use when: File removal should roll back if later format or validation steps fail.
  • Related: top level delete

file.rename

  • What it does: Renames (moves) a file inside a transaction.
  • Use when: File renames should roll back if later format or validation steps fail. More efficient than read + file.create + file.delete as a single operation.
  • Related: top level rename

search

  • What it does: Searches a file for a pattern inside a transaction and includes match results in the JSON output without writing anything.
  • Use when: An agent needs to locate patterns before replacing them in the same plan, enabling locate-then-edit in a single call.
  • Optional fields: regex (bool, default false), case_insensitive (bool, default false), multiline (bool, default false), context (lines around matches), before_context, and after_context match the top level search flags.
  • Related: top level search

read

  • What it does: Reads a file inside a transaction and includes its content in the JSON output without writing anything. The JSON read result carries the same line metadata as top level read (start_line, end_line, total_lines), and when no line range is requested it preserves the raw file content exactly.
  • Use when: An agent needs to inspect file content before or after other operations in the same plan, enabling "understand then edit" in a single call.
  • Related: top level read

patch.apply

  • What it does: Applies a unified diff inside a transaction.
  • Use when: Patch replay needs to compose with earlier in plan edits and share the same rollback or validation behavior.
  • Related: top level patch apply