feat(cli)!: make init the single entry point, fold in and remove create by markbackman · Pull Request #4883 · pipecat-ai/pipecat

markbackman · 2026-06-24T19:44:43Z

Summary

Makes pipecat init the single entry point for building a Pipecat app and removes pipecat create, folding its scaffolding into init. create shipped only in the last release, so we're opting for a clean break now rather than carrying two commands (and two location models).

pipecat init still writes the coding-agent guide (AGENTS.md + CLAUDE.md) and now also scaffolds a runnable bot — interactively, or non-interactively from flags or a config file:

pipecat init . --bot-type web -t daily --mode cascade \
  --stt deepgram_stt --llm openai_llm --tts cartesia_tts

This shape fits the real agent workflow: a developer runs pipecat init my-bot to lay down the guide, opens a coding session in that directory, and the agent scaffolds in place with pipecat init . ….

What changed

Scaffolding moved into init. A new pipecat/cli/scaffold.py holds the scaffolder — the interactive wizard, the quickstart preset, and the non-interactive flag/config-file build — reusing the existing config validator and project generator.
pipecat init gained the full scaffold flag surface (minus --output/-o). Scaffolding is directory-first and in-place: the project name is derived from the target directory, and . / no target means the current directory, so an automated run never hangs on a prompt.
pipecat create removed. A hidden stub points users to pipecat init instead of Click's bare "No such command".
AGENTS.md template updated so coding agents scaffold with pipecat init . ….
pipecat init --help reorganized into grouped panels ("Scaffold options" / "Scaffold features") with usage examples.
Docs are handled separately in pipecat-ai/docs.

This PR also absorbs the earlier CLI-cleanup commits (docstring tidy, drop "agent-ready" jargon, streamline GETTING_STARTED.md) that lived in #4868 — that PR is superseded by this one.

Breaking change

pipecat create is removed. Use pipecat init (pipecat init --help, pipecat init --list-options). pipecat create quickstart → pipecat init quickstart. The --output/-o flag and the --name→./<name>-subfolder layout are gone — scaffolding is always in-place in the target directory.

Test plan

uv run pytest tests/cli/ — full CLI suite passes
uv run ruff check / ruff format --check — clean
Real-binary smoke across the init paths (guide-only, in-place scaffold, config file, --dry-run, quickstart) and the removed-create stub

🤖 Generated with Claude Code

- `cli/__init__.py`: list the actual command surface — `init` (entry point), `create`, and `eval` - Replace the "agent-ready" terminology across the CLI with plain language ("initialize a project" / "set up for coding agents"), matching the docs. Rename the internal `_print_agent_ready` helper to `_print_ready` and change its message to "Your project is ready."

Trim the orientation paragraph to what the human reader needs — this file is yours; AGENTS.md/CLAUDE.md are the agent's guide, picked up automatically. Drop the breakdown of what AGENTS.md teaches the agent.

`pipecat init` is now the single entry point for building a Pipecat app. It still writes the coding-agent guide (AGENTS.md + CLAUDE.md) and now also scaffolds a runnable bot — interactively, or non-interactively from flags or a config file: pipecat init . --bot-type web -t daily --mode cascade \ --stt deepgram_stt --llm openai_llm --tts cartesia_tts Scaffolding is directory-first and in-place (project name derived from the target dir); create's --output/-o and --name-subfolder layout are gone. A missing target with scaffold flags defaults to the current directory so an automated run never hangs on a prompt. The scaffolder internals move to pipecat/cli/scaffold.py. `pipecat create` is removed; a hidden stub points users to `pipecat init`.

codecov · 2026-06-24T19:53:32Z

Codecov Report

❌ Patch coverage is 96.11111% with 7 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/pipecat/cli/commands/init.py	92.22%	7 Missing ⚠️

Files with missing lines	Coverage Δ
src/pipecat/cli/commands/__init__.py	`100.00% <100.00%> (ø)`
src/pipecat/cli/commands/eval.py	`19.92% <ø> (ø)`
src/pipecat/cli/main.py	`75.00% <100.00%> (+0.86%)`	⬆️
src/pipecat/cli/scaffold.py	`100.00% <100.00%> (ø)`
src/pipecat/cli/commands/init.py	`79.76% <92.22%> (+7.94%)`	⬆️

... and 6 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Group the scaffold flags into "Scaffold options" (the structural, value-taking choices) and "Scaffold features" (the optional boolean toggles) instead of one flat wall of ~24 options. Drop the help= override on the init command so its docstring (summary + examples) drives `pipecat init --help`; tighten that description and flatten the examples to single lines so they render cleanly. Sharpen the TARGET argument help to cover in-place scaffolding, `.`, and quickstart.

… flags Split run_non_interactive_scaffold into resolve_scaffold_config (merge + validate + --dry-run) and generate_scaffold (write), so `pipecat init` validates before writing the agent guide. An incomplete invocation like `pipecat init . --bot-type web` now fails atomically instead of dropping AGENTS.md/CLAUDE.md and then erroring. Also warn when scaffold flags are passed to `pipecat init quickstart` (a fixed preset) instead of silently ignoring them.

AGENTS.md is the coding-agent guide; the bare/quickstart interactive forms are for humans (covered in GETTING_STARTED.md) and the scaffold section's warning already tells the agent to avoid the interactive form.

