npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@vidgen/app-cli

v0.1.1

Published

Vidgen App CLI & MCP Server — automate AI video generation via the Vidgen platform

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Maintainers

forwaardforwaardlu_xilu_xi

Keywords

vidgencliaivideomcp

Readme

@vidgen/app-cli

Inventory and command reference for the Vidgen App CLI package.

This package currently exposes three runnable surfaces:

  1. package.json scripts for local development, build, publish, and tests
  2. The vidgen-app CLI for interactive workflows
  3. An MCP server entrypoint for AI agents

The apps/app-cli/scripts/ directory exists but is currently empty, so there are no standalone shell or Node scripts outside the surfaces above.

Inventory Summary

| Surface | Count | Notes | | ---------------------- | ----- | -------------------------------------------------------------- | | Package scripts | 11 | Build, local run, MCP run, tests, release | | Top-level CLI commands | 10 | Auth, briefs, scripts, videos, pipeline, strategy, TikTok, MCP | | MCP tools | 6 | Brief, scripts, video, pipeline, strategy | | Command source modules | 7 | One module per CLI domain under src/cli/commands |

Package Scripts

| Script | What it does | | ---------------- | ----------------------------------------------------------------- | | build | Build ESM bundles with tsup into dist/ | | dev | Watch-mode build with tsup --watch | | dev:run | Run the CLI entrypoint directly from src/cli/index.ts via tsx | | dev:mcp | Run the MCP server directly from src/mcp/index.ts via tsx | | start | Run the built CLI from dist/cli/index.js | | test | Run the Vitest unit test suite | | test:watch | Run Vitest in watch mode | | type-check | Run tsc --noEmit for the package source | | prepublishOnly | Type-check and build before publish | | release | Run prepublish checks, then publish to npm | | release:dry | Run prepublish checks, then perform a dry-run npm publish |

Package Script Examples

Run these from the repo root:

pnpm --filter @vidgen/app-cli build
pnpm --filter @vidgen/app-cli dev
pnpm --filter @vidgen/app-cli dev:run -- --help
pnpm --filter @vidgen/app-cli dev:mcp
pnpm --filter @vidgen/app-cli start -- --help
pnpm --filter @vidgen/app-cli test
pnpm --filter @vidgen/app-cli test:watch
pnpm --filter @vidgen/app-cli type-check
pnpm --filter @vidgen/app-cli release:dry
# Real publish:
pnpm --filter @vidgen/app-cli release

CLI Command Surface

Common Setup

Most examples below assume either:

  1. You have already run vidgen-app login, or
  2. You exported the environment variables directly
export VIDGEN_APP_API_URL=https://vidgen-api.beervid.ai/api/v1
export VIDGEN_APP_TOKEN=vidgen_your_token_here

Top-Level Commands

| Command | Description | Source | | ---------- | ------------------------------------------- | --------------------------------------- | | login | Save API URL and token to local config | src/cli/commands/auth.ts | | logout | Clear saved authentication | src/cli/commands/auth.ts | | whoami | Show the currently resolved config | src/cli/commands/auth.ts | | brief | Creative brief management | src/cli/commands/brief.ts | | script | Generated script management | src/cli/commands/script.ts | | video | Video task management | src/cli/commands/video.ts | | pipeline | End-to-end brief-to-video workflow | src/cli/commands/pipeline.ts | | strategy | Strategy scheduling and execution debugging | src/cli/commands/strategy.ts | | tiktok | TikTok and TikTok Shop operations | src/cli/commands/tiktok.ts | | mcp | Start the stdio MCP server | src/cli/index.ts + src/mcp/index.ts |

Top-Level Command Examples

vidgen-app --help
vidgen-app --version

Authentication:

vidgen-app login \
  --api-url https://vidgen-api.beervid.ai/api/v1 \
  --token vidgen_your_token_here

vidgen-app whoami
vidgen-app logout

brief

