init

Initialize and scaffold a new Pipecat project

pipecat init initializes a new Pipecat app. It’s the single entry point for building with Pipecat.

It 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, the coding-agent files AGENTS.md and CLAUDE.md are provided so your favorite coding agent works well with Pipecat.

Usage:

pipecat init [TARGET_DIR] [OPTIONS]

Arguments:

TARGET_DIR · string

Directory to initialize. pipecat init my-bot targets ./my-bot; pipecat init . targets the current directory. With no argument and no scaffold options, the CLI prompts for a directory. When scaffold options are present, the bot is generated in-place in this directory (the project name is derived from it); a missing TARGET_DIR then defaults to the current directory. The special value quickstart (pipecat init quickstart) scaffolds the canned quickstart bot into ./pipecat-quickstart (see Quickstart Preset).

Guide options:

--overwrite-guide · boolean · default: "false"

Overwrite existing AGENTS.md, CLAUDE.md, and GETTING_STARTED.md files. By default existing guide files are kept, so your edits are never clobbered.

Scaffold options: Passing any of these (or --config) scaffolds a bot non-interactively, in-place in TARGET_DIR.

--name / -n · string

Project name. Defaults to the target directory name; pass this to override it.

--bot-type / -b · string

Bot type: web or telephony. Optional — inferred from --transport when omitted (telephony if any transport is a telephony provider, otherwise web).

--transport / -t · string

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.

--mode / -m · string

Pipeline mode: cascade or realtime.

--stt · string

Speech-to-Text service (cascade mode). e.g. deepgram_stt, openai_stt.

--llm · string

Language model service (cascade mode). e.g. openai_llm, anthropic_llm.

--tts · string

Text-to-Speech service (cascade mode). e.g. cartesia_tts, elevenlabs_tts.

--realtime · string

Realtime service (realtime mode). e.g. openai_realtime, gemini_live_realtime.

--video · string

Video avatar service (web bots only). e.g. heygen_video, tavus_video, simli_video.

--client-framework · string

Client framework (web bots only): react, vanilla, or none.

--client-server · string

Client dev server (when using --client-framework react): vite or nextjs.

--daily-pstn-mode · string

Daily PSTN mode (required when transport is daily_pstn): dial-in or dial-out.

--twilio-daily-sip-mode · string

Twilio + Daily SIP mode (required when transport is twilio_daily_sip): dial-in or dial-out.

--recording / --no-recording · boolean · default: "false"

Enable audio recording.

--transcription / --no-transcription · boolean · default: "false"

Enable transcription logging.

--video-input / --no-video-input · boolean · default: "false"

Enable video input (web bots only).

--video-output / --no-video-output · boolean · default: "false"

Enable video output (web bots only).

--deploy-to-cloud / --no-deploy-to-cloud · boolean · default: "true"

Generate Pipecat Cloud deployment files (Dockerfile, pcc-deploy.toml).

--enable-krisp / --no-enable-krisp · boolean · default: "false"

Enable Krisp noise cancellation (requires cloud deployment).

--observability / --no-observability · boolean · default: "false"

Enable observability.

--eval / --no-eval · boolean · default: "false"

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.

--config / -c · string

Path to a JSON config file. Triggers non-interactive scaffolding. CLI flags override file values.

--dry-run · boolean · default: "false"

Print the resolved scaffold configuration as JSON without writing any files.

--list-options · boolean · default: "false"

Print all available service options as JSON and exit. Useful for CI scripts and coding agents that need to discover valid values at runtime.

--context-hub / --no-context-hub · boolean · default: "true"

Register the Pipecat Context Hub MCP server with your coding agents, and offer to build its index.

Context Hub setup

On the coding-agent path, init sets up the Context Hub — the guides it writes tell your agent to query the hub, so it makes sure the hub is there to query.

Registration runs without asking: it’s instant, idempotent, and needs doing per project, since Claude Code stores MCP servers per project. init reports what came of it — editors configured by hand (Cursor, VS Code, Zed) are pointed at pipecat context-hub install to print the config block to paste, and a client that rejects the registration reports why.

