Skip to content

README.md

Latest commit

 

History

History
364 lines (253 loc) · 6.42 KB

README.md

File metadata and controls

364 lines (253 loc) · 6.42 KB

@podcast-framework/cli

Command-line tool for creating and managing podcast framework projects.

Installation

# Install globally
npm install -g @podcast-framework/cli

# Or use with npx (no installation)
npx @podcast-framework/cli <command>

Commands

create [name]

Create a new podcast project from template.

podcast-framework create my-podcast

# Skip npm install
podcast-framework create my-podcast --skip-install

Interactive prompts:

  • Podcast name (if not provided)
  • Tagline
  • Description
  • Feature selection (newsletter, contributions, search)

What it creates:

  • Complete project structure (src/, public/, sanity/)
  • package.json with framework dependencies
  • podcast.config.js with your settings
  • astro.config.mjs
  • .env.template
  • Homepage
  • README

info

Display information about the current podcast project.

podcast-framework info

Shows:

  • Project name and version
  • Framework package versions
  • Astro and Sanity versions
  • Configuration file location
  • Helpful next commands

validate

Validate podcast project structure and configuration.

podcast-framework validate

# Show detailed validation
podcast-framework validate --verbose

Checks:

  • package.json exists and is valid
  • Required dependencies installed
  • Configuration files present
  • Directory structure correct
  • Environment variables configured

Exit Codes:

  • 0: Validation passed
  • 1: Validation failed

update

Update framework packages to latest versions.

# Update to latest compatible versions (patch/minor)
podcast-framework update

# Update to latest versions (may include breaking changes)
podcast-framework update --major

# Preview updates without applying
podcast-framework update --dry-run

Features:

  • Automatic backup creation (for --major)
  • Shows version changes (old → new)
  • Provides migration guidance
  • Safe rollback available

rollback

Rollback to a previous framework version from backup.

# List available backups
podcast-framework rollback --list

# Rollback to most recent backup
podcast-framework rollback --last

# Rollback to specific version
podcast-framework rollback --to v2.1.0

# Interactive selection
podcast-framework rollback

What it restores:

  • package.json
  • package-lock.json
  • podcast.config.js

Note: Run npm install after rollback to reinstall dependencies

migrate-schema

Generate Sanity schema migration template.

# Generate migration from v1 to v2
podcast-framework migrate-schema --from v1 --to v2

What it creates:

  • Migration file in sanity/migrations/
  • Template with TODOs for manual review
  • Example migration logic
  • Testing instructions
  • Safety warnings

Important: Always review and test migrations before running on production!

override <component>

Create a component override in your podcast.

podcast-framework override Header

# Overwrite existing override
podcast-framework override Header --force

What it does:

  • Creates src/components/<ComponentName>.astro
  • Generates template with 3 options:
    1. Replace framework component
    2. Wrap framework component
    3. Use framework as starting point
  • Provides usage instructions

Available components:

  • Header, Footer, NewsletterSignup, EpisodeSearch
  • TranscriptViewer, FeaturedEpisodesCarousel
  • SkeletonLoader, BlockContent

list-components

List all available framework components.

podcast-framework list-components

# Show detailed info
podcast-framework list-components --verbose

Output:

  • Component names
  • Descriptions (with --verbose)
  • Props (with --verbose)
  • Usage examples

list-schemas

List all available Sanity schemas.

podcast-framework list-schemas

# Show detailed info
podcast-framework list-schemas --verbose

Output:

  • Schema names (episode, guest, host, podcast, contribution)
  • Descriptions (with --verbose)
  • Field lists (with --verbose)
  • Usage and extension examples

validate

Validate podcast project structure and configuration.

podcast-framework validate

# Show detailed validation
podcast-framework validate --verbose

Checks:

  • package.json exists and is valid
  • Required dependencies installed
  • Configuration files present
  • Directory structure correct
  • Environment variables configured

Exit Codes:

  • 0: Validation passed
  • 1: Validation failed

override <component>

Create a component override in your podcast.

podcast-framework override Header

# Overwrite existing override
podcast-framework override Header --force

What it does:

  • Creates src/components/<ComponentName>.astro
  • Generates template with 3 options:
    1. Replace framework component
    2. Wrap framework component
    3. Use framework as starting point
  • Provides usage instructions

Available components:

  • Header, Footer, NewsletterSignup, EpisodeSearch
  • TranscriptViewer, FeaturedEpisodesCarousel
  • SkeletonLoader, BlockContent

check-updates

Check for available framework updates.

podcast-framework check-updates

Status: Scaffold only (full implementation in Week 6)

Currently shows:

  • Current package versions
  • Manual check instructions

Future:

  • Fetch latest versions from npm
  • Show changelog
  • Recommend updates

Coming Soon

Week 6-7 Commands:

  • create <name> - Create new podcast project
  • update - Update framework packages
  • migrate-schema - Generate schema migration
  • backup-sanity - Backup Sanity dataset
  • workspace - Multi-podcast management

Usage Examples

Validate Project

cd my-podcast
podcast-framework validate

Override Component

podcast-framework override Header
# Edit src/components/Header.astro
npm run dev

List Available Components

podcast-framework list-components --verbose

Development

# Clone repository
git clone https://github.com/podcast-framework/podcast-framework.git
cd podcast-framework/packages/cli

# Install dependencies
npm install

# Run in development
npm run dev <command>

# Build
npm run build

# Test
npm test

Version

Current version: 0.1.0 (Week 4-5)

Status: Foundation complete, 5 commands working

Roadmap:

  • Week 5: ✅ Helper commands (validate, override, list-schemas)
  • Week 6-7: Create, update, migrate commands
  • Week 7: CLI tests and polish

License

MIT - see LICENSE