Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

fix: escape the method-address example so `--help` renders (#1169)

Louis Choquel767e600f9f1d
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.toml
index 10e3b7177..4b54c0589 100644
--- a/.drift/acks/cli-docs.toml
+++ b/.drift/acks/cli-docs.toml
@@ -1,8 +1,8 @@
contract = "cli-docs"
-digest = "sha256:440d54e77c7ab292acb88632345fedf82ad29e2d7c35cc7149fa95f7d12c7b4f"
+digest = "sha256:c28a7ec0b029ea11e2ca96dccf909609b4b34ed1079e67d6e24f5bb34e5863d1"
reviewed_by = "Louis Choquel"
-reviewed_at = "2026-08-29T02:36:21Z"
-rationale = "Rebase of the fetch-on-miss branch onto v0.55.0: installed_methods.py now carries the install write path plus the review hardening (occupied-target identity check, unique mkdtemp staging with rename-race tolerance) on top of dev's method_resolver changes. No CLI command, flag, or help text changed; run-by-address.md documents both sides (build-runner materialization from dev, symlink refusal from this branch); the agent-CLI contract doc is unaffected."
+reviewed_at = "2026-08-30T16:39:08Z"
+rationale = "Escaping the rich markup in the NAME argument help of the eight method subcommands. No command, flag, argument or documented surface changed: the address grammar the help states is identical before and after, and the escape exists only because typer renders argument help through rich's markup parser, which read the literal [/name] as a closing tag and crashed. Reviewed docs/tools/cli/ — run.md, validate.md, run-by-address.md and the three build pages state the same grammar in Markdown, where the brackets are already literal, so nothing there was stale; no page carries a verbatim --help transcript. pipelex/cli/agent_cli/CLAUDE.md is unaffected, since the two-stream output contract it documents is untouched."
[trigger_files]
"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"
@@ -30,7 +30,7 @@ rationale = "Rebase of the fetch-on-miss branch onto v0.55.0: installed_methods.
"pipelex/cli/agent_cli/commands/inputs/_inputs_core.py" = "blob:d37826d96099028a1ad5dbc5cbf8ce0cfdb01e30"
"pipelex/cli/agent_cli/commands/inputs/app.py" = "blob:7e19284687b334c684fb03381a8d9d20af1aa152"
"pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py" = "blob:43ac0fe0887f5f31144df4e4973a1ab1d0dec166"
-"pipelex/cli/agent_cli/commands/inputs/method_cmd.py" = "blob:15e8d82bd1536449c6690fd2975d84b4018b6130"
+"pipelex/cli/agent_cli/commands/inputs/method_cmd.py" = "blob:582c3dbf1c8199f1f79856ffcc536c7e1226d21c"
"pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py" = "blob:a5cf89c89d5e2e84cc7b817ec184e8dc9e92b781"
"pipelex/cli/agent_cli/commands/lint_cmd.py" = "blob:91ad9cb4d618ba4c0b7da366cde2f74f38d350df"
"pipelex/cli/agent_cli/commands/migrate_cmd.py" = "blob:ce733b78df03e65c3c8a10d46b27b57c05ec054c"
@@ -43,14 +43,14 @@ rationale = "Rebase of the fetch-on-miss branch onto v0.55.0: installed_methods.
"pipelex/cli/agent_cli/commands/run/_run_core_api.py" = "blob:78a27e0ba91e6bbf99c11caedb29ad4cf20ac78b"
"pipelex/cli/agent_cli/commands/run/app.py" = "blob:64b2ecc02007cda11b526d8d3fc139593875dd9d"
"pipelex/cli/agent_cli/commands/run/bundle_cmd.py" = "blob:daf6207146c0ea41fe34bb272ed51350208af790"
-"pipelex/cli/agent_cli/commands/run/method_cmd.py" = "blob:d65cdba36e63563d0f225dafc7f8593b91af9317"
+"pipelex/cli/agent_cli/commands/run/method_cmd.py" = "blob:f61145e5706f2b36134aafe844653ae6d719be8c"
"pipelex/cli/agent_cli/commands/run/pipe_cmd.py" = "blob:df5e7f80a328932ffde901eda8d0585d009678ad"
"pipelex/cli/agent_cli/commands/run/stdin_resolver.py" = "blob:4bc7f4e91ddb3900a75356f8f8e6ba5a586a3690"
"pipelex/cli/agent_cli/commands/validate/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/agent_cli/commands/validate/_validate_core.py" = "blob:6e9e8488573fe17d7769608e299879a092ceaf6c"
"pipelex/cli/agent_cli/commands/validate/app.py" = "blob:d2d0ed19288c2d1c25be1650dd962189fcdb3b86"
"pipelex/cli/agent_cli/commands/validate/bundle_cmd.py" = "blob:3207973c194b096ed5c6ec2d3a955c417789e019"
-"pipelex/cli/agent_cli/commands/validate/method_cmd.py" = "blob:38fae7d9f8f26594f80e875251e926cc99f26dff"
+"pipelex/cli/agent_cli/commands/validate/method_cmd.py" = "blob:794914167c13975bc0cdff7b301a8268ff1b79b6"
"pipelex/cli/agent_cli/commands/validate/pipe_cmd.py" = "blob:7c15cf5a7341b774baad2f14540acbef8daebf76"
"pipelex/cli/bundle_target_resolution.py" = "blob:8dccc50b700b877968ed1b2c1c3652ab1c32e956"
"pipelex/cli/cli_factory.py" = "blob:1f859ab3b995e1a67e5fdc812a168d56c338e970"
@@ -61,19 +61,19 @@ rationale = "Rebase of the fetch-on-miss branch onto v0.55.0: installed_methods.
"pipelex/cli/commands/build/inputs/_inputs_core.py" = "blob:50317e058df75070722d2e29edab4537e6b7b438"
"pipelex/cli/commands/build/inputs/app.py" = "blob:2a7770c8294b8c2c1b4420ac00d6ffdfa50609bf"
"pipelex/cli/commands/build/inputs/bundle_cmd.py" = "blob:0cd99e9d307f46b8e8899bf7d5f3813563fcdf10"
-"pipelex/cli/commands/build/inputs/method_cmd.py" = "blob:fffeebfbec3ae19c5030619b647719e953c50b15"
+"pipelex/cli/commands/build/inputs/method_cmd.py" = "blob:34d3a67c33c6856be965a3a15142f9c53baf0585"
"pipelex/cli/commands/build/inputs/pipe_cmd.py" = "blob:00625740fd29837e3165d31be692e40e96065fc8"
"pipelex/cli/commands/build/output/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/commands/build/output/_output_core.py" = "blob:9ba47b88a3c0b6cbf3f8de5f9a4939373f64ceb8"
"pipelex/cli/commands/build/output/app.py" = "blob:67996650b99551fbd58be30e692688204d16935a"
"pipelex/cli/commands/build/output/bundle_cmd.py" = "blob:54c07aedb123eaaf2049965859e82b6d4800560d"
-"pipelex/cli/commands/build/output/method_cmd.py" = "blob:1a21e5d106870ea4d66014ccba07a378b7aa970b"
+"pipelex/cli/commands/build/output/method_cmd.py" = "blob:242434d518aff0b9706b910e7f937b53a601fde1"
"pipelex/cli/commands/build/output/pipe_cmd.py" = "blob:eb0db8279c93fcff9d5fe4546f593d753282acb5"
"pipelex/cli/commands/build/runner/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/commands/build/runner/_runner_core.py" = "blob:e4745231cb46547de93d83d1ac7a6db28ae81494"
"pipelex/cli/commands/build/runner/app.py" = "blob:b5aa321ed93dc2cb9b138e4a26bae9eb75c732b7"
"pipelex/cli/commands/build/runner/bundle_cmd.py" = "blob:5b5ca0628f0595a0c3aae9b539ae4e7e0c92a853"
-"pipelex/cli/commands/build/runner/method_cmd.py" = "blob:7d8ff2457569b3efa68830db6cdd031e4c6b9b2d"
+"pipelex/cli/commands/build/runner/method_cmd.py" = "blob:cea9a0365bc828c9f83cdcb88f4faee13d8fc6de"
"pipelex/cli/commands/build/structures_cmd.py" = "blob:d13ba3b6fc1433f787e1aa97c6c04a67483ec7ed"
"pipelex/cli/commands/bundle_path_resolver.py" = "blob:60c6a2994c9b7c6e0ec212702467d668eecb6d50"
"pipelex/cli/commands/codegen/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
@@ -115,7 +115,7 @@ rationale = "Rebase of the fetch-on-miss branch onto v0.55.0: installed_methods.
"pipelex/cli/commands/run/app.py" = "blob:a7090b0ff6bf2f1d47827fa27d2a138096a2e148"
"pipelex/cli/commands/run/bundle_cmd.py" = "blob:cb420bf4879c863d64c5e20ed535c42732b720a2"
"pipelex/cli/commands/run/exceptions.py" = "blob:e9552226e597922b6ac0757f7b52eb880a2e1472"
-"pipelex/cli/commands/run/method_cmd.py" = "blob:47344150d71386398ef9a4fad8aca54a3ea1d0a8"
+"pipelex/cli/commands/run/method_cmd.py" = "blob:9f5c7b6ad8f7fc7d086a9e6253049c6e2ec3e7d8"
"pipelex/cli/commands/run/pipe_cmd.py" = "blob:f92fcb94e3ad55cf5aeec366a59fa7a74bcc9667"
"pipelex/cli/commands/show_cmd.py" = "blob:7974d91404ea93f05b16b05b9aef3c1a540b965d"
"pipelex/cli/commands/update_cmd.py" = "blob:06100ec3b9d6c66ca89a8c1536aa27983ae409ca"
@@ -123,7 +123,7 @@ rationale = "Rebase of the fetch-on-miss branch onto v0.55.0: installed_methods.
"pipelex/cli/commands/validate/_validate_core.py" = "blob:3294c9c716ac616a89213c7356d38a8eff62da40"
"pipelex/cli/commands/validate/app.py" = "blob:309061423af13f2f6c496a024306ad696af567ab"
"pipelex/cli/commands/validate/bundle_cmd.py" = "blob:1fbf3e0cf695db39101c83160a724df6468988e9"
-"pipelex/cli/commands/validate/method_cmd.py" = "blob:db630f0a3ce633b54721656ef0758d9bda0f7839"
+"pipelex/cli/commands/validate/method_cmd.py" = "blob:f12ee233fc985d04a4512f1fef6b9ea02a1b9644"
"pipelex/cli/commands/validate/pipe_cmd.py" = "blob:d67267571559006459628180f2c8b216ba7fee31"
"pipelex/cli/commands/which_cmd.py" = "blob:68661d4bab22e2c4dab183d59bd9f2c6dd573472"
"pipelex/cli/deck_notice.py" = "blob:542877125e89e35b02bc969cfee952155b0d7c2c"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9c55c3e0e..c226d8e35 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,7 @@
### Fixed
+- **`--help` works again on every `method` subcommand**: `pipelex validate method`, `pipelex run method`, the three `pipelex build ... method` commands and their agent-CLI twins all crashed with a rich `MarkupError` traceback instead of printing their help. The method-address example in each command's `NAME` argument help — `github.com/owner/repo[/name][@tag]` — reaches rich's markup parser through typer, which read `[/name]` as a closing tag with no opening one. The brackets are escaped at each of the sites, so the example renders as written and the help exits zero.
- **Class-backed concepts reflect field by field in the input-form descriptor**: a concept declaring `structure = "SomeClass"` used to collapse to `kind: "unknown"` the moment one field annotation could not be mapped, taking every sibling field with it — and a nested non-native pydantic model was reported as an opaque payload rather than walked into. Every `document` and `image` position beneath such a concept disappeared from the descriptor, so a consumer preparing inputs from it passed a local file path at one of those positions through un-uploaded and the run failed on the unresolved path. Reflection is now partial: each annotation is mapped on its own, an unmappable one is `unknown` at that field alone, a nested model is an `object` the reflection walks into, a `list[X]` reports its element node, and a class that holds itself is cut at the revisit instead of recursing. A `RootModel` is reported as its root annotation's node wherever it appears — as a field of a reflected class, and as the registered class backing the concept itself — because the value it accepts is the root value, so the descriptor no longer states an object over a synthetic `root` key that contradicts the `json_schema` derived beside it. The native consistency probe keeps its faithful-or-absent rule — it is compared against a normative pinned blueprint, where a plausible-looking partial answer would be the failure — and the two reflections now share one annotation vocabulary (`pipelex/core/concepts/annotation_shapes.py`) instead of one calling the other. See [Input-Form Descriptor](under-the-hood/input-form-descriptor.md).
- **Generated-image storage key extension follows the actual mime type**: a generated image could be stored under a `.png` key while its bytes and reported `mime_type` were `image/jpeg`, because `GeneratedContentFactory` picked the key's extension from the *requested* image format while `mime_type` came from the provider's *actual* answer — and a provider may return a different format than requested. The factory now resolves the effective mime type once (provider-reported, then base64-extracted, then the requested format, then the `image/jpeg` default) and derives the storage-key extension from that same value, on every path (stored bytes and fetched remote content alike), so the key and the `mime_type` can no longer diverge and anything inferring a type from the extension sees the truth.
diff --git a/pipelex/cli/agent_cli/commands/inputs/method_cmd.py b/pipelex/cli/agent_cli/commands/inputs/method_cmd.py
index 15e8d82bd..582c3dbf1 100644
--- a/pipelex/cli/agent_cli/commands/inputs/method_cmd.py
+++ b/pipelex/cli/agent_cli/commands/inputs/method_cmd.py
@@ -24,7 +24,7 @@ from pipelex.pipeline.exceptions import ValidateBundleError
def inputs_method_cmd(
name: Annotated[
str,
- typer.Argument(help="Installed method name, method address (github.com/owner/repo[/name][@tag]), or GitHub URL"),
+ typer.Argument(help="Installed method name, method address (github.com/owner/repo\\[/name]\\[@tag]), or GitHub URL"),
],
pipe: Annotated[
str | None,
diff --git a/pipelex/cli/agent_cli/commands/run/method_cmd.py b/pipelex/cli/agent_cli/commands/run/method_cmd.py
index d65cdba36..f61145e57 100644
--- a/pipelex/cli/agent_cli/commands/run/method_cmd.py
+++ b/pipelex/cli/agent_cli/commands/run/method_cmd.py
@@ -30,7 +30,7 @@ def run_method_cmd(
ctx: typer.Context,
name: Annotated[
str,
- typer.Argument(help="Installed method name, method address (github.com/owner/repo[/name][@tag]), or GitHub URL"),
+ typer.Argument(help="Installed method name, method address (github.com/owner/repo\\[/name]\\[@tag]), or GitHub URL"),
],
pipe: Annotated[
str | None,
diff --git a/pipelex/cli/agent_cli/commands/validate/method_cmd.py b/pipelex/cli/agent_cli/commands/validate/method_cmd.py
index 38fae7d9f..794914167 100644
--- a/pipelex/cli/agent_cli/commands/validate/method_cmd.py
+++ b/pipelex/cli/agent_cli/commands/validate/method_cmd.py
@@ -32,7 +32,7 @@ from pipelex.pipeline.validation_render import format_validate_markdown
def validate_method_cmd(
name: Annotated[
str,
- typer.Argument(help="Installed method name, method address (github.com/owner/repo[/name][@tag]), or GitHub URL"),
+ typer.Argument(help="Installed method name, method address (github.com/owner/repo\\[/name]\\[@tag]), or GitHub URL"),
],
pipe: Annotated[
str | None,
diff --git a/pipelex/cli/commands/build/inputs/method_cmd.py b/pipelex/cli/commands/build/inputs/method_cmd.py
index fffeebfbe..34d3a67c3 100644
--- a/pipelex/cli/commands/build/inputs/method_cmd.py
+++ b/pipelex/cli/commands/build/inputs/method_cmd.py
@@ -14,7 +14,7 @@ from pipelex.pipe_machinery.rendering.input_renderer import InputsTemplateFormat
def build_inputs_method_cmd(
name: Annotated[
str,
- typer.Argument(help="Installed method name, method address (github.com/owner/repo[/name][@tag]), or GitHub URL"),
+ typer.Argument(help="Installed method name, method address (github.com/owner/repo\\[/name]\\[@tag]), or GitHub URL"),
],
pipe: Annotated[
str | None,
diff --git a/pipelex/cli/commands/build/output/method_cmd.py b/pipelex/cli/commands/build/output/method_cmd.py
index 1a21e5d10..242434d51 100644
--- a/pipelex/cli/commands/build/output/method_cmd.py
+++ b/pipelex/cli/commands/build/output/method_cmd.py
@@ -13,7 +13,7 @@ from pipelex.core.concepts.concept_representation_generator import ConceptRepres
def build_output_method_cmd(
name: Annotated[
str,
- typer.Argument(help="Installed method name, method address (github.com/owner/repo[/name][@tag]), or GitHub URL"),
+ typer.Argument(help="Installed method name, method address (github.com/owner/repo\\[/name]\\[@tag]), or GitHub URL"),
],
pipe: Annotated[
str | None,
diff --git a/pipelex/cli/commands/build/runner/method_cmd.py b/pipelex/cli/commands/build/runner/method_cmd.py
index 7d8ff2457..cea9a0365 100644
--- a/pipelex/cli/commands/build/runner/method_cmd.py
+++ b/pipelex/cli/commands/build/runner/method_cmd.py
@@ -13,7 +13,7 @@ from pipelex.cli.method_resolver import method_output_base_dir, resolve_method_t
def build_runner_method_cmd(
name: Annotated[
str,
- typer.Argument(help="Installed method name, method address (github.com/owner/repo[/name][@tag]), or GitHub URL"),
+ typer.Argument(help="Installed method name, method address (github.com/owner/repo\\[/name]\\[@tag]), or GitHub URL"),
],
pipe: Annotated[
str | None,
diff --git a/pipelex/cli/commands/run/method_cmd.py b/pipelex/cli/commands/run/method_cmd.py
index 47344150d..9f5c7b6ad 100644
--- a/pipelex/cli/commands/run/method_cmd.py
+++ b/pipelex/cli/commands/run/method_cmd.py
@@ -13,7 +13,7 @@ from pipelex.cli.method_resolver import method_output_base_dir, resolve_method_t
def run_method_cmd(
name: Annotated[
str,
- typer.Argument(help="Installed method name, method address (github.com/owner/repo[/name][@tag]), or GitHub URL to run"),
+ typer.Argument(help="Installed method name, method address (github.com/owner/repo\\[/name]\\[@tag]), or GitHub URL to run"),
],
pipe: Annotated[
str | None,
diff --git a/pipelex/cli/commands/validate/method_cmd.py b/pipelex/cli/commands/validate/method_cmd.py
index db630f0a3..f12ee233f 100644
--- a/pipelex/cli/commands/validate/method_cmd.py
+++ b/pipelex/cli/commands/validate/method_cmd.py
@@ -12,7 +12,7 @@ from pipelex.cli.method_resolver import resolve_method_target
def validate_method_cmd(
name: Annotated[
str,
- typer.Argument(help="Installed method name, method address (github.com/owner/repo[/name][@tag]), or GitHub URL to validate"),
+ typer.Argument(help="Installed method name, method address (github.com/owner/repo\\[/name]\\[@tag]), or GitHub URL to validate"),
],
pipe: Annotated[
str | None,