diff --git a/changelog/4867.changed.md b/changelog/4867.changed.md new file mode 100644 index 00000000000..07517302198 --- /dev/null +++ b/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. diff --git a/src/pipecat/cli/__init__.py b/src/pipecat/cli/__init__.py index e1206106a50..1f238d2709a 100644 --- a/src/pipecat/cli/__init__.py +++ b/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` diff --git a/src/pipecat/cli/agent_templates/AGENTS.md b/src/pipecat/cli/agent_templates/AGENTS.md index 84c4e5dfb57..8022bbfc574 100644 --- a/src/pipecat/cli/agent_templates/AGENTS.md +++ b/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. diff --git a/src/pipecat/cli/agent_templates/GETTING_STARTED.md b/src/pipecat/cli/agent_templates/GETTING_STARTED.md index f05456ea12f..013a182214d 100644 --- a/src/pipecat/cli/agent_templates/GETTING_STARTED.md +++ b/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 diff --git a/src/pipecat/cli/main.py b/src/pipecat/cli/main.py index e05b5e6975f..7c6e0131181 100644 --- a/src/pipecat/cli/main.py +++ b/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 diff --git a/tests/cli/test_create_hidden.py b/tests/cli/test_create_hidden.py new file mode 100644 index 00000000000..6f184f8632c --- /dev/null +++ b/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