LCYT CLI - Live Captions for YouTube

Command-line tool for sending live captions to YouTube Live streams.

Looking for the library? See lcyt.

Installation

npm install -g lcyt-cli

Or run directly with npx:

npx lcyt-cli

Getting Started

1. Set up your YouTube stream key

lcyt --stream-key "YOUR_STREAM_KEY"

To get your stream key:

1. Go to YouTube Studio
2. Click Create > Go Live
3. In stream settings, find Closed captions
4. Enable POST captions to URL
5. Copy the stream key (cid value)

2. Verify connection (optional)

lcyt --heartbeat

3. Send captions

lcyt "Hello, world!"          # Send a single caption
lcyt -i                       # Start interactive mode
lcyt -f                       # Start full-screen interactive mode

When running via npx lcyt-cli without arguments, it defaults to full-screen mode.

Options

| Option | Alias | Description | |--------|-------|-------------| | --stream-key <key> | -k | YouTube stream key (cid value) | | --base-url <url> | -u | Base ingestion URL (default: http://upload.youtube.com/closedcaption) | | --region <reg> | -r | Region identifier (default: reg1) | | --cue <cue> | | Cue identifier (default: cue1) | | --use-region | | Include region/cue in caption body (optional) | | --interactive | -i | Interactive mode (read from stdin) | | --fullscreen | -f | Full-screen interactive mode with file loading | | --show-config | | Show current configuration | | --heartbeat | | Send heartbeat to verify connection | | --test | | Send test payload from Google docs | | --timestamp <iso> | -t | Manual ISO timestamp override | | --reset | | Reset sequence counter to 0 | | --config <path> | -c | Config file path | | --verbose | -v | Enable verbose output | | --help | -h | Show help | | --version | | Show version number | | --log-stderr | | Write human logs to stderr instead of stdout (env: LCYT_LOG_STDERR=1) |

Interactive Mode (-i)

A simple line-by-line mode that reads from stdin.

lcyt -i

Commands:

• <text> - Send single caption
• timestamp|text - Send with custom timestamp
• /batch [seconds] - Start auto-batch mode (default: 5s)
• /send - Send collected batch immediately
• <empty line> - Send batch (if any captions queued)
• /heartbeat - Send heartbeat
• /status - Show current status
• Ctrl+C - Exit

Batch example

lcyt -i
/batch 10        # Start batch mode with 10 second timeout
Caption 1        # Timer starts here
Caption 2        # Added to batch
Caption 3        # Added to batch
# ... after 10 seconds from first caption, batch auto-sends

Full-Screen Mode (-f)

A rich terminal UI with file loading, navigation, and sent history.

lcyt -f

Keyboard shortcuts

| Key | Action | |-----|--------| | Enter | Send current file line and advance | | Up / k | Move to previous line | | Down / j | Move to next line | | PageUp / PageDown | Move up/down 10 lines | | Tab | Switch focus between input and preview | | h | Show help | | q / Ctrl+C | Quit |

Commands (type in input field)

| Command | Description | |---------|-------------| | /load <file> [line] | Load a text file, optionally jump to line number | | /reload | Reload the current file | | /goto <N> | Jump to line number N | | /batch [seconds] | Toggle batch mode (auto-send after N seconds) | | /send | Send batch immediately | | /status | Show current status | | /heartbeat | Send heartbeat to server | | /quit or /exit | Quit the application | | +N or -N | Shift pointer forward/backward N lines |

Text typed without a / prefix is sent as a custom caption (does not move the file pointer).

Example workflow

lcyt -f

# In the UI:
/load script.txt          # Load a file
/goto 10                  # Jump to line 10

# Press Enter to send the current line and advance
# Use arrow keys to navigate
# Type custom text and press Enter to send ad-hoc captions

/batch 3                  # Enable batch mode (3s auto-send)
# Press Enter multiple times to queue lines rapidly
/send                     # Or send the batch immediately

Sequence

YouTube requires an incrementing sequence counter for each stream. The counter is saved to your config file automatically.

Reset when restarting a stream:

lcyt --reset

Configuration

Config is stored in ~/.lcyt-config.json:

{
  "baseUrl": "http://upload.youtube.com/closedcaption",
  "streamKey": "YOUR_STREAM_KEY",
  "region": "reg1",
  "cue": "cue1",
  "sequence": 42
}

View current config:

lcyt --show-config

Use a custom config file:

lcyt --config /path/to/config.json

Docker / MCP notes

If you run the MCP host or a relay in Docker, rebuild the image after pulling changes so the container picks up the updated CLI behavior (logger stderr option):

# from repo root
docker build -t lcyt-mcp ./packages/lcyt-mcp
# restart your container using the new image
docker rm -f lcyt-mcp-container || true
docker run -d --name lcyt-mcp-container lcyt-mcp

Adjust image name and container commands to match your deployment.

License

MIT