From dacd9e9ecfa20bbff7e480e17687570c7ad493f9 Mon Sep 17 00:00:00 2001 From: Mark Backman Date: Wed, 3 Jun 2026 22:55:22 -0400 Subject: [PATCH 1/5] Update docs for the CLI shipping with pipecat-ai The pipecat init CLI now ships with pipecat-ai as the optional [cli] extra, and pipecatcloud / pipecat-ai-tail are co-installed plugins. - Swap install commands to \`uv tool install "pipecat-ai[cli]"\` across the quickstarts, build-your-next-bot, and the Gemini Live quickstart. - Reframe the CLI overview: init is built in; cloud/tail co-install via \`--with pipecatcloud\` / \`--with pipecat-ai-tail\`. - Fix the Tail page install + observer wiring (pipecat-ai-tail / \`from pipecat_tail.observer import TailObserver\`). - Pipecat Cloud: fix the CI install examples (PATs guide) and add an "Install the CLI" step to the introduction. The deploy GitHub Action is API-key based and untouched. Hold until pipecat-ai 1.4.0 ships with the CLI. --- api-reference/cli/overview.mdx | 17 ++++++++++++----- api-reference/cli/tail.mdx | 10 ++++++++-- client/get-started/quickstart.mdx | 2 +- pipecat-cloud/guides/personal-access-tokens.mdx | 4 ++-- pipecat-cloud/introduction.mdx | 6 ++++++ pipecat/features/gemini-live.mdx | 2 +- pipecat/get-started/build-your-next-bot.mdx | 2 +- pipecat/get-started/quickstart.mdx | 2 +- 8 files changed, 32 insertions(+), 13 deletions(-) diff --git a/api-reference/cli/overview.mdx b/api-reference/cli/overview.mdx index 3c0f7a1f..4f1251bc 100644 --- a/api-reference/cli/overview.mdx +++ b/api-reference/cli/overview.mdx @@ -33,10 +33,10 @@ description: "Command-line tool for scaffolding, deploying, and monitoring Pipec ## Installation -Install the CLI globally with [uv](https://docs.astral.sh/uv/): +The CLI ships with `pipecat-ai` as the optional `cli` extra. Install it globally with [uv](https://docs.astral.sh/uv/): ```bash -uv tool install pipecat-ai-cli +uv tool install "pipecat-ai[cli]" ``` Verify installation: @@ -47,13 +47,20 @@ pipecat --version All commands can use either `pipecat` or the shorter `pc` alias. +This gives you `pipecat init`. The `cloud` and `tail` commands are provided by separate packages that you co-install with `--with`: + +```bash +# Add deploy + monitor commands +uv tool install "pipecat-ai[cli]" --with pipecatcloud --with pipecat-ai-tail +``` + ## Commands -**[`pipecat init`](/api-reference/cli/init)** - Scaffold new projects with interactive setup +**[`pipecat init`](/api-reference/cli/init)** - Scaffold new projects with interactive setup (built in) -**[`pipecat tail`](/api-reference/cli/tail)** - Monitor sessions in real-time with a terminal dashboard +**[`pipecat cloud`](/api-reference/cli/cloud/auth)** - Deploy and manage bots on Pipecat Cloud (requires `pipecatcloud`) -**[`pipecat cloud`](/api-reference/cli/cloud/auth)** - Deploy and manage bots on Pipecat Cloud +**[`pipecat tail`](/api-reference/cli/tail)** - Monitor sessions in real-time with a terminal dashboard (requires `pipecat-ai-tail`) ## Getting Help diff --git a/api-reference/cli/tail.mdx b/api-reference/cli/tail.mdx index ea56df05..df852d05 100644 --- a/api-reference/cli/tail.mdx +++ b/api-reference/cli/tail.mdx @@ -27,12 +27,18 @@ pipecat tail [OPTIONS] ## How to Use Tail -- Add `pipecat-ai-cli` to your project's dependencies. +- Install the `pipecat tail` command alongside the CLI: + + ```bash + uv tool install "pipecat-ai[cli]" --with pipecat-ai-tail + ``` + +- Add `pipecat-ai-tail` to your project's dependencies. - Update your Pipecat code to include the `TailObserver`: ```python - from pipecat_cli.tail import TailObserver + from pipecat_tail.observer import TailObserver task = PipelineWorker( pipeline, diff --git a/client/get-started/quickstart.mdx b/client/get-started/quickstart.mdx index 867fccb0..21c5339b 100644 --- a/client/get-started/quickstart.mdx +++ b/client/get-started/quickstart.mdx @@ -43,7 +43,7 @@ description: "Get a Pipecat voice app running in minutes with the CLI." ```bash # Install the Pipecat CLI -uv tool install pipecat-ai-cli +uv tool install "pipecat-ai[cli]" # Scaffold the quickstart project pipecat init diff --git a/pipecat-cloud/guides/personal-access-tokens.mdx b/pipecat-cloud/guides/personal-access-tokens.mdx index b7823bc7..a3ec824d 100644 --- a/pipecat-cloud/guides/personal-access-tokens.mdx +++ b/pipecat-cloud/guides/personal-access-tokens.mdx @@ -96,7 +96,7 @@ jobs: uses: astral-sh/setup-uv@v5 - name: Install CLI - run: uv tool install pipecatcloud + run: uv tool install "pipecat-ai[cli]" --with pipecatcloud - name: Deploy run: pipecat cloud deploy my-agent --yes @@ -119,7 +119,7 @@ deploy: script: - curl -LsSf https://astral.sh/uv/install.sh | sh - source $HOME/.local/bin/env - - uv tool install pipecatcloud + - uv tool install "pipecat-ai[cli]" --with pipecatcloud - pipecat cloud deploy my-agent --yes ``` diff --git a/pipecat-cloud/introduction.mdx b/pipecat-cloud/introduction.mdx index 4715f0a9..cb2df907 100644 --- a/pipecat-cloud/introduction.mdx +++ b/pipecat-cloud/introduction.mdx @@ -25,6 +25,12 @@ description: "Deploy your AI agents to production at scale" Write a Pipecat pipeline as you normally would, using any supported services. + + Install the Pipecat CLI with the Pipecat Cloud plugin: + ```bash + uv tool install "pipecat-ai[cli]" --with pipecatcloud + ``` + Use the CLI to build and deploy your agent image to Pipecat Cloud. ```bash diff --git a/pipecat/features/gemini-live.mdx b/pipecat/features/gemini-live.mdx index 4e32b6e7..19de93cb 100644 --- a/pipecat/features/gemini-live.mdx +++ b/pipecat/features/gemini-live.mdx @@ -52,7 +52,7 @@ The fastest way to start building is with the Pipecat CLI: ```bash # Install the CLI -uv tool install pipecat-ai-cli +uv tool install "pipecat-ai[cli]" # Create a new project pipecat init diff --git a/pipecat/get-started/build-your-next-bot.mdx b/pipecat/get-started/build-your-next-bot.mdx index 2b583fc8..9599eaa8 100644 --- a/pipecat/get-started/build-your-next-bot.mdx +++ b/pipecat/get-started/build-your-next-bot.mdx @@ -16,7 +16,7 @@ Ready to build your own bot? The Pipecat CLI scaffolds complete projects tailore Install the CLI globally with [uv](https://docs.astral.sh/uv/): ```bash -uv tool install pipecat-ai-cli +uv tool install "pipecat-ai[cli]" ``` Verify installation: diff --git a/pipecat/get-started/quickstart.mdx b/pipecat/get-started/quickstart.mdx index 709b44f6..f4582c5a 100644 --- a/pipecat/get-started/quickstart.mdx +++ b/pipecat/get-started/quickstart.mdx @@ -63,7 +63,7 @@ Have these API keys ready. You'll add them to your environment file in the next ```bash # Install the Pipecat CLI -uv tool install pipecat-ai-cli +uv tool install "pipecat-ai[cli]" # Scaffold the quickstart project pipecat init quickstart From b56f0b3c1e7887c21c56f21d4d0ab3f62faaba95 Mon Sep 17 00:00:00 2001 From: Mark Backman Date: Sat, 13 Jun 2026 15:42:42 -0400 Subject: [PATCH 2/5] docs: rename init->create scaffolder; document new agent-ready init PR #4710 (pipecat-ai 1.4.0) renames the scaffolder `pipecat init` -> `pipecat create` and repurposes `pipecat init` to make a project agent-ready (writes AGENTS.md/CLAUDE.md/GETTING_STARTED.md). Align the docs with that CLI: - New api-reference/cli/create.mdx carries the scaffolder reference (the former init.mdx content); init.mdx is rewritten for the new agent-ready command. docs.json nav adds create. - CLI overview lists both commands and points scaffold links at create. - Build Your Next Bot leads with the recommended agent flow (`pipecat init` -> coding session -> agent scaffolds via `pipecat create`), keeping the direct `pipecat create` path. - Sweep scaffolder invocations to `create` in quickstart, examples, gemini-live, cloud-builds, and the client quickstart. Builds on 04d011d (the pipecat-ai[cli] package move). Hold until 1.4.0. --- api-reference/cli/create.mdx | 328 ++++++++++++++++++++ api-reference/cli/init.mdx | 302 +++--------------- api-reference/cli/overview.mdx | 13 +- client/get-started/quickstart.mdx | 4 +- docs.json | 1 + pipecat-cloud/guides/cloud-builds.mdx | 2 +- pipecat/examples/overview.mdx | 2 +- pipecat/features/gemini-live.mdx | 2 +- pipecat/get-started/build-your-next-bot.mdx | 29 +- pipecat/get-started/quickstart.mdx | 2 +- 10 files changed, 409 insertions(+), 276 deletions(-) create mode 100644 api-reference/cli/create.mdx diff --git a/api-reference/cli/create.mdx b/api-reference/cli/create.mdx new file mode 100644 index 00000000..b9fea7fd --- /dev/null +++ b/api-reference/cli/create.mdx @@ -0,0 +1,328 @@ +--- +title: create +description: "Scaffold a new Pipecat project with an interactive wizard or CLI flags" +--- + +Create a new Pipecat project with guided setup for bot type, transport, AI services, and deployment options. Supports both an interactive wizard and a fully non-interactive mode for automation. + +**Usage:** + +```shell +pipecat create [OPTIONS] +``` + + + To make an existing project agent-ready (so an AI coding assistant follows + Pipecat conventions and can drive `pipecat create` for you), see + [`pipecat init`](/api-reference/cli/init). + + +**Options:** + + + Output directory where files will be saved. Defaults to current directory. + + + + Project name. Providing this flag triggers non-interactive mode. + + + + Bot type: `web` or `telephony`. + + + + Transport provider. Repeatable for multiple transports (e.g. `-t daily -t + smallwebrtc`). Valid values: `daily`, `smallwebrtc`, `twilio`, `telnyx`, + `plivo`, `exotel`, `daily_pstn`, `twilio_daily_sip`. + + + + Pipeline mode: `cascade` or `realtime`. + + + + Speech-to-Text service (cascade mode). e.g. `deepgram_stt`, `openai_stt`. + + + + Language model service (cascade mode). e.g. `openai_llm`, `anthropic_llm`. + + + + Text-to-Speech service (cascade mode). e.g. `cartesia_tts`, `elevenlabs_tts`. + + + + Realtime service (realtime mode). e.g. `openai_realtime`, + `gemini_live_realtime`. + + + + Video avatar service (web bots only). e.g. `heygen_video`, `tavus_video`, + `simli_video`. + + + + Client framework (web bots only): `react`, `vanilla`, or `none`. + + + + Client dev server (when using `--client-framework react`): `vite` or `nextjs`. + + + + Daily PSTN mode (required when transport is `daily_pstn`): `dial-in` or + `dial-out`. + + + + Twilio + Daily SIP mode (required when transport is `twilio_daily_sip`): + `dial-in` or `dial-out`. + + + + Enable audio recording. + + + + Enable transcription logging. + + + + Enable video input (web bots only). + + + + Enable video output (web bots only). + + + + Generate Pipecat Cloud deployment files (Dockerfile, pcc-deploy.toml). + + + + Enable Krisp noise cancellation (requires cloud deployment). + + + + Enable observability. + + + + Make the generated bot eval-ready: add an `eval` transport entry and starter + scenarios in `server/evals/`, plus the dependencies to run them. See the + evals docs for the verification workflow. + + + + Path to a JSON config file. Triggers non-interactive mode. CLI flags override + file values. + + + + Print the resolved configuration as JSON without generating any files. + + + + Print all available service options as JSON and exit. Useful for CI scripts + and coding agents that need to discover valid values at runtime. + + +## Quickstart Project + +To scaffold the canned quickstart project (sensible defaults, no prompts): + +```shell +pipecat create quickstart +``` + +## Interactive Setup + +When run without `--name` or `--config`, the CLI guides you through selecting: + +- **Bot type and client framework** - Phone, web (Next.js, Vite, Vanilla JS), or mobile +- **Transport provider** - Daily, Twilio, Telnyx, Plivo, Exotel +- **Pipeline mode** - Cascade or Realtime +- **AI services** - STT, LLM, and TTS providers +- **Optional features** - Additional capabilities for your bot +- **Deployment target** - Local development or Pipecat Cloud + +## Non-Interactive Mode + +When `--name` or `--config` is provided, all configuration is taken from CLI flags or a JSON config file with no interactive prompts. This is useful for automation, scripting, and coding agents. + +All required fields must be specified or the command exits with a list of all missing/invalid fields. + +## Examples + +### Interactive Wizard + +```shell +pipecat create +``` + +### Non-Interactive (Cascade) + +```shell +pipecat create --name my-bot --bot-type web --transport daily \ + --mode cascade --stt deepgram_stt --llm openai_llm --tts cartesia_tts +``` + +### Non-Interactive (Realtime) + +```shell +pipecat create --name rt-bot --bot-type web --transport smallwebrtc \ + --mode realtime --realtime openai_realtime +``` + +### Multiple Transports + +```shell +pipecat create --name my-bot --bot-type web \ + --transport daily --transport smallwebrtc \ + --mode cascade --stt deepgram_stt --llm openai_llm --tts cartesia_tts +``` + +### With React Client + +```shell +pipecat create --name my-bot --bot-type web --transport daily \ + --mode cascade --stt deepgram_stt --llm openai_llm --tts cartesia_tts \ + --client-framework react --client-server vite +``` + +### Telephony + +```shell +pipecat create --name call-bot --bot-type telephony --transport twilio \ + --mode cascade --stt deepgram_stt --llm openai_llm --tts cartesia_tts +``` + +### Eval-Ready Bot + +```shell +pipecat create --name my-bot --bot-type web --transport daily \ + --mode cascade --stt deepgram_stt --llm openai_llm --tts cartesia_tts \ + --eval +``` + +### Discover Available Options + +```shell +# List all valid service values as JSON +pipecat create --list-options +``` + +Output: + +```json +{ + "bot_type": ["web", "telephony"], + "transports": { + "web": ["daily", "smallwebrtc"], + "telephony": ["twilio", "twilio_daily_sip_dialin", "twilio_daily_sip_dialout", ...] + }, + "stt": ["deepgram_stt", "mistral_stt", "openai_stt", "xai_stt", ...], + "llm": ["openai_llm", "anthropic_llm", ...], + "tts": ["cartesia_tts", "elevenlabs_tts", "soniox_tts", ...], + "realtime": ["openai_realtime", "gemini_live_realtime", ...], + "video": ["heygen_video", "tavus_video", "simli_video"] +} +``` + +This is useful for scripting — for example, to pick a random TTS provider: + +```shell +options=$(pipecat create --list-options) +tts=$(echo "$options" | jq -r '.tts[0]') +``` + +### Dry Run + +```shell +# Preview resolved config as JSON without generating files +pipecat create --name my-bot --bot-type web --transport daily \ + --mode cascade --stt deepgram_stt --llm openai_llm --tts cartesia_tts \ + --dry-run +``` + +### From Config File + +```shell +pipecat create --config project-config.json +``` + +Sample `project-config.json`: + +```json +{ + "project_name": "my-bot", + "bot_type": "web", + "transports": ["daily"], + "mode": "cascade", + "stt_service": "deepgram_stt", + "llm_service": "openai_llm", + "tts_service": "cartesia_tts", + "recording": false, + "transcription": false, + "deploy_to_cloud": true, + "enable_krisp": false, + "enable_observability": false +} +``` + +CLI flags override any values in the file, so you can use a base config and customize per-run: + +```shell +pipecat create --config base-config.json --name custom-name --no-deploy-to-cloud +``` + +### Specify Output Directory + +```shell +pipecat create --output my-bot +``` + +## Generated Project Structure + +``` +mybot/ +├── server/ # Python bot server +│ ├── bot.py # Main bot implementation +│ ├── evals/ # Starter eval scenarios (with --eval) +│ ├── pyproject.toml # Python dependencies +│ ├── .env.example # Environment variables template +│ ├── Dockerfile # Container image (if cloud enabled) +│ └── pcc-deploy.toml # Deployment config (if cloud enabled) +├── client/ # Web client (if generated) +│ ├── src/ +│ ├── package.json +│ └── ... +├── .gitignore +└── README.md # Project setup instructions +``` diff --git a/api-reference/cli/init.mdx b/api-reference/cli/init.mdx index 7b68844a..267089de 100644 --- a/api-reference/cli/init.mdx +++ b/api-reference/cli/init.mdx @@ -1,299 +1,81 @@ --- title: init -description: "Scaffold a new Pipecat project with an interactive wizard or CLI flags" +description: "Make a project agent-ready by writing the Pipecat coding-agent guide" --- -Create a new Pipecat project with guided setup for bot type, transport, AI services, and deployment options. Supports both an interactive wizard and a fully non-interactive mode for automation. +Write the Pipecat coding-agent guide into a project so an AI coding assistant (Claude Code, Codex, …) follows Pipecat conventions automatically — then has it scaffold the app for you with [`pipecat create`](/api-reference/cli/create). -**Usage:** - -```shell -pipecat init [OPTIONS] -``` - -**Options:** - - - Output directory where files will be saved. Defaults to current directory. - - - - Project name. Providing this flag triggers non-interactive mode. - - - - Bot type: `web` or `telephony`. - - - - Transport provider. Repeatable for multiple transports (e.g. `-t daily -t - smallwebrtc`). Valid values: `daily`, `smallwebrtc`, `twilio`, `telnyx`, - `plivo`, `exotel`, `daily_pstn`, `twilio_daily_sip`. - - - - Pipeline mode: `cascade` or `realtime`. - - - - Speech-to-Text service (cascade mode). e.g. `deepgram_stt`, `openai_stt`. - - - - Language model service (cascade mode). e.g. `openai_llm`, `anthropic_llm`. - - - - Text-to-Speech service (cascade mode). e.g. `cartesia_tts`, `elevenlabs_tts`. - - - - Realtime service (realtime mode). e.g. `openai_realtime`, - `gemini_live_realtime`. - - - - Video avatar service (web bots only). e.g. `heygen_video`, `tavus_video`, - `simli_video`. - - - - Client framework (web bots only): `react`, `vanilla`, or `none`. - - - - Client dev server (when using `--client-framework react`): `vite` or `nextjs`. - - - - Daily PSTN mode (required when transport is `daily_pstn`): `dial-in` or - `dial-out`. - +`pipecat init` writes three files: - - Twilio + Daily SIP mode (required when transport is `twilio_daily_sip`): - `dial-in` or `dial-out`. - +- **`AGENTS.md`** — the agent-facing guide (how to build Pipecat apps: scaffold first, check APIs against live sources instead of stale training data, verify with the eval harness). Picked up automatically by coding agents. +- **`CLAUDE.md`** — a one-line import of `AGENTS.md` so Claude Code loads the guide. +- **`GETTING_STARTED.md`** — developer-facing guidance: how to set up the [Pipecat Context Hub](/pipecat/get-started/ai-tools), write an effective first prompt, and what to expect from a coding session. - - Enable audio recording. - + + `pipecat init` does **not** scaffold a project — it makes a project + agent-ready. To scaffold a runnable bot, use + [`pipecat create`](/api-reference/cli/create) (the recommended flow is to run + `pipecat init`, then let your coding agent drive `pipecat create`). + - - Enable transcription logging. - - - - Enable video input (web bots only). - - - - Enable video output (web bots only). - - - - Generate Pipecat Cloud deployment files (Dockerfile, pcc-deploy.toml). - +**Usage:** - - Enable Krisp noise cancellation (requires cloud deployment). - +```shell +pipecat init [TARGET_DIR] [OPTIONS] +``` - - Enable observability. - +**Arguments:** - - Path to a JSON config file. Triggers non-interactive mode. CLI flags override - file values. + + Directory to make agent-ready. `pipecat init my-bot` targets `./my-bot`; + `pipecat init .` targets the current directory. With no argument, the CLI + prompts for a directory. - - Print the resolved configuration as JSON without generating any files. - +**Options:** - - Print all available service options as JSON and exit. Useful for CI scripts - and coding agents that need to discover valid values at runtime. + + Overwrite an existing `CLAUDE.md`. By default `CLAUDE.md` is written only when + absent, so a developer's own file is never clobbered. -## Interactive Setup - -When run without `--name` or `--config`, the CLI guides you through selecting: - -- **Bot type and client framework** - Phone, web (Next.js, Vite, Vanilla JS), or mobile -- **Transport provider** - Daily, Twilio, Telnyx, Plivo, Exotel -- **Pipeline mode** - Cascade or Realtime -- **AI services** - STT, LLM, and TTS providers -- **Optional features** - Additional capabilities for your bot -- **Deployment target** - Local development or Pipecat Cloud - -## Non-Interactive Mode - -When `--name` or `--config` is provided, all configuration is taken from CLI flags or a JSON config file with no interactive prompts. This is useful for automation, scripting, and coding agents. +## Behavior -All required fields must be specified or the command exits with a list of all missing/invalid fields. +- **`AGENTS.md` and `GETTING_STARTED.md` are always (re)written**, so re-running `pipecat init` refreshes the guide after a Pipecat upgrade. +- **`CLAUDE.md` is preserved if it already exists** — pass `--force` to overwrite it. +- 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. ## Examples -### Interactive Wizard +### Prompt for a directory ```shell pipecat init ``` -### Non-Interactive (Cascade) +### Make a specific directory agent-ready ```shell -pipecat init --name my-bot --bot-type web --transport daily \ - --mode cascade --stt deepgram_stt --llm openai_llm --tts cartesia_tts +pipecat init my-bot ``` -### Non-Interactive (Realtime) +### Make the current directory agent-ready ```shell -pipecat init --name rt-bot --bot-type web --transport smallwebrtc \ - --mode realtime --realtime openai_realtime +pipecat init . ``` -### Multiple Transports +### Refresh the guide, overwriting CLAUDE.md ```shell -pipecat init --name my-bot --bot-type web \ - --transport daily --transport smallwebrtc \ - --mode cascade --stt deepgram_stt --llm openai_llm --tts cartesia_tts +pipecat init my-bot --force ``` -### With React Client +## Next Steps -```shell -pipecat init --name my-bot --bot-type web --transport daily \ - --mode cascade --stt deepgram_stt --llm openai_llm --tts cartesia_tts \ - --client-framework react --client-server vite -``` - -### Telephony - -```shell -pipecat init --name call-bot --bot-type telephony --transport twilio \ - --mode cascade --stt deepgram_stt --llm openai_llm --tts cartesia_tts -``` - -### Discover Available Options - -```shell -# List all valid service values as JSON -pipecat init --list-options -``` - -Output: - -```json -{ - "bot_type": ["web", "telephony"], - "transports": { - "web": ["daily", "smallwebrtc"], - "telephony": ["twilio", "twilio_daily_sip_dialin", "twilio_daily_sip_dialout", ...] - }, - "stt": ["deepgram_stt", "mistral_stt", "openai_stt", "xai_stt", ...], - "llm": ["openai_llm", "anthropic_llm", ...], - "tts": ["cartesia_tts", "elevenlabs_tts", "soniox_tts", ...], - "realtime": ["openai_realtime", "gemini_live_realtime", ...], - "video": ["heygen_video", "tavus_video", "simli_video"] -} -``` - -This is useful for scripting — for example, to pick a random TTS provider: - -```shell -options=$(pipecat init --list-options) -tts=$(echo "$options" | jq -r '.tts[0]') -``` +Open the project in your coding tool and let the agent take it from here — it reads `AGENTS.md` and scaffolds the app with `pipecat create`. -### Dry Run - -```shell -# Preview resolved config as JSON without generating files -pipecat init --name my-bot --bot-type web --transport daily \ - --mode cascade --stt deepgram_stt --llm openai_llm --tts cartesia_tts \ - --dry-run -``` - -### From Config File - -```shell -pipecat init --config project-config.json -``` - -Sample `project-config.json`: - -```json -{ - "project_name": "my-bot", - "bot_type": "web", - "transports": ["daily"], - "mode": "cascade", - "stt_service": "deepgram_stt", - "llm_service": "openai_llm", - "tts_service": "cartesia_tts", - "recording": false, - "transcription": false, - "deploy_to_cloud": true, - "enable_krisp": false, - "enable_observability": false -} -``` - -CLI flags override any values in the file, so you can use a base config and customize per-run: - -```shell -pipecat init --config base-config.json --name custom-name --no-deploy-to-cloud -``` - -### Specify Output Directory - -```shell -pipecat init --output my-bot -``` - -## Generated Project Structure - -``` -mybot/ -├── server/ # Python bot server -│ ├── bot.py # Main bot implementation -│ ├── pyproject.toml # Python dependencies -│ ├── .env.example # Environment variables template -│ ├── Dockerfile # Container image (if cloud enabled) -│ └── pcc-deploy.toml # Deployment config (if cloud enabled) -├── client/ # Web client (if generated) -│ ├── src/ -│ ├── package.json -│ └── ... -├── .gitignore -└── README.md # Project setup instructions -``` + + Scaffold a runnable bot — services, pipeline, and deploy path wired up + diff --git a/api-reference/cli/overview.mdx b/api-reference/cli/overview.mdx index 4f1251bc..a901e66f 100644 --- a/api-reference/cli/overview.mdx +++ b/api-reference/cli/overview.mdx @@ -7,7 +7,7 @@ description: "Command-line tool for scaffolding, deploying, and monitoring Pipec Create new phone or web/mobile bots with interactive setup @@ -47,7 +47,7 @@ pipecat --version All commands can use either `pipecat` or the shorter `pc` alias. -This gives you `pipecat init`. The `cloud` and `tail` commands are provided by separate packages that you co-install with `--with`: +This gives you `pipecat create` and `pipecat init`. The `cloud` and `tail` commands are provided by separate packages that you co-install with `--with`: ```bash # Add deploy + monitor commands @@ -56,7 +56,9 @@ uv tool install "pipecat-ai[cli]" --with pipecatcloud --with pipecat-ai-tail ## Commands -**[`pipecat init`](/api-reference/cli/init)** - Scaffold new projects with interactive setup (built in) +**[`pipecat create`](/api-reference/cli/create)** - Scaffold new projects with interactive setup (built in) + +**[`pipecat init`](/api-reference/cli/init)** - Make a project agent-ready by writing the Pipecat coding-agent guide (built in) **[`pipecat cloud`](/api-reference/cli/cloud/auth)** - Deploy and manage bots on Pipecat Cloud (requires `pipecatcloud`) @@ -68,6 +70,7 @@ View help for any command: ```bash pipecat --help +pipecat create --help pipecat init --help pipecat tail --help pipecat cloud --help @@ -78,7 +81,7 @@ pipecat cloud --help - Scaffold a new project with pipecat init + Scaffold a new project with pipecat create diff --git a/client/get-started/quickstart.mdx b/client/get-started/quickstart.mdx index 21c5339b..d71b9540 100644 --- a/client/get-started/quickstart.mdx +++ b/client/get-started/quickstart.mdx @@ -45,8 +45,8 @@ description: "Get a Pipecat voice app running in minutes with the CLI." # Install the Pipecat CLI uv tool install "pipecat-ai[cli]" -# Scaffold the quickstart project -pipecat init +# Scaffold your project +pipecat create ``` The CLI will guide you through the setup. Choose the following options: diff --git a/docs.json b/docs.json index 79af2cf1..8ce331d2 100644 --- a/docs.json +++ b/docs.json @@ -815,6 +815,7 @@ { "group": "Commands", "pages": [ + "api-reference/cli/create", "api-reference/cli/init", "api-reference/cli/tail", { diff --git a/pipecat-cloud/guides/cloud-builds.mdx b/pipecat-cloud/guides/cloud-builds.mdx index a8439125..dd6abb03 100644 --- a/pipecat-cloud/guides/cloud-builds.mdx +++ b/pipecat-cloud/guides/cloud-builds.mdx @@ -33,7 +33,7 @@ The CLI will: ## Dockerfile requirement -Your project must include a `Dockerfile`. If you don't have one, use `pipecat init` to scaffold a new project with a Dockerfile included. +Your project must include a `Dockerfile`. If you don't have one, use `pipecat create` to scaffold a new project with a Dockerfile included. ## How it works diff --git a/pipecat/examples/overview.mdx b/pipecat/examples/overview.mdx index b546e709..17059d9c 100644 --- a/pipecat/examples/overview.mdx +++ b/pipecat/examples/overview.mdx @@ -7,7 +7,7 @@ description: "Complete applications and quickstart demos to accelerate your Pipe Quickstart} tags={["Getting Started"]}> -Get started with a basic voice bot using `pipecat init quickstart`. +Get started with a basic voice bot using `pipecat create quickstart`. [View Quickstart Guide →](/pipecat/get-started/quickstart) diff --git a/pipecat/features/gemini-live.mdx b/pipecat/features/gemini-live.mdx index 19de93cb..c977e726 100644 --- a/pipecat/features/gemini-live.mdx +++ b/pipecat/features/gemini-live.mdx @@ -55,7 +55,7 @@ The fastest way to start building is with the Pipecat CLI: uv tool install "pipecat-ai[cli]" # Create a new project -pipecat init +pipecat create ``` The CLI will guide you through selecting: diff --git a/pipecat/get-started/build-your-next-bot.mdx b/pipecat/get-started/build-your-next-bot.mdx index 9599eaa8..22e0a668 100644 --- a/pipecat/get-started/build-your-next-bot.mdx +++ b/pipecat/get-started/build-your-next-bot.mdx @@ -25,23 +25,42 @@ Verify installation: pipecat --version ``` -## Create Your Project +## Build with an AI coding agent (recommended) -Run the interactive setup wizard: +If you're using an AI coding assistant (Claude Code, Codex, …), make your project agent-ready first, then let the agent do the building: ```bash pipecat init ``` -The CLI will guide you through selecting your platform (phone or web/mobile), transport provider, AI services (STT, LLM, TTS), and deployment target. +`pipecat init` writes a Pipecat coding-agent guide (`AGENTS.md` + `CLAUDE.md`) and developer guidance (`GETTING_STARTED.md`) into the project. Open a coding session there and the agent picks up the guide automatically — it follows Pipecat conventions, scaffolds the app for you with `pipecat create`, and verifies its own work with the eval harness. - + + + What `init` writes and how the agent flow works + + + Set up the Pipecat Context Hub so your agent has live, accurate context + + + +## Scaffold it yourself + +Prefer to drive the CLI directly? Run the interactive setup wizard: + +```bash +pipecat create +``` + +The CLI will guide you through selecting your platform (phone or web/mobile), transport provider, AI services (STT, LLM, TTS), and deployment target. To skip the prompts and scaffold the canned quickstart project, run `pipecat create quickstart`. + + See detailed options and generated project structure ## Next Steps -Once `pipecat init` completes, the CLI will provide specific instructions for your generated project, including: +Once `pipecat create` completes, the CLI will provide specific instructions for your generated project, including: - How to configure your API keys - Installing dependencies diff --git a/pipecat/get-started/quickstart.mdx b/pipecat/get-started/quickstart.mdx index f4582c5a..7e4f7fa3 100644 --- a/pipecat/get-started/quickstart.mdx +++ b/pipecat/get-started/quickstart.mdx @@ -66,7 +66,7 @@ Have these API keys ready. You'll add them to your environment file in the next uv tool install "pipecat-ai[cli]" # Scaffold the quickstart project -pipecat init quickstart +pipecat create quickstart # Change to the project directory cd pipecat-quickstart From 470709f88101a661f1b07e4aa8338f4825e22bb8 Mon Sep 17 00:00:00 2001 From: Mark Backman Date: Sat, 13 Jun 2026 15:46:42 -0400 Subject: [PATCH 3/5] Remove tail CLI --- api-reference/cli/tail.mdx | 57 -------------------------------------- docs.json | 5 ---- 2 files changed, 62 deletions(-) delete mode 100644 api-reference/cli/tail.mdx diff --git a/api-reference/cli/tail.mdx b/api-reference/cli/tail.mdx deleted file mode 100644 index df852d05..00000000 --- a/api-reference/cli/tail.mdx +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: tail -description: "A terminal dashboard for monitoring Pipecat sessions in real-time" ---- - -**Tail** is a terminal dashboard for monitoring your Pipecat sessions in real-time with logs, conversations, metrics, and audio levels all in one place. - -With Tail you can: - -- 📜 Follow system logs in real time -- 💬 Track conversations as they happen -- 🔊 Monitor user and agent audio levels -- 📈 Keep an eye on service metrics and usage -- 🖥️ Run locally as a pipeline runner or connect to a remote session - -**Usage:** - -```shell -pipecat tail [OPTIONS] -``` - -**Options:** - - - WebSocket URL to connect to. Defaults to `ws://localhost:9292`. - - -## How to Use Tail - -- Install the `pipecat tail` command alongside the CLI: - - ```bash - uv tool install "pipecat-ai[cli]" --with pipecat-ai-tail - ``` - -- Add `pipecat-ai-tail` to your project's dependencies. - -- Update your Pipecat code to include the `TailObserver`: - - ```python - from pipecat_tail.observer import TailObserver - - task = PipelineWorker( - pipeline, - observers=[TailObserver()] - ) - ``` - -- Start the Tail app separately: - - ```bash - # Connect to local session (default) - pipecat tail - - # Connect to remote session - pipecat tail --url wss://my-bot.example.com - ``` diff --git a/docs.json b/docs.json index 8ce331d2..5c4c2500 100644 --- a/docs.json +++ b/docs.json @@ -817,7 +817,6 @@ "pages": [ "api-reference/cli/create", "api-reference/cli/init", - "api-reference/cli/tail", { "group": "cloud", "pages": [ @@ -2308,10 +2307,6 @@ "source": "/cli/init", "destination": "/api-reference/cli/init" }, - { - "source": "/cli/tail", - "destination": "/api-reference/cli/tail" - }, { "source": "/cli/cloud/agent", "destination": "/api-reference/cli/cloud/agent" From 5155ec2a4fe68111bdb0e5a89eb475a568d0bfc1 Mon Sep 17 00:00:00 2001 From: Mark Backman Date: Sat, 13 Jun 2026 15:51:16 -0400 Subject: [PATCH 4/5] docs(ai-tools): add pipecat init agent-ready flow; disambiguate CLAUDE.md The AI-Assisted Development page covered the Context Hub but never mentioned `pipecat init`. Add a lead section: run `pipecat init` to make a project agent-ready (writes AGENTS.md/CLAUDE.md/GETTING_STARTED.md), pairing with the Context Hub for live context, and link Build Your Next Bot. Clarify that the existing CLAUDE.md section is the framework repo's own file, distinct from the one init writes into your project. --- pipecat/get-started/ai-tools.mdx | 25 ++++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/pipecat/get-started/ai-tools.mdx b/pipecat/get-started/ai-tools.mdx index a3994450..dfe2b0e9 100644 --- a/pipecat/get-started/ai-tools.mdx +++ b/pipecat/get-started/ai-tools.mdx @@ -3,7 +3,26 @@ title: "AI-Assisted Development" description: "Use AI coding tools with Pipecat documentation and source code." --- -Pipecat offers several ways to give AI coding tools access to documentation and source code context, helping you build voice and multimodal applications faster. +Pipecat offers several ways to set up AI coding tools and feed them accurate, up-to-date context, helping you build voice and multimodal applications faster. + +## Make your project agent-ready (`pipecat init`) + +If you're building with an AI coding assistant, run `pipecat init` in your project first: + +```bash +uv tool install "pipecat-ai[cli]" +pipecat init +``` + +This writes a Pipecat coding-agent guide (`AGENTS.md` + `CLAUDE.md`) and developer guidance (`GETTING_STARTED.md`) into the project. Your agent picks up `AGENTS.md` automatically — it follows Pipecat conventions and scaffolds the app for you with `pipecat create`. Pair it with the Pipecat Context Hub below so the agent works from live API context instead of stale training data. + + + The full agent-driven workflow, start to finish + ## Pipecat Context Hub (MCP Server) @@ -82,9 +101,9 @@ Each command prints the tool's JSON to stdout. The package name is `pipecat-ai-c See the [repo docs](https://github.com/pipecat-ai/pipecat-context-hub) for additional configuration options, including pinning to a specific Pipecat version. -## CLAUDE.md +## CLAUDE.md in the framework repo -The Pipecat repository includes a [`CLAUDE.md`](https://github.com/pipecat-ai/pipecat/blob/main/CLAUDE.md) file that provides Claude Code with architecture guidance, coding conventions, and development patterns specific to the Pipecat codebase. When you work in a cloned copy of the Pipecat repo, Claude Code automatically reads this file for context. +Separate from the project guide `pipecat init` writes, the [Pipecat framework repository](https://github.com/pipecat-ai/pipecat) ships its own [`CLAUDE.md`](https://github.com/pipecat-ai/pipecat/blob/main/CLAUDE.md) with architecture guidance, coding conventions, and development patterns for the framework codebase itself. When you work in a cloned copy of the Pipecat repo — for example, contributing to the framework — Claude Code reads it automatically. ## Markdown docs From b42ea1620380ab8fad55f3e6e89f9f2012b48822 Mon Sep 17 00:00:00 2001 From: Mark Backman Date: Sat, 13 Jun 2026 15:53:38 -0400 Subject: [PATCH 5/5] docs(cli): drop pipecat tail references from CLI overview main removed the `pipecat tail` subcommand (page + nav); the rebase replayed this branch's overview edits, which still referenced it. Remove the Monitor card, the tail co-install, command entry, and --help line so the overview matches the shipped CLI and has no dead links. --- api-reference/cli/overview.mdx | 20 +++++--------------- 1 file changed, 5 insertions(+), 15 deletions(-) diff --git a/api-reference/cli/overview.mdx b/api-reference/cli/overview.mdx index a901e66f..cb753e53 100644 --- a/api-reference/cli/overview.mdx +++ b/api-reference/cli/overview.mdx @@ -1,9 +1,9 @@ --- title: "CLI Overview" -description: "Command-line tool for scaffolding, deploying, and monitoring Pipecat bots" +description: "Command-line tool for scaffolding and deploying Pipecat bots" --- - + Push your bots to production with one command - - Watch real-time logs, conversations, and metrics - ## Requirements @@ -47,11 +40,11 @@ pipecat --version All commands can use either `pipecat` or the shorter `pc` alias. -This gives you `pipecat create` and `pipecat init`. The `cloud` and `tail` commands are provided by separate packages that you co-install with `--with`: +This gives you `pipecat create` and `pipecat init`. The `cloud` command is provided by a separate package that you co-install with `--with`: ```bash -# Add deploy + monitor commands -uv tool install "pipecat-ai[cli]" --with pipecatcloud --with pipecat-ai-tail +# Add deploy commands +uv tool install "pipecat-ai[cli]" --with pipecatcloud ``` ## Commands @@ -62,8 +55,6 @@ uv tool install "pipecat-ai[cli]" --with pipecatcloud --with pipecat-ai-tail **[`pipecat cloud`](/api-reference/cli/cloud/auth)** - Deploy and manage bots on Pipecat Cloud (requires `pipecatcloud`) -**[`pipecat tail`](/api-reference/cli/tail)** - Monitor sessions in real-time with a terminal dashboard (requires `pipecat-ai-tail`) - ## Getting Help View help for any command: @@ -72,7 +63,6 @@ View help for any command: pipecat --help pipecat create --help pipecat init --help -pipecat tail --help pipecat cloud --help ```