CLI Reference

Commands

• init — Initialise a new code2cast project
• [auth login](#auth login) — Authenticate CLI with the code2cast platform
• [auth logout](#auth logout) — Remove stored credentials
• status — Show project and account status
• generate — Generate a podcast script from your codebase
• plan — Plan an episode series from codebase analysis
• voice — Synthesize audio from a generated script
• publish — Publish an episode to the code2cast platform
• preview — Play a generated episode locally

Global Options

These flags work with any command.

--json

Emit machine-readable JSON output (AI-friendly)

--no-interaction

Disable interactive prompts

--commands

List all commands as JSON (for AI agents)

--verbose

Show detailed output

-V, --version

Print version

-h, --help

Show help

---

init

Sets up code2cast in the current (or specified) directory. In interactive mode, launches a guided wizard. In non-interactive / JSON mode, accepts all options as flags.

code2cast init [path] [options]

Arguments

path

Optional · Default: .

Project directory (defaults to cwd)

Options

--name <name>

Project name

--description <desc>

Short project description

--theme <theme>

Default: casual

Podcast tone (casual, technical, entertaining, deep-dive)

--duration <minutes>

Default: 10

Target episode duration in minutes

-y, --yes

Default: false

Accept all defaults (non-interactive)

Examples

code2cast init
code2cast init ./my-project
code2cast init --name "My App" --yes
code2cast init --json --name "My App" --yes

Interactive mode

This command launches a guided wizard when run without --yes or --json.

---

auth login

Store an API key for accessing the code2cast web platform. Create a key at your dashboard Settings → Developer page, then paste it here.

code2cast auth login [options]

Options

--api-key <key>

API key (c2c_xxx). If omitted, opens interactive prompt.

--web-url <url>

Web platform URL (default: https://code2cast.dev)

Examples

code2cast auth login
code2cast auth login --api-key c2c_abc123...
code2cast auth login --web-url http://localhost:3000

Interactive mode

This command launches a guided wizard when run without --yes or --json.

---

auth logout

Clears the stored API key and default org from settings.

code2cast auth logout [options]

Examples

code2cast auth logout

---

status

Displays the current project configuration, authentication state, and remote sync status if authenticated.

code2cast status [path] [options]

Arguments

path

Optional · Default: .

Project directory (defaults to cwd)

Examples

code2cast status
code2cast status ./my-project

---

generate

Analyses the codebase and git history, then generates a podcast script using Claude or Codex. Saves the script locally to .code2cast/output/.

code2cast generate [path] [options]

Arguments

path

Optional · Default: .

Project directory (defaults to cwd)

Options

--provider <name>

Script provider (claude or codex)

--api-key <key>

Provider API key (overrides settings)

--episode <number>

Episode number (defaults to next available)

--days <n>

Default: 30

Analyse last N days of git history

--from <date>

Git history start date (ISO 8601)

--to <date>

Git history end date (ISO 8601)

--dry-run

Default: false

Analyse codebase but don't generate script

Examples

code2cast generate
code2cast generate --provider codex
code2cast generate --days 7
code2cast generate --from 2025-01-01 --to 2025-02-01
code2cast generate --dry-run

Interactive mode

This command launches a guided wizard when run without --yes or --json.

---

plan

Analyses the codebase and proposes an episode plan — a series of topics covering the project's architecture, key features, and recent changes. Saves the plan to .code2cast/plan.json.

code2cast plan [path] [options]

Arguments

path

Optional · Default: .

Project directory (defaults to cwd)

Options

--episodes <n>

Default: 5

Number of episodes to plan

--provider <name>

AI provider for planning (claude or codex)

--api-key <key>

Provider API key

--strategy <type>

Default: architecture

Planning strategy: architecture, changelog, or features

Examples

code2cast plan
code2cast plan --episodes 10
code2cast plan --strategy changelog --episodes 3

---

voice

Reads a script from .code2cast/output/ and synthesizes podcast audio using ElevenLabs (or another voice provider). Outputs an MP3 file.

code2cast voice [path] [options]

Arguments

path

Optional · Default: .

Project directory (defaults to cwd)

Options

--episode <number>

Default: 1

Episode number (defaults to latest)

--provider <name>

Voice provider (elevenlabs)

--api-key <key>

Provider API key (overrides settings)

--model <id>

Voice model ID

Examples

code2cast voice
code2cast voice --episode 2
code2cast voice --provider elevenlabs --api-key xi_...

---

publish

Uploads audio and transcript to the web platform and creates or updates an episode. Requires authentication via code2cast auth login.

code2cast publish [path] [options]

Arguments

path

Optional · Default: .

Project directory (defaults to cwd)

Options

--episode <number>

Default: 1

Episode number to publish

--podcast <slug>

Target podcast slug (prompts if not set)

--title <title>

Override episode title

--description <desc>

Override episode description

--draft

Default: false

Create as draft (don't publish immediately)

Examples

code2cast publish --episode 1 --podcast my-podcast
code2cast publish --episode 2 --draft
code2cast publish --episode 1 --podcast my-podcast --title "Custom Title"

---

preview

Plays the audio file for a generated episode using the system audio player. On macOS uses afplay, on Linux uses aplay or paplay.

code2cast preview [path] [options]

Arguments

path

Optional · Default: .

Project directory (defaults to cwd)

Options

--episode <number>

Default: 1

Episode number to preview

Examples

code2cast preview
code2cast preview --episode 2

---

For AI Agents

code2cast is designed to be used by AI agents and automation tools.

Discovery

# Get the full command catalogue as JSON
code2cast --commands

Structured output

Pass --json to any command. Output is newline-delimited JSON where each line has a type field:

• result — Successful outcome with data
• error — Failure with code and optional hint
• progress — Progress update with optional pct (0–100)
• info — Informational message
• warn — Warning
• prompt — Describes expected input (interactive mode)

Non-interactive mode

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

The --no-interaction global flag is equivalent to passing --yes on every command.