Updated docs for init / create commands by markbackman · Pull Request #941 · pipecat-ai/docs

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

Documentation for the pipecat init "starting point" work (pipecat-ai/pipecat#4861).

Changes

pipecat init is the starting point. Reframed the init reference around initializing a new project, then routing to a build method (coding agent or scaffold now). Documented pipecat init quickstart.
pipecat create stays documented, just not the advertised path. It remains a real command with its own reference page and CLI nav entry; the get-started flow and the CLI overview hero lead with init, so developers reach create by seeking it out in the reference (writing a coding-agent skill, scripting scaffolding, understanding what init runs).
Quickstart and examples now 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.

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:30:47Z

If create is really only for bots to invoke after an init (if the user goes the coding agent route) or for init to invoke directly (if the user goes the wizard route), why not just treat it as "private" and not even discuss it? That'll help with the onboarding confusion.

In fact, we should also remove it from the output of pipecat --help. It currently still looks like the main way to get started, to anyone looking at that output.

(Or find some way of burying it, maybe marking it as deprecated or something)

I made a change to the CLI to hide the create command. That means that the command is still usable and you can get help info, but it doesn't appear in pipecat --help. You can still see how to use it by running pipecat create --help, which the agents will need:
pipecat-ai/pipecat#4867

Along with this change, I've removed the create reference. Not sure if this is a good idea since we're hiding info from the agent about how headless scaffolding works...

kompfner · 2026-06-23T19:33:39Z

 ---
 title: init
-description: "Make a project agent-ready by writing the Pipecat coding-agent guide"
+description: "The starting point for building a Pipecat app: make a project agent-ready, then build with a coding agent or scaffold a runnable bot"


This still implies that it takes an existing project and makes it agent-ready. That's not really what it does, right?

This whole description, I think, should be rewritten to present a simpler mental model for the user; it's a bit wordy and confused-sounding.

Maybe something along the lines of:

Initialize a new Pipecat app. Gives you a choice about how to scaffold your project: - Using a coding agent like Claude Code or Codex - Using an interactive wizard No matter how you choose to scaffold your app, coding agent files—AGENTS.md and CLAUDE.md—are provided to help your favorite coding agent work well with Pipecat.

(Exact wording TBD, but hopefully a good illustration of how to reframe in a simple compact way)

Oh, and also:

This command can be run again to update the coding agent files with the latest and greatest Pipecat guidance.

Or, per https://github.com/pipecat-ai/docs/pull/941/changes#r3462691884:

This command can be run again with `--update-coding-agents` to update the coding agent files with the latest and greatest Pipecat guidance.

Simplified the intro.

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.

kompfner · 2026-06-23T19:52:27Z

-</Note>
+After writing those, **interactive `pipecat init` asks how you want to build**:
+
+- **Build with a coding agent** (recommended): open your coding tool and let it scaffold and iterate. The agent drives [`pipecat create`](/api-reference/cli/create) itself, non-interactively. This path also writes **`GETTING_STARTED.md`**, developer-facing guidance on setting up the [Pipecat Context Hub](/api-reference/context-hub), writing an effective first prompt, and what to expect from a coding session.


Sounds like GETTING_STARTED.md like it contains some things that would be useful even if you wanted to go the wizard route and use a coding agent later to continue development. It shouldn't be tethered (at least fully) to whether the user chooses to use the wizard or not.

Some ideas:

Always include some parts in it (e.g. context hub) but only include others (e.g. effective first prompt) if the user goes the non-wizard route

Split into PIPECAT_README.md (always useful) and GETTING_STARTED.md (only for non-wizard usage)

kompfner · 2026-06-23T20:11:49Z

- The written `AGENTS.md` ends with a provenance footer naming the `pipecat-ai` version that wrote it, so a stale guide is detectable and refreshable.
- Passing scaffolder flags (e.g. `--name`, `--bot-type`) prints a message redirecting you to [`pipecat create`](/api-reference/cli/create) and exits non-zero.
+- **`AGENTS.md` is always (re)written**, so re-running `pipecat init` refreshes the guide after a Pipecat upgrade. `GETTING_STARTED.md` is written (and refreshed) on the coding-agent path only, not when scaffolding a bot now or via `pipecat init quickstart`.
+- **`CLAUDE.md` is preserved if it already exists**: pass `--force` to overwrite it.


This is feedback on pre-existing behavior, and thus outside the scope of this PR, but: giving AGENTS.md and CLAUDE.md different behaviors feels a bit weird to me. It feels like us favoring Claude over other coding agents: a Codex user doesn't have the same control over whether their personal edits to AGENTS.md are preserved when re-running init.

Also: --force isn't a very descriptive name anymore now that init is a broad initialization tool rather than a "make-ready-for-agents" tool.

So, some suggestions:

Call it something more like --update-coding-agents

Make it apply to both files - if --update-coding-agents is not provided, init doesn't update either (so it should no-op if the project already exists; no magic updating)

(In other words, the way to update coding-agent files is to run init --update-coding-agents)

- 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

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

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

		@@ -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`;

Conversation

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

Uh oh!

Changes

Uh oh!

github-actions Bot commented Jun 23, 2026

Uh oh!

kompfner Jun 23, 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 Jun 23, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kompfner Jun 23, 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 Jun 23, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

markbackman commented Jun 23, 2026 •

edited

Loading

kompfner Jun 23, 2026 •

edited

Loading

kompfner Jun 23, 2026 •

edited

Loading

kompfner Jun 23, 2026 •

edited

Loading

kompfner Jun 23, 2026 •

edited

Loading