> ## Documentation Index
> Fetch the complete documentation index at: https://daily-docs-context-hub-ships-with-cli.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>

<ParamField path="--context-hub / --no-context-hub" type="boolean" default="true">
  Register the [Pipecat Context Hub](/api-reference/context-hub) MCP server with
  your coding agents, and offer to build its index.
</ParamField>

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

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