Your First Episode

This tutorial walks you through generating a podcast episode from a real codebase, end to end. By the end, you'll have an MP3 file you can listen to.

Prerequisites

• Node.js 22+
• A git repository with some commit history
• An ElevenLabs API key (for voice synthesis)

For script generation, code2cast uses a hosted Claude proxy by default — no API key needed to get started. You can also use your own Anthropic or OpenAI key (see step 4).

1. Install the CLI

npm install -g code2cast

Verify it's working:

code2cast --version

2. Initialise your project

Navigate to the repository you want to turn into a podcast and run:

cd ~/my-project
code2cast init

The interactive wizard asks for a project name, description, theme, and target duration. For your first episode, the defaults are fine — just press enter through each step.

This creates .code2cast/config.json in your project root:

{
  "name": "my-project",
  "include": ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"],
  "exclude": ["node_modules", "dist", ".git"],
  "theme": "casual",
  "durationMinutes": 5
}

Non-interactive alternative

code2cast init --yes --name "My Project" --theme casual --duration 3m

Duration accepts human-friendly formats: 30s, 2m 30s, 5, etc.

3. Check your status

Before generating, verify everything looks right:

code2cast status

This shows your project config and authentication state. You don't need to be authenticated with the platform to generate episodes locally.

4. Configure script generation

The generate command needs an AI provider to write the podcast script. By default, code2cast uses a hosted Claude proxy — no setup required.

Default: Claude proxy (no API key needed)

Just run code2cast generate — it works out of the box.

Option B: Anthropic API key

If you prefer to use your own Anthropic API key:

export ANTHROPIC_API_KEY=sk-ant-api03-...
code2cast generate --provider claude

Option C: OpenAI Codex

export OPENAI_API_KEY=sk-...
code2cast generate --provider codex

Option D: Self-hosted Claude proxy

If you run your own remote-claude instance:

code2cast generate --provider claude-proxy --base-url http://localhost:4009

Per-command API key

Any provider that needs a key accepts --api-key inline:

code2cast generate --provider claude --api-key sk-ant-api03-...
code2cast voice --api-key xi-...

5. Generate a script

Now the fun part. This command analyzes your codebase and recent git history, then generates a podcast script:

code2cast generate

You'll see progress as it works through three steps:

1. Analyzing codebase — reads your source files (up to 200 files, respecting include/exclude patterns)
2. Analyzing git history — scans the last 30 days of commits and PRs
3. Generating script — streams the script from the AI provider

The output is saved to .code2cast/output/episode-1/script.json.

Customising generation

Analyse a different time range:

code2cast generate --days 7
code2cast generate --from 2025-01-01 --to 2025-02-01

Preview what would be analysed without generating:

code2cast generate --dry-run

6. Synthesize audio

Convert the script into spoken audio using ElevenLabs:

export ELEVENLABS_API_KEY=xi-...
code2cast voice

This reads the script from step 5, sends each dialogue segment to ElevenLabs for text-to-speech, and concatenates the results into a single MP3 file.

Output: .code2cast/output/episode-1/audio.mp3

Specifying an episode

If you've generated multiple episodes:

code2cast voice --episode 2

7. Listen to it

Play the generated episode locally:

code2cast preview

This uses your system's audio player (afplay on macOS, paplay on Linux). Press Ctrl+C to stop playback.

What's in the output directory

After completing these steps, your .code2cast/ directory looks like this:

.code2cast/
  config.json              # Project config (from step 2)
  output/
    episode-1/
      script.json          # Generated dialogue
      metadata.json        # Generation stats (provider, timestamps, file/commit counts)
      audio.mp3            # Synthesized audio (from step 6)

Next steps

Customize your cast

By default, episodes are generated with a Host and Guest. You can customize speakers, assign personas, and pick voices:

# Add a named guest for this episode
code2cast generate --guest "Dr. Smith:Chief architect"

# Multiple guests
code2cast generate --guest Alice --guest "Bob:CTO"

# Full cast override
code2cast generate --cast '[{"name":"Alex","role":"host"},{"name":"Sam","role":"guest","description":"Security researcher"}]'

To configure the default cast with voice selection, use Studio:

code2cast studio

This opens a local web app where you can manage speakers, browse ElevenLabs voices with preview, and configure all project settings visually. See the CLI Reference for details.

Authenticate and publish

To publish episodes to code2cast.com, first authenticate:

code2cast auth login

This opens your browser where you create an API key. For CI/CD, pass it directly:

code2cast auth login --api-key c2c_your_key_here

Then create a podcast to hold your episodes:

code2cast podcast create --name "My Project" --repo owner/repo

And publish:

code2cast publish --episode 1 --podcast my-project

The publish command:

1. Creates a draft episode on the platform
2. Uploads your audio to R2 storage via presigned URL
3. Uploads the transcript (if available)
4. Uploads a cover image (if cover.jpg/cover.png exists in the episode directory)
5. Publishes the episode (unless --draft is passed)

Manage podcasts

All podcast operations work from the CLI:

# List your podcasts
code2cast podcast list

# Delete a podcast
code2cast podcast delete --slug my-project --confirm

Plan a series

Instead of one-off episodes, plan a multi-episode series:

code2cast plan --episodes 5 --strategy architecture

This creates .code2cast/plan.json with episode outlines you can then generate one at a time.

Automate with CI

Every command supports --json for machine-readable output and --yes for non-interactive mode:

code2cast generate --json --yes | jq '.title'

See For AI Agents in the CLI reference.