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
studio — Launch the Studio web app for managing your project
studio:dev — Launch Studio in dev mode (Vite HMR + full error messages)
[config get](#config get) — Read a user setting
[config set](#config set) — Update a user setting
[podcast create](#podcast create) — Create a new podcast
[podcast list](#podcast list) — List your podcasts
[podcast delete](#podcast delete) — Delete a podcast

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

Default: 5

Target episode duration (e.g. 30s, 2m, 2m 30s, 5)

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

Opens a browser to authenticate with the code2cast platform. After authorizing, the CLI receives an API key automatically. For CI/CD, pass --api-key directly. For environments without a browser, use --manual.

code2cast auth login [options]

Options

`--api-key <key>`

API key (c2c_xxx) for non-interactive auth (CI/CD)

`--manual`

Default: false

Paste an API key manually instead of browser auth

`--web-url <url>`

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

Examples

code2cast auth login
code2cast auth login --api-key c2c_abc123...
code2cast auth login --manual
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, codex, or claude-proxy)

`--api-key <key>`

Provider API key (overrides settings)

`--base-url <url>`

Base URL for claude-proxy provider

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

`--guest <name>`

Add a named guest (repeatable). Use 'Name:Description' for persona, e.g. 'Dr. Smith:Chief architect'

`--cast <json>`

Full cast override as JSON array, e.g. '[{"name":"Alex","role":"host"},{"name":"Sam","role":"guest"}]'

Examples

code2cast generate
code2cast generate --provider codex
code2cast generate --days 7
code2cast generate --guest 'Dr. Smith:Chief architect'
code2cast generate --guest Alice --guest Bob
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, codex, or claude-proxy)

`--api-key <key>`

Provider API key

`--base-url <url>`

Base URL for claude-proxy provider

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

`studio`

Starts a local web server and opens the Studio interface in your browser. Studio lets you browse episodes, edit settings, play audio, and manage your podcast project visually.

code2cast studio [path] [options]

Arguments

`path`

Optional · Default: .

Project directory (defaults to cwd)

Options

`--port <port>`

Default: 24842

Port for the Studio server

`--no-open`

Default: false

Don't open the browser automatically

Examples

code2cast studio
code2cast studio ./my-project
code2cast studio --port 3333

`studio:dev`

Starts the Hono API server and Vite dev server concurrently. Gives you hot module replacement, unminified React errors, and fast refresh.

code2cast studio:dev [path] [options]

Arguments

`path`

Optional · Default: .

Project directory (defaults to cwd)

Examples

code2cast studio:dev
code2cast studio:dev ./my-project

`config get`

Reads a value from ~/.code2cast/settings.json using a dotpath key. Run without arguments to see all known setting paths.

code2cast config get [key] [options]

Arguments

`key`

Optional

Setting path (e.g. providers.elevenlabs.apiKey). Omit to list all paths.

Examples

code2cast config get
code2cast config get providers.elevenlabs.apiKey
code2cast config get providers.scriptDefault
code2cast config get auth.webUrl

`config set`

Writes a value to ~/.code2cast/settings.json using a dotpath key. The file is created if it doesn't exist. Permissions are set to 0600.

code2cast config set <key> <value> [options]

Arguments

`key`

Required

Setting path (e.g. providers.elevenlabs.apiKey)

`value`

Required

Value to set

Examples

code2cast config set providers.elevenlabs.apiKey xi-...
code2cast config set providers.scriptDefault claude
code2cast config set providers.claude.apiKey sk-ant-...
code2cast config set output.format wav
code2cast config set auth.webUrl http://localhost:3000

`podcast create`

Creates a new podcast under your default organization. Requires authentication via code2cast auth login.

code2cast podcast create [options]

Options

`--name <name>`

Podcast name (required)

`--slug <slug>`

URL slug (auto-generated from name if omitted)

`--repo <owner/repo>`

GitHub repository

`--description <desc>`

Short description

`--visibility <visibility>`

Default: public

public, private, or unlisted

Examples

code2cast podcast create --name "My Podcast" --repo owner/repo
code2cast podcast create --name "My Podcast" --slug my-podcast --visibility private

`podcast list`

Lists all podcasts you have access to.

code2cast podcast list [options]

Examples

code2cast podcast list

`podcast delete`

Permanently deletes a podcast and all its episodes. This cannot be undone.

code2cast podcast delete [options]

Options

`--slug <slug>`

Podcast slug to delete (required)

`--confirm`

Default: false

Skip confirmation prompt

Examples

code2cast podcast delete --slug my-podcast --confirm

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.

CLI Reference ​

Commands ​

Global Options ​

--json ​

--no-interaction ​

--commands ​

--verbose ​

-V, --version ​

-h, --help ​

init ​

Arguments ​

path ​

Options ​

--name <name> ​

--description <desc> ​

--theme <theme> ​

--duration <duration> ​

-y, --yes ​

Examples ​

auth login ​

Options ​

--api-key <key> ​

--manual ​

--web-url <url> ​

Examples ​

auth logout ​

Examples ​

status ​

Arguments ​

path ​

Examples ​

generate ​

Arguments ​

path ​

Options ​

--provider <name> ​

--api-key <key> ​

--base-url <url> ​

--episode <number> ​

--days <n> ​

--from <date> ​

--to <date> ​

--dry-run ​

--guest <name> ​

--cast <json> ​

Examples ​

plan ​

Arguments ​

path ​

Options ​

--episodes <n> ​

--provider <name> ​

--api-key <key> ​

--base-url <url> ​

--strategy <type> ​

Examples ​

voice ​

Arguments ​

path ​

Options ​

--episode <number> ​

--provider <name> ​

--api-key <key> ​

--model <id> ​

Examples ​

publish ​

Arguments ​

path ​

Options ​

--episode <number> ​

--podcast <slug> ​

--title <title> ​

--description <desc> ​

--draft ​

Examples ​

preview ​

Arguments ​

path ​

Options ​

--episode <number> ​

CLI Reference

Commands

Global Options

`--json`

`--no-interaction`

`--commands`

`--verbose`

`-V, --version`

`-h, --help`

`init`

Arguments

`path`

Options

`--name <name>`

`--description <desc>`

`--theme <theme>`

`--duration <duration>`

`-y, --yes`

Examples

`auth login`

Options

`--api-key <key>`

`--manual`

`--web-url <url>`

Examples

`auth logout`

Examples

`status`

Arguments

`path`

Examples

`generate`

Arguments

`path`

Options

`--provider <name>`

`--api-key <key>`

`--base-url <url>`

`--episode <number>`

`--days <n>`

`--from <date>`

`--to <date>`

`--dry-run`

`--guest <name>`

`--cast <json>`

Examples

`plan`

Arguments

`path`

Options

`--episodes <n>`

`--provider <name>`

`--api-key <key>`

`--base-url <url>`

`--strategy <type>`

Examples

`voice`

Arguments

`path`

Options

`--episode <number>`

`--provider <name>`

`--api-key <key>`

`--model <id>`

Examples

`publish`

Arguments

`path`

Options

`--episode <number>`

`--podcast <slug>`

`--title <title>`

`--description <desc>`

`--draft`

Examples

`preview`

Arguments

`path`

Options

`--episode <number>`