Docs: make `pipecat init` the single entry point (remove `create`) by markbackman · Pull Request #941 · pipecat-ai/docs

markbackman · 2026-06-23T17:16:34Z

Documentation for making pipecat init the single entry point for building a Pipecat app. Tracks the framework changes in pipecat-ai/pipecat#4883 (init absorbs scaffolding; pipecat create removed) and pipecat-ai/pipecat#4869 (guide files preserved on re-run; --overwrite-guide).

Changes

pipecat init is the single entry point. Reframed the init reference around initializing a project and scaffolding it — interactively (a build-method wizard) or non-interactively from flags / a config file (pipecat init . --bot-type web -t daily …). Documented the full scaffold flag surface, --list-options, --dry-run, --config, and pipecat init quickstart. Scaffolding is directory-first and in-place (no --output/-o, no --name subfolder).
pipecat create removed. Deleted its reference page and CLI nav entry; added a redirect /api-reference/cli/create → /api-reference/cli/init. Scaffolding now lives entirely under pipecat init.
--overwrite-guide + preserve-by-default. Re-running init keeps existing guide files; a stale guide gets an interactive refresh offer (or a printed nudge non-interactively), and --overwrite-guide forces a refresh.
Quickstart and examples start with pipecat init quickstart.
Dropped the "agent-ready" jargon in favor of "initialize" / "set up for coding agents".
Merged "Build with a Coding Agent" into "Build Your Next Bot." A single agent-first workflow page (install → init → coding-agent path with Context Hub → scaffold-it-yourself → deploy). Deleted ai-tools.mdx, added redirects to the #build-with-a-coding-agent anchor, and updated nav + inbound links.

Depends on

