> ## Documentation Index
> Fetch the complete documentation index at: https://daily-docs-source-analytics-user-turn-strategies.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:**

```shell theme={null}
pipecat init [TARGET_DIR] [OPTIONS]
```

**Arguments:**

<ParamField path="TARGET_DIR" type="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](#quickstart-preset)).
</ParamField>

**Guide options:**

<ParamField path="--overwrite-guide" type="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.
</ParamField>

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

<ParamField path="--name / -n" type="string">
  Project name. Defaults to the target directory name; pass this to override it.
</ParamField>

<ParamField path="--bot-type / -b" type="string">
  Bot type: `web` or `telephony`. Optional — inferred from `--transport` when
  omitted (telephony if any transport is a telephony provider, otherwise web).
</ParamField>

<ParamField path="--transport / -t" type="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`.
</ParamField>

<ParamField path="--mode / -m" type="string">
  Pipeline mode: `cascade` or `realtime`.
</ParamField>

<ParamField path="--stt" type="string">
  Speech-to-Text service (cascade mode). e.g. `deepgram_stt`, `openai_stt`.
</ParamField>

<ParamField path="--llm" type="string">
  Language model service (cascade mode). e.g. `openai_llm`, `anthropic_llm`.
</ParamField>

<ParamField path="--tts" type="string">
  Text-to-Speech service (cascade mode). e.g. `cartesia_tts`, `elevenlabs_tts`.
</ParamField>

<ParamField path="--realtime" type="string">
  Realtime service (realtime mode). e.g. `openai_realtime`,
  `gemini_live_realtime`.
</ParamField>

<ParamField path="--video" type="string">
  Video avatar service (web bots only). e.g. `heygen_video`, `tavus_video`,
  `simli_video`.
</ParamField>

<ParamField path="--client-framework" type="string">
  Client framework (web bots only): `react`, `vanilla`, or `none`.
</ParamField>

<ParamField path="--client-server" type="string">
  Client dev server (when using `--client-framework react`): `vite` or `nextjs`.
</ParamField>

<ParamField path="--daily-pstn-mode" type="string">
  Daily PSTN mode (required when transport is `daily_pstn`): `dial-in` or
  `dial-out`.
</ParamField>

<ParamField path="--twilio-daily-sip-mode" type="string">
  Twilio + Daily SIP mode (required when transport is `twilio_daily_sip`):
  `dial-in` or `dial-out`.
</ParamField>

<ParamField path="--recording / --no-recording" type="boolean" default="false">
  Enable audio recording.
</ParamField>

<ParamField path="--transcription / --no-transcription" type="boolean" default="false">
  Enable transcription logging.
</ParamField>

<ParamField path="--video-input / --no-video-input" type="boolean" default="false">
  Enable video input (web bots only).
</ParamField>

<ParamField path="--video-output / --no-video-output" type="boolean" default="false">
  Enable video output (web bots only).
</ParamField>

<ParamField path="--deploy-to-cloud / --no-deploy-to-cloud" type="boolean" default="true">
  Generate Pipecat Cloud deployment files (Dockerfile, pcc-deploy.toml).
</ParamField>

<ParamField path="--enable-krisp / --no-enable-krisp" type="boolean" default="false">
  Enable Krisp noise cancellation (requires cloud deployment).
</ParamField>

<ParamField path="--observability / --no-observability" type="boolean" default="false">
  Enable observability.
</ParamField>

<ParamField path="--eval / --no-eval" type="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](/api-reference/cli/eval) for the verification workflow.
</ParamField>

<ParamField path="--config / -c" type="string">
  Path to a JSON config file. Triggers non-interactive scaffolding. CLI flags
  override file values.
</ParamField>

<ParamField path="--dry-run" type="boolean" default="false">
  Print the resolved scaffold configuration as JSON without writing any files.
</ParamField>

<ParamField path="--list-options" type="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.
</ParamField>

## 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:

```shell theme={null}
# 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

```shell theme={null}
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

```shell theme={null}
pipecat init my-bot
```

### Scaffold in place, non-interactively

```shell theme={null}
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

```shell theme={null}
pipecat init rt-bot --bot-type web --transport smallwebrtc \
  --mode realtime --realtime openai_realtime
```

### Multiple transports

```shell theme={null}
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

```shell theme={null}
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

```shell theme={null}
pipecat init call-bot --bot-type telephony --transport twilio \
  --mode cascade --stt deepgram_stt --llm openai_llm --tts cartesia_tts
```

### Eval-ready bot

```shell theme={null}
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

```shell theme={null}
pipecat init my-bot --overwrite-guide
```

### Scaffold the quickstart project

```shell theme={null}
pipecat init quickstart
```

### Discover available options

```shell theme={null}
pipecat init --list-options
```

Output:

```json theme={null}
{
  "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:

```shell theme={null}
options=$(pipecat init --list-options)
tts=$(echo "$options" | jq -r '.tts[0]')
```

### Dry run

```shell theme={null}
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

```shell theme={null}
pipecat init my-bot --config project-config.json
```

Sample `project-config.json`:

```json theme={null}
{
  "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 theme={null}
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](/api-reference/context-hub) setup, so a scaffolded project is ready to extend with Claude Code or Codex.

## Next Steps

<Card title="Build Your Next Bot" icon="wand-magic-sparkles" href="/pipecat/get-started/build-your-next-bot">
  The full flow: initialize a project, then build with a coding agent or
  scaffold a bot
</Card>