Getting Started

Quick start

The fastest way to start is with npx:

npx code2cast init

This launches an interactive wizard that walks you through project setup.

Installation

If you prefer a global install:

npm install -g code2cast

Or with your package manager of choice:

npm

npm install -g code2cast

pnpm

pnpm add -g code2cast

yarn

yarn global add code2cast

Initialise a project

Run the init command in your project directory:

cd my-project
code2cast init

The wizard will ask you for:

1. Project name -- used as the podcast series title
2. Description -- a short summary of what the project does
3. Theme -- the tone of the podcast (casual, technical, entertaining, or executive)
4. Duration -- target episode length in minutes

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

Non-interactive mode

For CI pipelines or AI agents, skip the wizard:

code2cast init --yes --name "My Project" --theme technical

Add --json for machine-readable output:

code2cast init --json --yes --name "My Project"

Authenticate with the platform

To publish episodes to code2cast.com, connect the CLI:

code2cast auth login

This opens your browser where you can create an API key. For CI/CD or non-interactive use:

code2cast auth login --api-key c2c_your_key_here

Check your authentication status:

code2cast status

Create a podcast

Before publishing episodes, create a podcast to hold them:

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

You can also specify a custom slug, description, and visibility:

code2cast podcast create \
  --name "My Podcast" \
  --slug my-podcast \
  --repo owner/repo \
  --description "A podcast about my project" \
  --visibility public

List your podcasts:

code2cast podcast list

Generate, voice, and publish

With a project initialised and a podcast created, the full workflow is:

# 1. Generate a podcast script from your codebase
code2cast generate

# 2. Synthesize audio from the script
code2cast voice

# 3. Preview locally before publishing
code2cast preview

# 4. Publish to the platform
code2cast publish --podcast my-podcast

Each step saves output to .code2cast/output/episode-N/:

.code2cast/output/episode-1/
  script.json      # Generated dialogue
  audio.mp3        # Synthesized audio
  metadata.json    # Generation provenance

Manage your podcasts

All podcast operations are available via the CLI:

# List podcasts
code2cast podcast list

# Delete a podcast (requires --confirm)
code2cast podcast delete --slug my-podcast --confirm

You can also manage podcasts, episodes, images, and settings from the web dashboard at code2cast.com/dashboard.

Next steps

• Follow the Your First Episode tutorial for a detailed walkthrough
• Browse the CLI Reference for all available commands
• Read about Configuration options