Prosey

Prosey is a CLI tool to download and display video transcriptions from YouTube, so you can get the information you're looking for without wasting hours.

The main use cases are:

• Summarize a YouTube video and display it in the CLI with a single command (quicker).
• Read video captions, formatted and organized in chapters like the original video (often needs more time).

Both uses need an AI assistant on your system (default: opencode, use prosey config to configure your own).

If we detect a syntax highlighter on your system, you'll get a nice colored output.

Prosey can also output or store the native json format verbatim.

Features

Quickstart

Try it out immediately with npx:

npx @tacone/prosey 771PQEDeRmw
npx @tacone/prosey https://youtu.be/771PQEDeRmw --lang es -o transcript.txt

Install

Install globally with your favorite package manager:

npm install -g @tacone/prosey
# or
yarn global add @tacone/prosey
# or
pnpm add -g @tacone/prosey
# or
bun install -g @tacone/prosey

Then use it anywhere:

prosey 771PQEDeRmw

From Source

Uses Bun for development — scripts, package management, and running the TypeScript source directly.

git clone https://github.com/tacone/prosey.git
cd prosey
bun install
bun run start -- 771PQEDeRmw

Usage

prosey [options] <video controls-url-or-id>
prosey read [options] <video controls-url-or-id>
prosey info [options] <video controls-url-or-id>
prosey summarize [options] <video controls-url-or-id>
prosey config
prosey help

summarize is the default command, so prosey <id> runs the AI summarizer. Use prosey read <id> to download and print a richly formatted transcript.

The summarize command fetches a transcript, prepends the prompt from the [summarize] config section, and pipes the result to the configured AI command.

The read command downloads the transcript and prints it to stdout (plain text, markdown, or JSON). This is useful when you don't need AI processing.

The info command shows video metadata (title, channel, duration, views).

The config command opens your config file in $EDITOR for editing. If $EDITOR is not set, the config file path is printed.

The help command shows the help message, same as --help.

Examples

# Summarize (AI summary + formatting + syntax highlighting)
prosey 771PQEDeRmw

# Summarize (same as above)
prosey summarize 771PQEDeRmw

# Transcribe (AI summary + formatting + syntax highlighting)
prosey read 771PQEDeRmw

# Show video metadata
prosey info 771PQEDeRmw

# Edit config in $EDITOR
prosey config

# List available languages
prosey read https://youtu.be/771PQEDeRmw --list

# Specify language
prosey read https://youtu.be/771PQEDeRmw --lang es

# Display JSON (no AI transcription)
prosey read 771PQEDeRmw

# Display plain text (no AI transcription)
prosey read 771PQEDeRmw

# Save transcript to file
prosey read 771PQEDeRmw -o transcript.txt

Options

JSON format

When --json is used, the output is an array of objects:

[
  {
    "text": "♪ We're no strangers to love ♪",
    "offset": 18.64,
    "duration": 3.24,
    "timestamp": "00:18"
  }
]

timestamp is always present in JSON mode. Video details are suppressed (silently) since JSON is structured data.

Development

This project uses Bun for development.

bun run typecheck   # TypeScript check
bun run start       # Run the CLI from source
bun run test        # Run unit tests
bun run build       # Compile Node bundle to bin/prosey

Before publishing to npm, bun run build runs automatically via the prepack hook, producing a Node-compatible JS bundle at bin/prosey.

Configuration

Prosey reads configuration from a TOML file. The location follows the XDG Base Directory Specification (~/.config/prosey/config.toml), or you can set the PROSEY_CONFIG_PATH environment variable to use a custom path.

The config file is created automatically on first run with default values. Use --reset-config to restore the defaults at any time.

pager

Pager command for transcript and summary output. Defaults to "auto", which detects the first available of: bat -lmd --style plain → glow -p → mdcat -l -p → less. Set to a custom command (e.g. "less -R") to override. The PROSEY_PAGER environment variable takes precedence over this setting.

[summarize]

The [summarize] section configures the summarize command:

PROSEY_PAGER

Environment variable to set the pager command. Takes precedence over the pager config value. Set to "auto" or empty to use auto-detection.

Cache

Transcripts and summaries are cached to /tmp/prosey/. Repeated invocations for the same video and options are instant and work offline. Use --no-cache to skip cache reads and force a fresh fetch.

When running prosey summarize, the command runs inside the cache directory for that video. This prevents the AI agent from picking up project-specific files like AGENTS.md or CLAUDE.md from the current folder, and limits its ability to modify files outside that directory.

Exit codes

How it works

prosey uses YouTube's Innertube API via the youtube-transcript-plus library. No API keys or browser automation required.

The tool works with both manually created captions and auto-generated transcripts (YouTube's speech-to-text). Auto-detection falls through languages in the order provided by YouTube's player response.