Documents behavior from two stacked framework PRs — merge this after both land (order: #4883 → #4869 → docs):

feat(cli)!: make init the single entry point, fold in and remove create pipecat#4883 — init absorbs scaffolding, create removed
feat(cli): preserve existing guide files on pipecat init re-run pipecat#4869 — preserve guide files on re-run, --overwrite-guide

github-actions · 2026-06-23T17:16:51Z

🔍 Mintlify preview for this branch: https://daily-mb-init-as-start-point-docs.mintlify.app

kompfner · 2026-06-23T19:37:57Z

@@ -29,7 +26,9 @@ pipecat init [TARGET_DIR] [OPTIONS]
 <ParamField path="TARGET_DIR" type="string">
  Directory to make agent-ready. `pipecat init my-bot` targets `./my-bot`;


I think we should avoid using the terminology "make agent-ready" wherever it's still being used. init initializes your Pipecat project.

Removed mentions.

- init as starting point - create acts as an internal / standalone utility

Combine the two overlapping get-started pages into one agent-first workflow. build-your-next-bot.mdx now covers install, `pipecat init` and its fork, the coding-agent path (with Context Hub setup and the coding session), the scaffold-it-yourself path, and deploy/learn. - Delete ai-tools.mdx and remove it from the Get Started nav. - Redirect /pipecat/get-started/ai-tools and the legacy /getting-started/ai-tools to the new #build-with-a-coding-agent anchor, preserving discoverability. - Update inbound links in context-hub.mdx and the-eval-loop.mdx to the anchor. Removes the duplicated init-fork explanation and the circular "the full workflow is over there" cross-links between the two pages.

Make `pipecat init` the only advertised CLI entry point, matching the framework change that hides `create` from `pipecat --help`. - Delete api-reference/cli/create.mdx; remove it from the CLI nav; add a redirect to api-reference/cli/init - Reframe the CLI overview to lead with `init`; drop `create` from cards, command list, and help examples - init.mdx: unlink inline `create` references; replace the "pipecat create" Next Steps card with "Build Your Next Bot" - gemini-live, client quickstart, cloud-builds: start with `pipecat init` (choose "Scaffold a runnable bot now") instead of `pipecat create`

@kompfner

- Reframe `init` as creating a new project rather than retrofitting an existing one (per @kompfner): "create an agent-ready project", not "make a project agent-ready" - Simplify the init.mdx intro to a short choice (coding agent vs. wizard) - Drop the "make agent-ready" terminology everywhere it appeared in this PR; converge on "initialize" across init.mdx and the CLI overview, and describe what `init` writes (AGENTS.md + CLAUDE.md) instead of labeling the project "agent-ready"

Reverse the "treat create as internal" decision: `pipecat create` is a real, documented command — just not the advertised starting point. There are legit reasons to look it up (writing a coding-agent skill, scripting scaffolding, understanding what `init` runs). - Restore api-reference/cli/create.mdx and its CLI nav entry; drop the create -> init redirect - Re-add `create` to the CLI overview command list and help examples, while `init` stays the headline entry point - Get-started pages stay init-only, so a developer seeks `create` out in the reference rather than meeting it on the happy path

Match the framework change (pipecat-ai/pipecat#4869): re-running `pipecat init` now preserves existing AGENTS.md/CLAUDE.md/GETTING_STARTED.md and surfaces a stale guide; `--overwrite-guide` (renamed from `--force`, covering all three files) refreshes them.

pipecat create was removed from the framework; init is now the single entry point that also scaffolds. Delete the create reference page (with a redirect to init), de-list it from the CLI nav/overview, and document the scaffold flags + --overwrite-guide on the init page.

You run `pipecat init`, choose 'Build with a coding agent', then navigate into the project directory and open your agent there to start prompting — the previous wording skipped the build-method selection.

Tie the scaffold-directly path to its build-method choice, parallel to the coding-agent bullet: choosing 'Scaffold a runnable bot now' runs the interactive wizard; passing scaffold options skips the prompts.

Lead with what init does and the two scaffold choices (coding agent or interactive wizard); note the AGENTS.md/CLAUDE.md guarantee. The build-method flow, GETTING_STARTED.md, and the non-interactive flags are covered in the sections below.

kompfner · 2026-06-25T18:27:20Z

 ```

-The CLI will guide you through the setup. Choose the following options:
+When `init` asks how you want to build, choose **Scaffold a runnable bot now**. The wizard will guide you through the setup. Choose the following options:


Maybe nothing to do here for this PR, but wanted to point out a quirk: our CLI tells the user that building with a coding agent is the recommended route, but our main quickstart guide tells us to use the scaffolding wizard.

Oh! Good catch. Let me align the quickstart.

FYI, adding:

<Note> This quickstart uses the interactive `pipecat init` wizard so you end up with the same project this guide walks through below. When you're ready to build your own bot, we recommend driving development with a coding agent — see [Build Your Next Bot](/pipecat/get-started/build-your-next-bot). </Note>

This explains why we're selecting this path while also directing the reader to the key resource for building.

markbackman requested a review from kompfner June 23, 2026 17:26

markbackman force-pushed the mb/init-as-start-point-docs branch from 3518f62 to 017beb0 Compare June 23, 2026 17:29

mintlify Bot deployed to staging June 23, 2026 17:29 View deployment

mintlify Bot deployed to staging June 23, 2026 17:50 View deployment

kompfner reviewed Jun 23, 2026

View reviewed changes

Comment thread api-reference/cli/create.mdx Outdated

kompfner reviewed Jun 23, 2026

View reviewed changes

Comment thread api-reference/cli/init.mdx Outdated

kompfner reviewed Jun 23, 2026

View reviewed changes

Comment thread api-reference/cli/init.mdx Outdated

kompfner reviewed Jun 23, 2026

View reviewed changes

Comment thread api-reference/cli/init.mdx Outdated

markbackman mentioned this pull request Jun 23, 2026

feat(cli): make pipecat create internal pipecat-ai/pipecat#4867

Closed

mintlify Bot deployed to staging June 23, 2026 21:55 View deployment

markbackman added 3 commits June 23, 2026 17:59

Updated docs for init / create commands

a831115

- init as starting point - create acts as an internal / standalone utility

markbackman force-pushed the mb/init-as-start-point-docs branch from 9698640 to 5ab034a Compare June 23, 2026 22:00

mintlify Bot deployed to staging June 23, 2026 22:02 View deployment

mintlify Bot deployed to staging June 23, 2026 22:21 View deployment

mintlify Bot deployed to staging June 23, 2026 22:45 View deployment

markbackman mentioned this pull request Jun 24, 2026

feat(cli): preserve existing guide files on pipecat init re-run pipecat-ai/pipecat#4869

Merged

mintlify Bot deployed to staging June 24, 2026 01:50 View deployment

docs: note init offers to refresh a stale guide interactively

27768c6

mintlify Bot deployed to staging June 24, 2026 02:10 View deployment

markbackman requested a review from kompfner June 24, 2026 02:16

markbackman changed the title ~~Updated docs for init / create commands~~ Docs: make pipecat init the single entry point (remove create) Jun 25, 2026

mintlify Bot deployed to staging June 25, 2026 12:11 View deployment

docs(cli): correct the coding-agent path flow in init reference

843af0e

You run `pipecat init`, choose 'Build with a coding agent', then navigate into the project directory and open your agent there to start prompting — the previous wording skipped the build-method selection.

mintlify Bot deployed to staging June 25, 2026 12:17 View deployment

docs(cli): clarify 'Scaffold a runnable bot now' leads to the wizard

422f873

Tie the scaffold-directly path to its build-method choice, parallel to the coding-agent bullet: choosing 'Scaffold a runnable bot now' runs the interactive wizard; passing scaffold options skips the prompts.

mintlify Bot deployed to staging June 25, 2026 13:08 View deployment

mintlify Bot deployed to staging June 25, 2026 13:11 View deployment

kompfner reviewed Jun 25, 2026

View reviewed changes

kompfner approved these changes Jun 25, 2026

View reviewed changes

Clarify why init wizard in the client quickstart

567e76b

mintlify Bot deployed to staging June 25, 2026 20:05 View deployment

markbackman merged commit 716e2cd into main Jun 25, 2026
3 checks passed

Navigation Menu

Uh oh!

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

Docs: make `pipecat init` the single entry point (remove `create`)#941
markbackman merged 12 commits into
mainfrom
mb/init-as-start-point-docs

markbackman commented Jun 23, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 23, 2026

Uh oh!

Uh oh!

Uh oh!

kompfner Jun 23, 2026

Uh oh!

markbackman Jun 23, 2026

Uh oh!

Uh oh!

Uh oh!

kompfner Jun 25, 2026

Uh oh!

markbackman Jun 25, 2026

Uh oh!

markbackman Jun 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -29,7 +26,9 @@ pipecat init [TARGET_DIR] [OPTIONS]
		<ParamField path="TARGET_DIR" type="string">
		Directory to make agent-ready. `pipecat init my-bot` targets `./my-bot`;

Uh oh!

Conversation

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

Uh oh!

Changes

Depends on

Uh oh!

github-actions Bot commented Jun 23, 2026

Uh oh!

Uh oh!

Uh oh!

kompfner Jun 23, 2026

Choose a reason for hiding this comment

Uh oh!

markbackman Jun 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

kompfner Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

markbackman Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

markbackman Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

markbackman commented Jun 23, 2026 •

edited

Loading