Validate Commands

Validate your pipeline definitions and configuration for correctness.

The validate command has three subcommands depending on what you want to validate:

pipelex validate pipe ...      # Validate a pipe from your project's library
pipelex validate bundle ...    # Validate a bundle file or directory
pipelex validate method ...    # Validate an installed method package

Validate Pipe

pipelex validate pipe <PIPE_CODE>
pipelex validate pipe --all

Validates and dry-runs a specific pipe from your imported packages, or all pipes at once.

Arguments:

• PIPE_CODE - The pipe code to validate (omit when using --all)

Options:

• --all, -a - Validate all discovered pipes
• --library-dir, -L - Directory to search for pipe definitions. Can be specified multiple times.
• --allow-signatures - Accept PipeSignature placeholders in the dependency graph (lenient mode). See Signature Pipes.

Examples:

# Validate a specific pipe
pipelex validate analyze_cv_matching
pipelex validate write_weekly_report

# Validate all pipes
pipelex validate --all

# Explicit subcommand form also works
pipelex validate pipe --all

# Validate with custom library directories
pipelex validate my_pipe -L ./pipelines
pipelex validate --all -L ./pipelines -L ./shared_pipes

# Allow PipeSignature placeholders during dry-run
pipelex validate my_draft_pipe --allow-signatures
pipelex validate --all --allow-signatures

Validate Bundle

pipelex validate bundle <PATH>

Validates all pipes defined in a bundle file (.mthds), or every bundle of a method's folder. A folder is read as its method tree, the method rooted at the nearest METHODS.toml at or above it, else at the folder itself, and the whole tree is judged, as the MTHDS protocol's validation judges a method: every bundle of it is loaded and every pipe of it dry-run, whatever its bundles declare of where the method starts. A folder whose bundles declare several main_pipes, or none, is validated like any other, since validation needs no pipe to start at; only a command acting on one pipe, such as pipelex run bundle, needs the folder's entry. Only the tree's own pipes are judged: the -L directories, a nested package below the folder with its own METHODS.toml, and the packages the method depends on all load for its bundles to use, but their own pipes are not judged. A folder whose tree cannot be read, such as one past this machine's limits or holding a symbolic link, is an invalid verdict naming the folder, with exit code 1. A folder holding no .mthds bundle produces no verdict and exits with code 2, and so does a configuration that does not validate, which the command reads before Pipelex starts for the limits a folder's tree is listed under: Failed to validate: names what to correct.

Arguments:

• PATH - Path to a .mthds bundle file or a method's folder

Options:

• --library-dir, -L - Directory to search for additional pipe definitions. Can be specified multiple times.
• --allow-signatures - Accept PipeSignature placeholders in the dependency graph (lenient mode). See Signature Pipes.

Examples:

# Validate a bundle file
pipelex validate bundle my_pipeline.mthds
pipelex validate bundle pipelines/invoice_processor.mthds

# Validate a method's folder (every bundle of its method tree)
pipelex validate bundle pipelines/invoice_processor/

# Validate with additional library directories
pipelex validate bundle my_bundle.mthds -L ./shared_pipes

# Allow PipeSignature placeholders during dry-run
pipelex validate bundle methods/draft_pipeline.mthds --allow-signatures

Validate Method

pipelex validate method <NAME>

Validates all pipes in an installed method package.

Arguments:

• NAME - The name of the installed method to validate, a method address (github.com/owner/repo[/name][@tag]), or a GitHub URL — see Run a Method by Address

Options:

• --pipe PIPE_CODE - Validate only a specific pipe within the method
• --library-dir, -L - Directory to search for additional pipe definitions. Can be specified multiple times.

Examples:

# Validate an installed method
pipelex validate method invoice_extractor

# Validate a specific pipe within a method
pipelex validate method invoice_extractor --pipe extract_amounts

An Invalid Bundle Is a Verdict

