init - Pipecat

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.

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

​Behavior

​Scaffolding a Bot

​Interactive

​Non-Interactive

​Quickstart Preset

​Examples

​Initialize for a coding agent

​Scaffold in place, non-interactively

​Realtime bot

​Multiple transports

​With a React client

​Telephony

​Eval-ready bot

​Refresh the guide files

​Scaffold the quickstart project

​Discover available options

​Dry run

​From a config file

​Generated Project Structure

​Next Steps

Build Your Next Bot

Behavior

Scaffolding a Bot

Interactive

Non-Interactive

Quickstart Preset

Examples

Initialize for a coding agent

Scaffold in place, non-interactively

Realtime bot

Multiple transports

With a React client

Telephony

Eval-ready bot

Refresh the guide files

Scaffold the quickstart project

Discover available options

Dry run

From a config file

Generated Project Structure

Next Steps