init

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:

pipecat init [TARGET] [OPTIONS]

Arguments:

TARGET · string

Optional target directory. Use . to scaffold into the current directory without creating a <name> subfolder (same convention as npm create vite@latest .). When provided, the project name defaults to the directory’s basename unless overridden with --name. Omit this argument to create a <name> subfolder (legacy behavior).

Options:

--output / -o · string

Output directory where files will be saved. Defaults to current directory. Creates a <name> subfolder within this directory. Mutually exclusive with TARGET.

--name / -n · string

Project name. Providing this flag triggers non-interactive mode.

--bot-type / -b · string

Bot type: web or telephony.

--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.

--config / -c · string

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

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

Print the resolved configuration as JSON without generating 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.

Interactive Setup

When run without --name or --config, the CLI guides you through selecting:

• Project name - Defaults to the target directory’s basename if a TARGET was provided (e.g., pc init . uses the current directory name)
• 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

pipecat init

Scaffold Into Current Directory

# In-place mode: scaffolds into `.` without creating a subfolder
# Project name is derived from the directory name
pipecat init .

Non-Interactive (Cascade)

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

In-Place With Custom Options

# Combine in-place scaffolding with non-interactive flags
# Project name still derived from directory unless --name is provided
pipecat init . --bot-type web --transport daily \
  --mode cascade --stt deepgram_stt --llm openai_llm --tts cartesia_tts

Non-Interactive (Realtime)

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

Multiple Transports

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

With React Client

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

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

Discover Available Options

# List all valid service values as JSON
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 random TTS provider:

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

Dry Run

# 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

pipecat init --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 --config base-config.json --name custom-name --no-deploy-to-cloud

Specify Output Directory

pipecat init --output my-bot

Generated Project Structure

When scaffolding with a project name (default behavior):

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

When using in-place mode (pc init .), the files are created directly in the target directory without a project name subfolder:

./
├── 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