Make the three guide files `pipecat init` writes (AGENTS.md, CLAUDE.md, GETTING_STARTED.md) follow one uniform rule instead of asymmetric ones. Previously AGENTS.md and GETTING_STARTED.md were always overwritten while CLAUDE.md was preserved — which silently destroyed a non-Claude user's hand-edited AGENTS.md on every re-run. Now: absent -> write; present -> keep it (never clobber silently); `--overwrite-guide` (renamed from `--force`, now covering all three files) to overwrite. A re-run reports what it did per file, and if a kept guide carries an older Pipecat's version stamp it prints a heads-up pointing at `--overwrite-guide` — so staleness is surfaced, not silent. - init.py: `_write_guide_file` helper (absent/keep/overwrite) + `_stamped_version` + `_print_refresh_summary`; footer text and flag/param renamed - tests: re-run now preserves; add stale-nudge and summary coverage

kompfner · 2026-06-25T18:44:30Z

so we're opting for a clean break now rather than carrying two commands

👍

kompfner · 2026-06-25T18:54:50Z

+    # the command's docstring (summary + examples) drives `pipecat init --help`.
+    app.command("init")(init_command)
+
+    # `pipecat create` was removed (folded into `init`). Keep a hidden stub so an old


kompfner · 2026-06-25T18:58:08Z

If this PR lands before mine, I'll rebase and fix my README.md updates to properly reference the new single-entry-point version of init.

FYI: I'll merge later this afternoon.

kompfner

🥳

When `pipecat init` is re-run in a terminal and finds a guide written by an older Pipecat, it now offers to refresh it ("Refresh the guide files now? [Y/n]") rather than only printing a nudge that's easy to miss before the build-method prompt. Re-running signals intent, so a one-keystroke refresh is the expected payoff. Non-interactive runs keep the printed `--overwrite-guide` nudge.

Integrating preserve-by-default (this branch) with init's scaffold path (base): scaffolding over an existing guide now keeps it instead of refreshing it, so update the in-place test to assert preservation.

…te helpers

feat(cli): preserve existing guide files on `pipecat init` re-run

markbackman added 3 commits June 23, 2026 18:42

docs(cli): streamline GETTING_STARTED.md intro

154ca70

Trim the orientation paragraph to what the human reader needs — this file is yours; AGENTS.md/CLAUDE.md are the agent's guide, picked up automatically. Drop the breakdown of what AGENTS.md teaches the agent.

markbackman mentioned this pull request Jun 24, 2026

chore(cli): tidy CLI docstrings and drop "agent-ready" jargon #4868

Closed

chore(changelog): rename fragment to PR 4883

60d9392

markbackman added 2 commits June 24, 2026 16:13

markbackman requested review from aconchillo and kompfner June 24, 2026 20:56

markbackman added 5 commits June 24, 2026 17:02

docs(changelog): match house style for the create-removal entry

6e79841

docs(cli): drop human-facing note from vended AGENTS.md

01a3db8

AGENTS.md is the coding-agent guide; the bare/quickstart interactive forms are for humans (covered in GETTING_STARTED.md) and the scaffold section's warning already tells the agent to avoid the interactive form.

docs(changelog): drop agent-ready jargon from init entry (4861)

466eb45

Add changelog for init preserve-guides change

adcb954

markbackman mentioned this pull request Jun 25, 2026

Docs: make pipecat init the single entry point (remove create) pipecat-ai/docs#941

Merged

kompfner reviewed Jun 25, 2026

View reviewed changes

kompfner approved these changes Jun 25, 2026

View reviewed changes

markbackman added 4 commits June 25, 2026 15:33

test(cli): keep in-place guide preserved under preserve-by-default

4ee9ea1

Integrating preserve-by-default (this branch) with init's scaffold path (base): scaffolding over an existing guide now keeps it instead of refreshing it, so update the in-place test to assert preservation.

refactor(cli): rename overwrite param to overwrite_guide outside _wri…

e6a6d44

…te helpers

Merge pull request #4869 from pipecat-ai/mb/init-preserve-guides

e80f3f1

feat(cli): preserve existing guide files on `pipecat init` re-run

markbackman merged commit 40b9660 into main Jun 25, 2026
6 checks passed

markbackman deleted the mb/init-absorbs-create branch June 25, 2026 19:42

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

feat(cli)!: make init the single entry point, fold in and remove create#4883
markbackman merged 15 commits into
mainfrom
mb/init-absorbs-create

markbackman commented Jun 24, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Jun 24, 2026 •

edited

Loading

Uh oh!

kompfner commented Jun 25, 2026

Uh oh!

kompfner Jun 25, 2026

Uh oh!

kompfner Jun 25, 2026

Uh oh!

markbackman Jun 25, 2026 •

edited

Loading

Uh oh!

kompfner left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

markbackman commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What changed

Breaking change

Test plan

Uh oh!

codecov Bot commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

kompfner commented Jun 25, 2026

Uh oh!

kompfner Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

kompfner Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

markbackman Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kompfner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

markbackman commented Jun 24, 2026 •

edited

Loading

codecov Bot commented Jun 24, 2026 •

edited

Loading

markbackman Jun 25, 2026 •

edited

Loading