| Subcommand | Description | | ------------------------- | ------------------------------------------------ | | brief list | List briefs for the current account | | brief submit | Submit a product brief from flags or a YAML file | | brief status <briefId> | Query or watch brief task status | | brief scripts <briefId> | List scripts generated for a brief |

Key implementation notes:

  • brief submit --file <path> uses src/cli/lib/yaml-loader.ts
  • Local images referenced in YAML are uploaded via StorageClient
  • --wait reuses BriefsApi.pollUntilComplete(...)

Examples:

# List briefs
vidgen-app brief list
vidgen-app brief list --page 2 --page-size 10
vidgen-app brief list --json

# Submit with flags
vidgen-app brief submit \
  --product-url https://example.com/products/portable-blender \
  --product-name "Portable Blender Pro" \
  --platform tiktok \
  --market US \
  --output-language English \
  --currency USD \
  --optimization-mode gmv_first \
  --script-count 5 \
  --wait

# Submit with inline product text instead of product URL
vidgen-app brief submit \
  --product-text "USB-C portable blender for smoothies on the go" \
  --product-name "Portable Blender Pro" \
  --platform instagram \
  --market UK \
  --script-count 3

# Submit from YAML
vidgen-app brief submit --file ./examples/portable-blender.yml
vidgen-app brief submit --file ./examples/portable-blender.yml --wait
vidgen-app brief submit --file ./examples/portable-blender.yml --json

# Check status
vidgen-app brief status 018f1234-aaaa-bbbb-cccc-1234567890ab
vidgen-app brief status 018f1234-aaaa-bbbb-cccc-1234567890ab --watch
vidgen-app brief status 018f1234-aaaa-bbbb-cccc-1234567890ab --json

# List generated scripts
vidgen-app brief scripts 018f1234-aaaa-bbbb-cccc-1234567890ab
vidgen-app brief scripts 018f1234-aaaa-bbbb-cccc-1234567890ab --json

script

| Subcommand | Description | | ------------------------------- | ------------------------------------ | | script list --brief-id <uuid> | List scripts for a brief | | script show <scriptId> | Show full script details and content | | script to-video <scriptId> | Create a video task from a script |

Key options:

  • script to-video supports --tech-type, --scale, --segments, --wait, and --json

Examples:

# List scripts for a brief
vidgen-app script list --brief-id 018f1234-aaaa-bbbb-cccc-1234567890ab
vidgen-app script list --brief-id 018f1234-aaaa-bbbb-cccc-1234567890ab --json

# Show one script
vidgen-app script show 018f9003-aaaa-bbbb-cccc-1234567890ab
vidgen-app script show 018f9003-aaaa-bbbb-cccc-1234567890ab --json

# Turn a script into a video task
vidgen-app script to-video 018f9003-aaaa-bbbb-cccc-1234567890ab
vidgen-app script to-video 018f9003-aaaa-bbbb-cccc-1234567890ab \
  --tech-type veo \
  --scale 9:16 \
  --segments 3 \
  --wait
vidgen-app script to-video 018f9003-aaaa-bbbb-cccc-1234567890ab --json

video

| Subcommand | Description | | ---------------------------- | -------------------------------- | | video status <videoTaskId> | Query or watch video task status |

Examples:

vidgen-app video status 018fabc1-aaaa-bbbb-cccc-1234567890ab
vidgen-app video status 018fabc1-aaaa-bbbb-cccc-1234567890ab --watch
vidgen-app video status 018fabc1-aaaa-bbbb-cccc-1234567890ab --json

pipeline

| Subcommand | Description | | -------------- | --------------------------------------------------------------------------------- | | pipeline run | Submit a brief, wait for scripts, select top N, and optionally create video tasks |

Key options:

  • --brief-id reuses an existing brief instead of submitting a new one
  • --dry-run stops after script selection
  • --top-n, --tech-type, and --scale control video creation

Examples:

# Full pipeline from product URL
vidgen-app pipeline run \
  --product-url https://example.com/products/portable-blender \
  --product-name "Portable Blender Pro" \
  --platform tiktok \
  --market US \
  --output-language English \
  --top-n 3 \
  --tech-type veo \
  --scale 9:16