Building the index is the only prompt, and only appears when no index exists yet. It takes upwards of three minutes and about 900 MB of disk, so init asks rather than assuming. The index is shared across every project on the machine, so once it exists the question doesn’t return.

pipecat init quickstart skips this entirely, to stay a short path to a running bot.

Behavior

• Existing guide files are kept. Re-running pipecat init never overwrites an existing AGENTS.md, CLAUDE.md, or GETTING_STARTED.md, so your edits are safe. If a guide was written by an older Pipecat version, an interactive run offers to refresh it on the spot; a non-interactive run prints how.
• --overwrite-guide refreshes them, overwriting the existing guide files with the current templates (for example, after upgrading Pipecat).
• GETTING_STARTED.md is written on the coding-agent path only, not when scaffolding a bot.

Scaffolding a Bot

pipecat init scaffolds a complete project — bot.py, dependencies, config, and an optional client — in-place in the target directory, so the coding-agent guide and a runnable bot live together.

Interactive

With no scaffold options, an interactive pipecat init asks whether to build with a coding agent or scaffold a bot now. Choosing to scaffold runs a wizard for bot type, transport, AI services, and deployment options.

Non-Interactive

Passing any scaffold option (or --config) skips the prompts and builds the project from your flags and/or a config file — the path coding agents and automation use. The typical agent loop is:

# 1. A developer initializes the project (writes the coding-agent guide):
pipecat init my-bot

# 2. They open ./my-bot in a coding agent and describe the bot they want.
# 3. The agent scaffolds it in place, mapping the requirements to flags:
pipecat init . --bot-type web --transport daily --mode cascade \
  --stt deepgram_stt --llm openai_llm --tts cartesia_tts --eval

All required fields must be specified or the command exits with a list of all missing/invalid fields. Bot type is not required — it’s inferred from --transport when omitted. Run pipecat init --list-options to discover valid service and transport values.

Quickstart Preset

pipecat init quickstart

Scaffolds the canned quickstart bot (SmallWebRTC + Daily, Deepgram, OpenAI, Cartesia) into ./pipecat-quickstart and writes AGENTS.md + CLAUDE.md there (the generated README carries the Context Hub setup). It’s the fastest way to a running project that your coding agent can work with.

Examples

Initialize for a coding agent

pipecat init my-bot

Scaffold in place, non-interactively

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

Scaffolds into the current directory, deriving the project name from it. Bot type is inferred from the transport (web here), so --bot-type is optional.

Realtime bot

pipecat init rt-bot --bot-type web --transport smallwebrtc \
  --mode realtime --realtime openai_realtime

Multiple transports

pipecat init my-bot --bot-type web \
  --transport daily --transport smallwebrtc \
  --mode cascade --stt deepgram_stt --llm openai_llm --tts cartesia_tts

With a React client

pipecat init 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

pipecat init call-bot --bot-type telephony --transport twilio \
  --mode cascade --stt deepgram_stt --llm openai_llm --tts cartesia_tts

Eval-ready bot

pipecat init my-bot --bot-type web --transport daily \
  --mode cascade --stt deepgram_stt --llm openai_llm --tts cartesia_tts \
  --eval

Refresh the guide files

pipecat init my-bot --overwrite-guide

Scaffold the quickstart project

pipecat init quickstart

Discover available options

pipecat init --list-options

Output:

{
  "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 TTS provider:

options=$(pipecat init --list-options)
tts=$(echo "$options" | jq -r '.tts[0]')

Dry run

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

Prints the resolved configuration as JSON and writes nothing.

From a config file

pipecat init my-bot --config project-config.json

Sample project-config.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:

pipecat init my-bot --config base-config.json --name custom-name --no-deploy-to-cloud

Generated Project Structure

my-bot/
├── AGENTS.md               # Coding-agent guide
├── CLAUDE.md               # @AGENTS.md import for Claude Code
├── 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

The generated README.md includes a “Building with an AI coding agent” section with Pipecat Context Hub setup, so a scaffolded project is ready to extend with Claude Code or Codex.

Next Steps

Build Your Next Bot

The full flow: initialize a project, then build with a coding agent or scaffold a bot