feat(cli)!: make init the single entry point, fold in and remove create

README.md

@@ -8,7 +8,7 @@
 
 **Pipecat** is an open-source Python framework for building real-time voice and multimodal conversational agents. Build a single voice agent or a full multi-agent system where specialists hand off, fan out in parallel, and coordinate over a shared bus, locally or distributed across processes and machines. Orchestrate audio and video, AI services, transports, and conversation pipelines effortlessly, so you can focus on what makes your agents unique.
 
-> Want to dive right in? Run `pipecat create quickstart` or follow the [quickstart guide](https://docs.pipecat.ai/getting-started/quickstart).
+> Want to dive right in? Run `pipecat init quickstart` or follow the [quickstart guide](https://docs.pipecat.ai/getting-started/quickstart).
 
 ## 🚀 What You Can Build
 
@@ -47,7 +47,7 @@ Want to build beautiful and engaging experiences? Checkout the [Voice UI Kit](ht
 
 ### 🛠️ Create and deploy projects
 
-The [Pipecat CLI](https://docs.pipecat.ai/api-reference/cli/overview) ships with `pipecat-ai` — install it with `uv tool install "pipecat-ai[cli]"`. Scaffold a project in under a minute with `pipecat create`, or run `pipecat init` to make a project agent-ready so an AI coding assistant (Claude Code, Codex) builds it for you. Then use the CLI to monitor and deploy your agent to production.
+The [Pipecat CLI](https://docs.pipecat.ai/api-reference/cli/overview) ships with `pipecat-ai` — install it with `uv tool install "pipecat-ai[cli]"`. Run `pipecat init` to start a project: it sets you up so an AI coding assistant (Claude Code, Codex) builds it for you, and can scaffold a runnable bot in under a minute. Then use the CLI to monitor and deploy your agent to production.
 
 ### 🔍 Debugging
 

changelog/4861.changed.md

@@ -1,4 +1,4 @@
-- `pipecat init` is now the starting point for building a Pipecat app. It makes your project agent-ready by writing `AGENTS.md` and `CLAUDE.md`, then helps you build:
+- `pipecat init` is now the starting point for building a Pipecat app. It writes the coding-agent files `AGENTS.md` and `CLAUDE.md`, then helps you build:
   - Build with a coding agent (such as Claude Code or Codex). This also writes a `GETTING_STARTED.md` guide for building Pipecat apps with an AI coding assistant.
   - Scaffold a runnable bot immediately through an interactive setup wizard.
-  - Run `pipecat init quickstart` to scaffold the ready-to-run quickstart project, agent-ready in one step.
+  - Run `pipecat init quickstart` to scaffold the ready-to-run quickstart project, set up for coding agents in one step.

changelog/4869.changed.md

@@ -0,0 +1 @@
+- ⚠️ `pipecat init` now keeps existing `AGENTS.md`, `CLAUDE.md`, and `GETTING_STARTED.md` files instead of overwriting them on re-run. When a guide was written by an older Pipecat version, an interactive run offers to refresh it; otherwise pass the new `--overwrite-guide` flag (renamed from `--force`, now covering all three files) to refresh them.

changelog/4883.removed.md

@@ -0,0 +1 @@
+- ⚠️ Removed the `pipecat create` command; scaffolding now lives in `pipecat init`, the single entry point for starting a Pipecat app. Alongside the coding-agent guide (`AGENTS.md`, `CLAUDE.md`) it already wrote, `pipecat init` now also scaffolds a runnable bot — interactively, or non-interactively from flags or a config file (e.g. `pipecat init . --bot-type web -t daily --stt deepgram_stt --llm openai_llm --tts cartesia_tts`; run `pipecat init --list-options` for valid values). `pipecat init quickstart` replaces `pipecat create quickstart`. Scaffolding is now directory-first and in-place — the project name comes from the target directory, and `create`'s `--output/-o` and `--name`-subfolder layout are gone.

src/pipecat/cli/__init__.py

@@ -7,8 +7,10 @@
 """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`
+- Initializing a new Pipecat project with `pipecat init` (the entry point: writes the
+  coding-agent guide, then helps you build with a coding agent or scaffolds a runnable
+  bot — interactively or non-interactively from flags or a config file)
+- 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

@@ -25,23 +25,22 @@ Always begin from the deterministic CLI scaffold. It gives you a known-good stru
 uv tool install "pipecat-ai[cli]"   # provides the `pipecat` (alias `pc`) command
 ```
 
-> ⚠️ **Agents: scaffold non-interactively** — bare `pipecat create` opens an interactive wizard that **hangs an automated run**. Pass every choice as flags (or `--config`):
+> ⚠️ **Agents: scaffold non-interactively** — bare `pipecat init` (no scaffold flags) opens an interactive wizard that **hangs an automated run**. Pass your choices as flags (or `--config`):
 
 ```bash
-# Headless: --name (or --config) switches to non-interactive mode.
+# Headless: any scaffold flag (--bot-type, a service, or --config) switches off the wizard.
+# Run it in the project directory you're already in; `.` scaffolds in place, name from the dir.
 # The service values below are EXAMPLES — map the user's actual choices, don't copy these.
-pipecat create --name mybot \
+pipecat init . \
   --transport smallwebrtc --mode cascade \
   --stt deepgram_stt --llm openai_llm --tts cartesia_tts \
   --eval                             # eval transport + starter scenarios, for verification (§6)
 #   • Don't hand-write flags from memory — discover them:
-#       pipecat create --help          # available flags
-#       pipecat create --list-options  # valid service/transport VALUES
+#       pipecat init --help          # available flags
+#       pipecat init --list-options  # valid service/transport VALUES
 #   • --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`.
 ```
 
 **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.
@@ -197,7 +196,7 @@ A voice app can't be eyeballed like a web page — but you don't need a live cal
 
 > **Deep reference:** the **Pipecat Evals docs** are the authoritative spec — look them up via your Pipecat MCP (§3): **Overview**, **Writing Scenarios** (the schema + the two modality axes), **Using the Library** (the Python API), **Agent Self-Improvement** (the closed-loop workflow this section describes). For working examples, copy the **scaffolded starters in `server/evals/`** rather than writing YAML from scratch. The eval harness ships in the `pipecat-ai[evals]` extra (the `pipecat eval` command plus the local Kokoro/Moonshine speech models); scaffolding with `--eval` adds it, so run evals from the **bot's own environment**.
 
-**Make your bot eval-able.** Scaffold with `pipecat create --eval` (headless) — pass it whenever you scaffold a bot you intend to test. The generated bot has the `eval` transport entry, eval dependencies in its env, and **runnable starter scenarios in `server/evals/`**: `starter_text.yaml` (the fast inner loop; cascade only) and `starter_audio.yaml` (the full round trip). They pass against the freshly scaffolded bot, so run them *first* to prove the loop, then edit them to match the bot you're building and copy them to grow the suite. For an **existing** bot, add the transport entry by hand (a one-time change; RTVI is already on by default for `PipelineWorker`, so that's the only edit):
+**Make your bot eval-able.** Scaffold with `pipecat init . --eval` (headless) — pass it whenever you scaffold a bot you intend to test. The generated bot has the `eval` transport entry, eval dependencies in its env, and **runnable starter scenarios in `server/evals/`**: `starter_text.yaml` (the fast inner loop; cascade only) and `starter_audio.yaml` (the full round trip). They pass against the freshly scaffolded bot, so run them *first* to prove the loop, then edit them to match the bot you're building and copy them to grow the suite. For an **existing** bot, add the transport entry by hand (a one-time change; RTVI is already on by default for `PipelineWorker`, so that's the only edit):
 ```python
 from pipecat.evals.transport import EvalTransportParams
 

src/pipecat/cli/agent_templates/GETTING_STARTED.md

@@ -1,10 +1,8 @@
 # Getting Started — Building Pipecat Bots with a Coding Agent
 
 **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.
+files here (`AGENTS.md`, `CLAUDE.md`) are the agent's guide, instructing
+it how to write, run, and test Pipecat code.
 
 ## First: set up the Pipecat Context Hub
 

src/pipecat/cli/commands/__init__.py

@@ -6,6 +6,6 @@
 
 """CLI commands for Pipecat CLI."""
 
-from . import create, init
+from . import init
 
-__all__ = ["create", "init"]
+__all__ = ["init"]