# Full pipeline from inline product text
vidgen-app pipeline run \
  --product-text "Portable smoothie blender with USB-C charging" \
  --platform youtube_shorts \
  --market DE \
  --top-n 2

# Reuse an existing brief and skip video creation
vidgen-app pipeline run \
  --brief-id 018f1234-aaaa-bbbb-cccc-1234567890ab \
  --dry-run \
  --json

strategy

| Subcommand | Description | | ------------------------------------- | ------------------------------------ | | strategy list | List all generation strategies | | strategy show <strategyId> | Show strategy details | | strategy plan:generate <strategyId> | Generate a daily plan with the LLM | | strategy plan:schedule <strategyId> | Schedule plan executions into BullMQ | | strategy plan:status <strategyId> | Inspect daily plan executions | | strategy execute:slot <executionId> | Run one execution slot immediately |

Examples:

vidgen-app strategy list
vidgen-app strategy list --market-id 018f1111-aaaa-bbbb-cccc-1234567890ab
vidgen-app strategy list --json

vidgen-app strategy show 018f2222-aaaa-bbbb-cccc-1234567890ab
vidgen-app strategy show 018f2222-aaaa-bbbb-cccc-1234567890ab --json

vidgen-app strategy plan:generate 018f2222-aaaa-bbbb-cccc-1234567890ab
vidgen-app strategy plan:generate 018f2222-aaaa-bbbb-cccc-1234567890ab --date 2026-04-17
vidgen-app strategy plan:generate 018f2222-aaaa-bbbb-cccc-1234567890ab --json

vidgen-app strategy plan:schedule 018f2222-aaaa-bbbb-cccc-1234567890ab
vidgen-app strategy plan:schedule 018f2222-aaaa-bbbb-cccc-1234567890ab --date 2026-04-17
vidgen-app strategy plan:schedule 018f2222-aaaa-bbbb-cccc-1234567890ab --json

vidgen-app strategy plan:status 018f2222-aaaa-bbbb-cccc-1234567890ab
vidgen-app strategy plan:status 018f2222-aaaa-bbbb-cccc-1234567890ab --date 2026-04-17
vidgen-app strategy plan:status 018f2222-aaaa-bbbb-cccc-1234567890ab --json

vidgen-app strategy execute:slot 018feee4-aaaa-bbbb-cccc-1234567890ab
vidgen-app strategy execute:slot 018feee4-aaaa-bbbb-cccc-1234567890ab --json

tiktok

| Subcommand | Description | | -------------------------------- | ------------------------------------------------ | | tiktok auth:link | Generate an OAuth link for TikTok or TikTok Shop | | tiktok accounts list | List authorized TT/TTS accounts | | tiktok publish | Upload and publish a video to TT or TTS | | tiktok publish:status <taskId> | Query publish task status | | tiktok videos | Query TikTok video metrics | | tiktok performances | Query TikTok Shop performance metrics | | tiktok products:shop | List TikTok Shop products | | tiktok products:showcase | List TikTok Showcase products |

Key implementation notes:

  • tiktok publish accepts either --file or --url
  • For --platform tts, both --product-id and --product-title are required
  • OSS upload is handled through TikTokApi.getOssUploadUrl(...) plus a direct fetch(..., { method: 'PUT' })

Examples:

# Generate OAuth link
vidgen-app tiktok auth:link --platform tt
vidgen-app tiktok auth:link --platform tts --json

# List authorized accounts
vidgen-app tiktok accounts list
vidgen-app tiktok accounts list --json

# Publish a local file to TikTok
vidgen-app tiktok publish \
  --account 7123456789012345678 \
  --platform tt \
  --caption "Portable Blender Pro demo #portableblender" \
  --file ./assets/portable-blender-demo.mp4