Every refusal of your method raised while it is loaded or validated is reported as an invalid bundle: the grouped ❌ Bundle validation failed output naming each error's pipe, domain, field and file, printed on stderr with any --traceback stack trace, with exit code 1. Exit code 2 is kept for the cases where no verdict could be produced — bad arguments, a target that does not resolve, or a failure of Pipelex or its environment. This holds on every subcommand: validate pipe and validate --all render a pipe whose dry run fails the same way validate bundle does, where they used to print a traceback. A failing dry run is listed under Dry Run Errors: with one entry per failing pipe, naming the innermost pipe that failed and is not allowed to fail rather than every controller around it, and every error found while parsing gets its own entry, so a misspelled field is reported beside the other errors instead of after they are fixed. A few refusals raised while a pipe is built do not classify themselves as a fault of your method yet, and those still stop validation without a verdict.

A pipe that names a model your model deck does not define is the most common case. It is reported as an Unknown Model error on that pipe, with the path of the field that names it (pipe.<code>.model, or pipe.<code>.model_to_structure for the model a PipeLLM structures its output with) and the deck's close matches:

Pipe Validation Errors:

1. Unknown Model
   Pipe: write_tide_note
   Domain: tide_tables
   Field: model
   → Pipe 'write_tide_note' (PipeLLM), field 'model': Alias 'best-sonet' was not found in the model deck

Did you mean: @best-gpt
   💡 Suggested fix (unsafe, confirm before applying): Replace model '@best-sonet' of pipe 'write_tide_note' with '@best-gpt', its one close match in the model deck
   └─ Path: pipe.write_tide_note.model

When the deck offers exactly one close match, as here, the error carries a suggested fix naming it. The fix is marked unsafe, its line says so, and pipelex fix bundle does not apply it on its own: the match is a guess from the spelling, and a close name can be a different model, with its own provider, cost and behaviour, so check it before you write it. With several matches, choosing among them is yours; pipelex-agent check-model <name> -t <type> and pipelex-agent models -t <type> list what the deck defines.

Suggested Fixes

When a validation error has a deterministic fix, the error output includes a 💡 Suggested fix line describing the change. A safe fix reads 💡 Suggested fix:, and when at least one safe fix targets a file the command may write, the report ends with the exact command that applies those fixes automatically:

💡 1 of these errors can be fixed automatically — run: pipelex fix bundle my_pipeline.mthds

An unsafe fix reads 💡 Suggested fix (unsafe, confirm before applying):. It is a likely correction that could still be wrong, such as a model name the deck only nearly matches, so pipelex fix bundle never applies it and the footer does not count it: check the change, then make it by hand. pipelex-agent prints the same labels in its Markdown, and its JSON carries each fix's safety as safe or unsafe.

See Fix Commands for pipelex fix bundle, including the --diff preview.

Advisory Warnings

A bundle can be valid and still be worth commenting on. When it is, pipelex validate bundle and pipelex validate --all print one yellow Warning: line per finding — advisory only: a warning never changes the verdict or the exit code. The lines come out ahead of the success message, and ahead of the strict pending-signature gate too, so a method still holding an unimplemented PipeSignature placeholder shows its warnings even though the command exits non-zero. Four families are reported, always in this order:

• optional_force_redundant — a ! (force) input whose slot is guaranteed present in every analyzed flow, so the assertion can never fire.
• input_presence_vacuous — a method input (an input of the bundle's declared main_pipe) that must be supplied, but whose concept declares no required field: the empty object satisfies it, so a caller cannot tell what to fill in.
• hint_unknown_key, hint_unknown_intent, hint_inapplicable_intent — the intent-hint lints. Hints are non-normative, so the entry is preserved and only named.
• template_check_warning — a warning the engine's template check found in a PipeDocGen step's office template file during the dry run, such as an Excel defined name or a PowerPoint shape name that matches no input field. The line names the step, the file and the place in it.

pipelex validate pipe <PIPE_CODE> prints only the last family: one pipe makes no bundle-wide claim, so the three lints have nothing to say about it, but what its dry run found is about that pipe.

The same findings ride the warnings array of the agent CLI's JSON envelope and of the validation report, built from one composition point, so the surfaces cannot disagree. See Understanding Optionality for what each one means for your method.

What Validation Checks

All validation commands check:

• Syntax correctness of .mthds files
• Concept and pipe definitions are valid
• Every model a pipe names is defined in your model deck
• Input/output connections are correct
• All referenced pipes and concepts exist
• Dry-run execution succeeds without errors, which implies the logic is correct and the pipe can be run

Related Configuration

• Dry Run Configuration