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/Run-help-escape · L-261008-156344 (#1377)

Louis Choquelc117be17580f
diff --git a/.badges/tests.json b/.badges/tests.json
index 70e0da708..ef7276a98 100644
--- a/.badges/tests.json
+++ b/.badges/tests.json
@@ -1,7 +1,7 @@
{
"schemaVersion": 1,
"label": "tests",
- "message": "16496",
+ "message": "16504",
"color": "blue",
"cacheSeconds": 300
}
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.toml
index 078ce8e17..346d99d16 100644
--- a/.drift/acks/cli-docs.toml
+++ b/.drift/acks/cli-docs.toml
@@ -1,8 +1,8 @@
contract = "cli-docs"
-digest = "sha256:1753075a19fa8a93ee26f9bb162c2f085ebb07d90d565e0690a8c9f356bb026f"
+digest = "sha256:97cce33271beed9b555021ecd78eb67e83261f51634f4e8e99054ad3d08269e1"
reviewed_by = "Claude (Opus 5.5)"
-reviewed_at = "2026-10-08T13:14:35Z"
-rationale = "clean-pass: merge of the reviewed tip of feature/Pipelex-runs-hosted-via into this branch, the ack file taken from that tip. The merge changes no trigger file: every trigger blob equals the one this branch last acked, and the open changes are this branch's own work since that tip, the login command, init's question of where runs execute with its setup_path module, and the former-release cleanup across migrate, doctor, init, the CLI factories, agent_output and error_handlers. The merged docs answer each: login.md covers the browser and paste flows, the 0600 home .env and PIPELEX_APP_URL; init.md describes the hosted or local question written to the run execution setting and the former-release cleanup it offers first; migrate.md and agent-cli.md describe the cleanup, FormerReleaseConfigError and the former_release key, and agent-cli.md and the agent CLI CLAUDE.md list execution in the init config and the hosted doctor verdict. Nothing under docs/tools/cli is stale against the merged CLI."
+reviewed_at = "2026-10-08T13:35:43Z"
+rationale = "clean-pass: merge of origin/dev into this branch, the ack file taken from dev. The open trigger changes are this branch's own work and nothing else: every other trigger file now equals dev's acked blob, and the five changed files only escape square brackets in help strings so Rich markup stops dropping them, the --hosted/--local help of pipelex run bundle, pipe and method, the shared --runner help of pipelex-agent run, and the --config help of pipelex-agent init. The rendered help now reads [run] execution and list[str], which run.md, agent-cli.md and init.md under docs/tools/cli already describe, and the agent CLI CLAUDE.md names [run] execution in prose but quotes none of these help strings, so nothing under the review targets is stale. The help guard test walks every help text of the three CLIs, the login, init and migrate commands dev brought included, and passes."
[trigger_files]
"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"
@@ -23,7 +23,7 @@ rationale = "clean-pass: merge of the reviewed tip of feature/Pipelex-runs-hoste
"pipelex/cli/agent_cli/commands/fix/app.py" = "blob:e6190d9bde6a05755c04bd21806f699461038ac0"
"pipelex/cli/agent_cli/commands/fix/bundle_cmd.py" = "blob:cfd9e645986636c44c02a6a04a0fc67ed60d444b"
"pipelex/cli/agent_cli/commands/fmt_cmd.py" = "blob:97d6fb6c328e0b718b1293bd6b73cba03edcb7dc"
-"pipelex/cli/agent_cli/commands/init_cmd.py" = "blob:e8ff262f4c0a0e1bd1cf75d4008276b8d5552169"
+"pipelex/cli/agent_cli/commands/init_cmd.py" = "blob:2151fa938858604e7cd9dba9462e030e95c137c0"
"pipelex/cli/agent_cli/commands/inputs/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/agent_cli/commands/inputs/_inputs_core.py" = "blob:4161029643f3a302de54fa637d2676521e10d873"
"pipelex/cli/agent_cli/commands/inputs/app.py" = "blob:7e19284687b334c684fb03381a8d9d20af1aa152"
@@ -37,7 +37,7 @@ rationale = "clean-pass: merge of the reviewed tip of feature/Pipelex-runs-hoste
"pipelex/cli/agent_cli/commands/run/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/agent_cli/commands/run/_output_helpers.py" = "blob:40ed1700e0d5e86d7696eadd7f9887baeb8059f6"
"pipelex/cli/agent_cli/commands/run/_run_core.py" = "blob:32f973c5c754b23016f3e708ab3235856e8bc5f4"
-"pipelex/cli/agent_cli/commands/run/_run_hosted.py" = "blob:8178b10eff95faf8bfac8d4c12895a47dbda9b90"
+"pipelex/cli/agent_cli/commands/run/_run_hosted.py" = "blob:cea011e61feb082a7b9d82d7693b4fd3246737e5"
"pipelex/cli/agent_cli/commands/run/app.py" = "blob:64b2ecc02007cda11b526d8d3fc139593875dd9d"
"pipelex/cli/agent_cli/commands/run/bundle_cmd.py" = "blob:cf85194e29f44b0691eb81b216d2e506fcdd75f2"
"pipelex/cli/agent_cli/commands/run/method_cmd.py" = "blob:7c5f73a28e50f30196088af2435cbc2f635a65e5"
@@ -111,10 +111,10 @@ rationale = "clean-pass: merge of the reviewed tip of feature/Pipelex-runs-hoste
"pipelex/cli/commands/run/_run_core.py" = "blob:a41aafa3ee899c51e4b3b3919d164c8aaebe2095"
"pipelex/cli/commands/run/_run_hosted.py" = "blob:dd5801877a636f71187e9b23c2fab18d4d25ba32"
"pipelex/cli/commands/run/app.py" = "blob:a7090b0ff6bf2f1d47827fa27d2a138096a2e148"
-"pipelex/cli/commands/run/bundle_cmd.py" = "blob:18659c5024e19d94bfb3116596c0b1db34970ea2"
+"pipelex/cli/commands/run/bundle_cmd.py" = "blob:169220d5ec5784a47802c3894c13b9809fd569fd"
"pipelex/cli/commands/run/exceptions.py" = "blob:e9552226e597922b6ac0757f7b52eb880a2e1472"
-"pipelex/cli/commands/run/method_cmd.py" = "blob:a3858adc9d74b6de5d119d8082e00995d24a95a1"
-"pipelex/cli/commands/run/pipe_cmd.py" = "blob:4da3fce1bc0782b56ab75274738611ca65c655f7"
+"pipelex/cli/commands/run/method_cmd.py" = "blob:549d356113febc4888ad36eb94ffb51e4a89232a"
+"pipelex/cli/commands/run/pipe_cmd.py" = "blob:e43e844a9877832aa89c308cb4b6f52486cf2ce5"
"pipelex/cli/commands/show_cmd.py" = "blob:4c87c70058ea3b15827d03a370f3345569a2b705"
"pipelex/cli/commands/update_cmd.py" = "blob:b2db6170ddd9c67f17d88096ba1f1796a897557d"
"pipelex/cli/commands/validate/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fc2d70bf5..c1990fea0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,7 @@
### Fixed
- **A home configuration directory holding only some files gets the kit's missing ones**: every boot now copies into `~/.pipelex/`, or the directory `PIPELEX_HOME` names, each kit file it lacks, never overwriting one it holds or writing through a symbolic link, so a kit file deleted from it comes back. A directory holding anything at all, such as the `pipelex_service.toml` an earlier release wrote, used to be left as it was, and every boot then failed with "Config files are missing for the inference backend library". The inference files are copied as one unit, only when the directory has no `inference/backends.toml`, each file and kit manifest is written whole or not at all, so a fill cut short is completed by the next boot, and a directory Pipelex cannot write to is read as it is.
+- **`pipelex-agent init --help` keeps `list[str]`**: the `--config` help printed the schema's `"backends": list[str]` as `"backends": list`, because Typer renders help as Rich markup and Rich took `[str]` for a style; the bracket is now escaped and printed.
## [v0.78.0] - 2026-10-08
diff --git a/pipelex/cli/agent_cli/commands/init_cmd.py b/pipelex/cli/agent_cli/commands/init_cmd.py
index e8ff262f4..2151fa938 100644
--- a/pipelex/cli/agent_cli/commands/init_cmd.py
+++ b/pipelex/cli/agent_cli/commands/init_cmd.py
@@ -350,11 +350,12 @@ def agent_init_cmd(
typer.Option(
"--config",
"-c",
+ # Typer renders help as Rich markup, which drops an unescaped [str] or [run]: \[ prints the bracket.
help=(
"Inline JSON string or path to a JSON file. "
- 'Schema: {"execution": "hosted" | "local", "backends": list[str], "primary_backend": str}. '
+ r'Schema: {"execution": "hosted" | "local", "backends": list\[str], "primary_backend": str}. '
"All fields are optional. "
- "execution: where runs execute by default, written to [run] execution; 'hosted' runs on the hosted Pipelex API "
+ r"execution: where runs execute by default, written to \[run] execution; 'hosted' runs on the hosted Pipelex API "
"with the key in PIPELEX_API_KEY and configures no backend; 'local' (the default) runs on this machine. "
"backends: backend keys to enable (e.g. 'openai', 'anthropic', 'openrouter'). Omit to keep template defaults "
"and the template's routing profile. "
diff --git a/pipelex/cli/agent_cli/commands/run/_run_hosted.py b/pipelex/cli/agent_cli/commands/run/_run_hosted.py
index 8178b10ef..cea011e61 100644
--- a/pipelex/cli/agent_cli/commands/run/_run_hosted.py
+++ b/pipelex/cli/agent_cli/commands/run/_run_hosted.py
@@ -33,8 +33,9 @@ from pipelex.hosted.run_config import RunExecution
if TYPE_CHECKING:
from pipelex_sdk.client import PipelexAPIClient
-#: The `--runner` help, shared by the run commands.
-RUNNER_OPTION_HELP = "Where the run executes: 'local' (this machine) or 'hosted' (the hosted Pipelex API). Default: [run] execution, else local."
+#: The `--runner` help, shared by the run commands. Typer renders help as Rich markup, which drops an unescaped `[run]`,
+#: so the bracket is escaped as `\[`.
+RUNNER_OPTION_HELP = r"Where the run executes: 'local' (this machine) or 'hosted' (the hosted Pipelex API). Default: \[run] execution, else local."
#: The `--hosted/--local` help, shared by the run commands.
HOSTED_OPTION_HELP = "Run on the hosted Pipelex API (key in PIPELEX_API_KEY) or on this machine; the same choice as --runner."
#: The `--base-url` help, shared by the run commands.
diff --git a/pipelex/cli/commands/run/bundle_cmd.py b/pipelex/cli/commands/run/bundle_cmd.py
index 18659c502..169220d5e 100644
--- a/pipelex/cli/commands/run/bundle_cmd.py
+++ b/pipelex/cli/commands/run/bundle_cmd.py
@@ -112,7 +112,8 @@ def run_bundle_cmd(
bool | None,
typer.Option(
"--hosted/--local",
- help="Run on the hosted Pipelex API (key in PIPELEX_API_KEY) or on this machine. Default: [run] execution, else local.",
+ # Typer renders help as Rich markup, which drops an unescaped [run]: \[ prints the bracket.
+ help=r"Run on the hosted Pipelex API (key in PIPELEX_API_KEY) or on this machine. Default: \[run] execution, else local.",
),
] = None,
base_url: Annotated[
diff --git a/pipelex/cli/commands/run/method_cmd.py b/pipelex/cli/commands/run/method_cmd.py
index a3858adc9..549d35611 100644
--- a/pipelex/cli/commands/run/method_cmd.py
+++ b/pipelex/cli/commands/run/method_cmd.py
@@ -111,7 +111,8 @@ def run_method_cmd(
bool | None,
typer.Option(
"--hosted/--local",
- help="Run on the hosted Pipelex API (key in PIPELEX_API_KEY) or on this machine. Default: [run] execution, else local.",
+ # Typer renders help as Rich markup, which drops an unescaped [run]: \[ prints the bracket.
+ help=r"Run on the hosted Pipelex API (key in PIPELEX_API_KEY) or on this machine. Default: \[run] execution, else local.",
),
] = None,
base_url: Annotated[
diff --git a/pipelex/cli/commands/run/pipe_cmd.py b/pipelex/cli/commands/run/pipe_cmd.py
index 4da3fce1b..e43e844a9 100644
--- a/pipelex/cli/commands/run/pipe_cmd.py
+++ b/pipelex/cli/commands/run/pipe_cmd.py
@@ -106,7 +106,8 @@ def run_pipe_cmd(
bool | None,
typer.Option(
"--hosted/--local",
- help="Run on the hosted Pipelex API (key in PIPELEX_API_KEY) or on this machine. Default: [run] execution, else local.",
+ # Typer renders help as Rich markup, which drops an unescaped [run]: \[ prints the bracket.
+ help=r"Run on the hosted Pipelex API (key in PIPELEX_API_KEY) or on this machine. Default: \[run] execution, else local.",
),
] = None,
base_url: Annotated[
diff --git a/tests/unit/pipelex/cli/test_cli_help_brackets.py b/tests/unit/pipelex/cli/test_cli_help_brackets.py
new file mode 100644
index 000000000..a60da1dd1
--- /dev/null
+++ b/tests/unit/pipelex/cli/test_cli_help_brackets.py
@@ -0,0 +1,115 @@
+r"""Help text keeps its square brackets on every CLI.
+
+Typer renders every help text, option help, docstring, epilog and help panel through Rich markup, and Rich reads a
+bracketed lowercase word such as `[run]` or `[str]` as a style tag: one that names no style renders as nothing, so
+"Default: [run] execution" printed as "Default: execution". A bracket meant literally is escaped as `\[`.
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from typing import TYPE_CHECKING
+
+import click
+import pytest
+import typer
+from rich.text import Text
+from typer.testing import CliRunner
+
+from pipelex.cli._cli import app as pipelex_app
+from pipelex.cli.agent_cli._agent_cli import app as agent_app
+from pipelex.cli.dev_cli._dev_cli import app as dev_app
+
+if TYPE_CHECKING:
+ from collections.abc import Iterator
+
+ from pytest_mock import MockerFixture
+
+ROOT_CLI_MODULE = "pipelex.cli._cli"
+RUN_SETTING_DEFAULT = "Default: [run] execution, else local."
+
+
+def _rendered_help(*, app: typer.Typer, args: list[str]) -> str:
+ """Render `<args> --help` through the real app, as one line of plain text.
+
+ Rich wraps a long help over several rows of the options table, so the box drawing and the line breaks are folded
+ away and a sentence reads whole at any terminal width; the colour codes a forced terminal adds are stripped too.
+ """
+ result = CliRunner().invoke(app, [*args, "--help"], env={"COLUMNS": "200"})
+ assert result.exit_code == 0, result.output
+ return " ".join(click.unstyle(result.output).replace("│", " ").split())
+
+
+def _help_texts(*, command: click.Command, path: str) -> Iterator[tuple[str, str]]:
+ """Every text Typer renders through Rich markup for a command and its subcommands, with where it comes from."""
+ command_texts = {
+ "help": command.help,
+ "short_help": command.short_help,
+ "epilog": command.epilog,
+ "rich_help_panel": getattr(command, "rich_help_panel", None),
+ }
+ for label, text in command_texts.items():
+ if text:
+ yield f"{path} ({label})", text
+ for param in command.params:
+ for label in ("help", "rich_help_panel"):
+ text = getattr(param, label, None)
+ if isinstance(text, str) and text:
+ yield f"{path} {param.name} ({label})", text
+ if isinstance(command, click.Group):
+ for name, subcommand in command.commands.items():
+ yield from _help_texts(command=subcommand, path=f"{path} {name}")
+
+
+class TestCliHelpBrackets:
+ @pytest.fixture(autouse=True)
+ def _restore_logging_cutoff(self) -> Iterator[None]:
+ """Restore the process-global `logging.disable` threshold that the agent CLI's app callback arms."""
+ original_disable = logging.root.manager.disable
+ yield
+ logging.disable(original_disable)
+
+ @pytest.mark.parametrize(
+ ("app", "args", "expected_phrases"),
+ [
+ (pipelex_app, ["--no-logo", "run", "bundle"], [RUN_SETTING_DEFAULT]),
+ (pipelex_app, ["--no-logo", "run", "pipe"], [RUN_SETTING_DEFAULT]),
+ (pipelex_app, ["--no-logo", "run", "method"], [RUN_SETTING_DEFAULT]),
+ (agent_app, ["run", "bundle"], [RUN_SETTING_DEFAULT]),
+ (agent_app, ["run", "pipe"], [RUN_SETTING_DEFAULT]),
+ (agent_app, ["run", "method"], [RUN_SETTING_DEFAULT]),
+ (agent_app, ["init"], ['"backends": list[str],', "written to [run] execution;"]),
+ ],
+ ids=[
+ "pipelex-run-bundle",
+ "pipelex-run-pipe",
+ "pipelex-run-method",
+ "pipelex-agent-run-bundle",
+ "pipelex-agent-run-pipe",
+ "pipelex-agent-run-method",
+ "pipelex-agent-init",
+ ],
+ )
+ def test_rendered_help_keeps_the_bracketed_words(
+ self,
+ mocker: MockerFixture,
+ app: typer.Typer,
+ args: list[str],
+ expected_phrases: list[str],
+ ) -> None:
+ mocker.patch(f"{ROOT_CLI_MODULE}.check_readiness")
+ rendered = _rendered_help(app=app, args=args)
+ for phrase in expected_phrases:
+ assert phrase in rendered, f"`{' '.join(args)} --help` lost a bracket: {phrase!r} is not in the rendered help:\n{rendered}"
+
+ def test_rich_markup_renders_every_help_text_verbatim(self) -> None:
+ r"""Rich renders every help text of every CLI as written, bar the `\[` escapes: no bracket is taken as a style."""
+ offenders: list[str] = []
+ for program, app in (("pipelex", pipelex_app), ("pipelex-agent", agent_app), ("pipelex-dev", dev_app)):
+ for where, text in _help_texts(command=typer.main.get_command(app), path=program):
+ written = inspect.cleandoc(text)
+ rendered = Text.from_markup(written).plain
+ if rendered != written.replace("\\[", "["):
+ offenders.append(f"{where}: {written!r} renders as {rendered!r}")
+ assert not offenders, "Rich markup swallows a bracket in these help texts; escape it as \\[:\n" + "\n".join(offenders)