pipecat init

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:

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:

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.

string

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

string

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

string

Transport provider. Repeatable for multiple transports (e.g. -t daily -t smallwebrtc). Valid values: daily, livekit, smallwebrtc, twilio, telnyx, plivo, exotel, daily_pstn, twilio_daily_sip.

string

Pipeline mode: cascade or realtime.

string

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

string

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

string

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

string

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

string

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

string

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

string

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

string

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

string

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

boolean

default:"false"

Enable audio recording.

boolean

default:"false"

Enable transcription logging.

boolean

default:"false"

Enable video input (web bots only).

boolean

default:"false"

Enable video output (web bots only).

boolean

default:"true"

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

boolean

default:"false"

Enable Krisp noise cancellation (requires cloud deployment).

boolean

default:"false"

Enable observability.

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.

string

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

boolean

default:"false"

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

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.

boolean

default:"true"

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 — it registers with every coding agent CLI it detects (Claude Code, Codex), a client that rejects the registration reports why, and if it finds no agent CLI at all it points you at pipecat context-hub install to print the config block for the editors configured by hand (Cursor, VS Code, Zed). 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. A non-interactive run registers but never builds — it prints the refresh command instead. Three paths skip setup, since none of them writes the agent-guide start-here: pipecat init quickstart, to stay a short path to a running bot; scaffolding a bot from flags or --config; and choosing “Scaffold a runnable bot now” in the interactive prompt. In each case the generated README carries the instructions instead. If you scaffolded that way — the route a coding agent takes — run pipecat context-hub install to wire the hub up.

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", "livekit", "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/
│   │   ├── components/
│   │   │   ├── pipecat/   # Pipecat UI components (React only)
│   │   │   └── ui/        # Base UI components (React only)
│   │   └── ...
│   ├── components.json     # shadcn config (React only)
│   ├── package.json
│   └── ...
├── .gitignore
└── README.md               # Project setup instructions

React Client Components

When using --client-framework react, the generated client uses Pipecat UI components installed as source. The client renders the Console block (connect flow, transcript, metrics, device and session info, live event stream) with your project’s transport picker. Components live under src/components/pipecat/ and can be customized directly. The generated components.json configures the @pipecat shadcn registry, so you can add more components:

npx shadcn@latest add @pipecat/user-audio-control @pipecat/conversation

The vanilla JavaScript client (--client-framework vanilla) uses plain JavaScript and CSS styled to match the Console theme. 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

Get Started

Standards

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

Context Hub setup

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

React Client Components

Next Steps

Build Your Next Bot