feat(cli): make pipecat create internal

changelog/4867.changed.md

@@ -0,0 +1 @@
+- `pipecat create` is no longer listed in `pipecat --help`. `pipecat init` is now the single entry point for starting a Pipecat project. `pipecat create` continues to work unchanged for automation and AI coding agents.

src/pipecat/cli/__init__.py

@@ -7,8 +7,9 @@
 """Pipecat CLI - command-line tools for building Pipecat AI voice agents.
 
 This package provides command-line tools for:
-- Scaffolding new Pipecat projects with `pipecat create`
-- Making a project agent-ready (AGENTS.md + CLAUDE.md) with `pipecat init`
+- Starting a new Pipecat project with `pipecat init` to scaffold a bot and
+make it agent-ready
+- Running behavioral evals against a bot with `pipecat eval`
 
 And allows installing extensions like Pipecat Cloud:
 - Deploying to Pipecat Cloud with `pipecat cloud`

src/pipecat/cli/agent_templates/AGENTS.md

@@ -40,8 +40,8 @@ pipecat create --name mybot \
 #   • --dry-run prints the resolved config as JSON; --config project.json drives it from a file.
 #   • --transport is repeatable — pass each transport you want (production + a local-dev one, §2).
 #   • --bot-type is inferred from --transport (telephony if any telephony transport, else web) — omit it.
-
-# Humans (interactive wizard): `pipecat create quickstart` (defaults) or `pipecat create`.
+#   • `create` is intentionally NOT listed in `pipecat --help`, but it's fully functional —
+#     it's the scaffolder you build with. Use it headlessly as shown.
 ```
 
 **Choose *with* the user, not for them.** Map their requirements to the real options and confirm transport / services / mode / deployment (§7) before scaffolding — don't silently pick or guess. Mode affects testing speed — **cascade (STT→LLM→TTS)** gets the fast text-mode eval loop (§6); **realtime (speech-to-speech)** is tested in audio mode — but both run headless, so pick the mode the use case needs.

src/pipecat/cli/agent_templates/GETTING_STARTED.md

@@ -2,9 +2,9 @@
 
 **This file is for you**: how to drive your coding agent well. The other
 files here are for the **agent**: AGENTS.md teaches it how to build Pipecat
-apps — scaffold with `pipecat create`, check APIs against live sources
-instead of stale training data, verify its own work with headless evals —
-and CLAUDE.md loads it into Claude Code.
+apps — scaffold the project, check APIs against live sources instead of
+stale training data, verify its own work with headless evals — and
+CLAUDE.md loads it into Claude Code.
 
 ## First: set up the Pipecat Context Hub
 

src/pipecat/cli/main.py

@@ -73,7 +73,12 @@ def _build_app():
 
     # `create` is a plain command (not a sub-Typer group) so it can take an optional
     # positional target path followed by options (e.g. `pc create . --bot-type web`).
-    app.command("create", help="Create a new Pipecat project")(create_command)
+    # It is `hidden=True` so it doesn't appear in `pipecat --help`: `pipecat init` is the
+    # single advertised starting point for humans. `create` stays fully functional — it's
+    # the scaffolder that coding agents and automation call non-interactively (per the
+    # bundled AGENTS.md), and that `init` itself wraps — just no longer surfaced as an
+    # entry point.
+    app.command("create", help="Create a new Pipecat project", hidden=True)(create_command)
 
     # `init` makes a project agent-ready (writes AGENTS.md + CLAUDE.md). ignore_unknown_options
     # lets it catch legacy scaffolder flags (now `pipecat create`) and redirect with a clear

tests/cli/test_create_hidden.py

@@ -0,0 +1,50 @@
+#
+# Copyright (c) 2025-2026, Daily
+#
+# SPDX-License-Identifier: BSD 2-Clause License
+#
+
+"""Tests that `pipecat create` is hidden from `--help` yet stays fully functional.
+
+`pipecat init` is the single advertised entry point. `create` is the underlying
+scaffolder that coding agents and automation call non-interactively, so it must keep
+working — it's just no longer listed in `pipecat --help`.
+"""
+
+import re
+
+from typer.testing import CliRunner
+
+from pipecat.cli.main import app
+
+runner = CliRunner()
+
+_ANSI_RE = re.compile(r"\x1b\[[0-9;]*m")
+
+
+def _norm(text: str) -> str:
+    """Normalize help output so assertions survive rich's ANSI colors and borders."""
+    text = _ANSI_RE.sub("", text)
+    for ch in "│╭╮╰╯─":
+        text = text.replace(ch, " ")
+    return " ".join(text.split())
+
+
+class TestCreateHidden:
+    """`create` is hidden from the top-level help but remains invocable."""
+
+    def test_create_not_listed_in_top_level_help(self):
+        result = runner.invoke(app, ["--help"])
+        assert result.exit_code == 0
+        out = _norm(result.output)
+        # `init` is the advertised starting point...
+        assert "init" in out
+        # ...and `create` is not listed as a command.
+        assert "create" not in out
+
+    def test_create_help_still_works(self):
+        result = runner.invoke(app, ["create", "--help"])
+        # The command is hidden, not removed: `pipecat create --help` still resolves.
+        assert result.exit_code == 0
+        out = _norm(result.output)
+        assert "create" in out