# Publish from a remote URL to TikTok Shop
vidgen-app tiktok publish \
  --account 7123456789012345678 \
  --platform tts \
  --caption "Portable Blender Pro demo #tiktokshop" \
  --url https://cdn.example.com/videos/portable-blender-demo.mp4 \
  --product-id 1738392012345678901 \
  --product-title "Portable Blender Pro" \
  --json

# Check publish task status
vidgen-app tiktok publish:status 018fabcd-aaaa-bbbb-cccc-1234567890ab
vidgen-app tiktok publish:status 018fabcd-aaaa-bbbb-cccc-1234567890ab --json

# Query TikTok video data
vidgen-app tiktok videos --openId 7123456789012345678
vidgen-app tiktok videos --openId 7123456789012345678 --video-ids 745839201,745839202
vidgen-app tiktok videos --openId 7123456789012345678 --video-ids 745839201,745839202 --json

# Query TikTok Shop performance data
vidgen-app tiktok performances \
  --openId 7123456789012345678 \
  --video-ids 745839201,745839202 \
  --start 1744761600 \
  --end 1744847999

vidgen-app tiktok performances \
  --openId 7123456789012345678 \
  --video-ids 745839201,745839202 \
  --start 1744761600 \
  --end 1744847999 \
  --json

# List TikTok Shop products
vidgen-app tiktok products:shop --openId 7123456789012345678
vidgen-app tiktok products:shop --openId 7123456789012345678 --page-size 50
vidgen-app tiktok products:shop --openId 7123456789012345678 --page-token next_page_token --json

# List TikTok showcase products
vidgen-app tiktok products:showcase --openId 7123456789012345678
vidgen-app tiktok products:showcase --openId 7123456789012345678 --page-size 50
vidgen-app tiktok products:showcase --openId 7123456789012345678 --page-token next_page_token --json

mcp

Examples:

# Start the stdio MCP server with inline environment variables
VIDGEN_APP_API_URL=https://vidgen-api.beervid.ai/api/v1 \
VIDGEN_APP_TOKEN=vidgen_your_token_here \
vidgen-app mcp

MCP Tools

src/mcp/index.ts currently registers 6 tools:

| Tool | Purpose | | --------------------- | ----------------------------------------------- | | submit_brief | Submit a brief for script generation | | get_brief_status | Query brief task status | | get_scripts | Retrieve generated scripts for a brief | | create_video | Create a video task from a script | | run_pipeline | Execute the end-to-end pipeline | | get_strategy_status | Inspect strategy daily plan and execution slots |

Source Map

| File | Responsibility | | ------------------------------ | -------------------------------------------------------- | | src/index.ts | Public exports for external consumers | | src/cli/index.ts | CLI entrypoint and top-level registration | | src/cli/commands/auth.ts | Auth commands | | src/cli/commands/brief.ts | Brief workflows, YAML submission, post-submit wait logic | | src/cli/commands/script.ts | Script listing, detail, and video task creation | | src/cli/commands/video.ts | Video task polling | | src/cli/commands/pipeline.ts | Scenario 3 pipeline orchestration | | src/cli/commands/strategy.ts | Strategy debugging commands | | src/cli/commands/tiktok.ts | TT/TTS auth, publishing, metrics, products | | src/cli/lib/yaml-loader.ts | YAML parsing and validation for brief submission | | src/client/api-client.ts | Shared HTTP client with bearer auth | | src/client/briefs.ts | Brief endpoints and polling | | src/client/scripts.ts | Script detail API | | src/client/videos.ts | Video task creation and polling | | src/client/pipeline.ts | Select-top-N logic and pipeline orchestration | | src/client/strategies.ts | Strategy and plan APIs | | src/client/tiktok.ts | TT/TTS API client and structured error handling | | src/client/storage-client.ts | Pre-signed upload flow for local images | | src/mcp/index.ts | MCP server tool registration |

Current Gaps

  • apps/app-cli/scripts/ is empty, so all runnable behavior is currently defined in package.json, the CLI command tree, or MCP tools.
  • The docs site under apps/app/content/docs/app-cli/ is scenario-oriented; this README is the package-level inventory/reference view.