ytmogo

README

🎵 ytmogo — YouTube Music, but make it terminal.

Power CLI for YouTube Music using your browser cookies. Search, browse, manage your library and playlists, and script it all with --json / --plain.

Built on the same idea as spogo: no developer app, no OAuth dance, no API quota — just the cookies your browser already has.

Features

• Search songs, videos, albums, artists, playlists, podcasts and episodes
• Search suggestions, library-scoped search, exact (no spelling correction) search
• Item info: song, album, artist, playlist, podcast, episode
• Library: songs, albums, artists, playlists, subscriptions, podcasts
• Ratings: like / dislike / clear on songs, save / remove albums
• Subscriptions: subscribe and unsubscribe from artists
• Playlists: create, delete, add tracks, remove tracks, list tracks
• Listening history and account identity
• Queue: what YouTube would play next for a track or playlist
• Playback on a paired screen — TV, console, Chromecast — over the cast (lounge) protocol: play, pause, next, prev, seek, volume, status
• --json and --plain for scripting, colorized human output otherwise (respects NO_COLOR, TERM=dumb, --no-color)

Why cookies?

YouTube Music has no public API for any of this. The Data API v3 covers YouTube, not YouTube Music: it cannot read your Music library, your liked songs, or your Music playlists, and it burns a daily quota for what it does cover.

ytmogo talks to the same internal InnerTube endpoints music.youtube.com uses, authenticated with the cookies your browser already holds:

• No app registration — no client id, no redirect URI, no consent screen
• No quota — the same endpoints the web player calls
• Full library access — everything the web player can read, ytmogo can read
• Agent-friendly — stable JSON out, documented exit codes

About playback

YouTube Music has no equivalent of Spotify Connect — no internal endpoint presses play on another device. What it does have is MDX/lounge, the protocol behind "Watch on TV", and ytmogo speaks it. Point it at a screen and you get real remote control:

ytmogo device discover --add    # finds screens on your network, no code needed
ytmogo play 7h7t0jzCYIY
ytmogo status
ytmogo volume 40

Two limits worth knowing before you try:

• Only receivers can be targets. TVs, consoles, Chromecasts, and a browser on youtube.com/tv announce themselves as screens. A phone running the YouTube or YouTube Music app is a remote, not a screen, so it can never be a playback target — that is a property of the protocol, not a missing feature.
• ytmogo itself plays nothing. There is no local player. ytmogo stream resolves media URLs, but YouTube ciphers them for the web client, so expect to hand the video id to yt-dlp instead.

The lounge protocol is undocumented and Google changes it without notice. It is the most fragile part of ytmogo. See docs/devices.md.

Install

Needs Go 1.25 or newer.

Latest release — a fixed version, what you want unless you have a reason not to:

go install github.com/jadilson12/ytmogo/cmd/ytmogo@latest

Or pin one explicitly:

go install github.com/jadilson12/ytmogo/cmd/ytmogo@v0.0.2

Latest main — unreleased work, may break:

go install github.com/jadilson12/ytmogo/cmd/ytmogo@main

From a checkout — for hacking on it:

git clone https://github.com/jadilson12/ytmogo.git
cd ytmogo
make ytmogo      # builds ./ytmogo
make test

go install puts the binary in $(go env GOPATH)/bin; add that to your PATH if ytmogo is not found afterwards.

Quick start

ytmogo auth import --browser chrome
ytmogo user account
ytmogo search song "wonderwall" --limit 5
ytmogo library playlists list
ytmogo playlist tracks LM --limit 10

# playback, if you have a TV or Chromecast on the network
ytmogo device discover --add
ytmogo play ZrOKjDZOtkA

Usage

ytmogo [global flags] <command> [args]

Global flags:

• --config <path> config file path
• --profile <name> profile name
• --timeout <dur> request timeout (default 10s)
• --location <cc> country code (InnerTube gl)
• --language <tag> language/locale (InnerTube hl)
• --device <name> paired screen to control
• --json / --plain
• --no-color
• -q, --quiet / -v, --verbose / -d, --debug
• --no-input

Commands:

• completion bash|zsh|fish
• auth status|import|paste|clear
• search song|video|album|artist|playlist|podcast|episode|all|suggest
• song info|like|dislike|unlike
• album info|save|remove
• artist info|subscribe|unsubscribe
• playlist info|tracks|create|delete|add|remove
• podcast info, episode info
• library songs|albums|artists|playlists|subscriptions|podcasts list
• user account|history
• queue <id|url>
• stream <id|url>
• device discover|pair|list|set|forget
• play [<id|url>], pause, next, prev, stop, seek, volume, status

Full spec: docs/spec.md. Auth: docs/auth.md. Playback devices: docs/devices.md.

Cookies

ytmogo auth import --browser chrome
ytmogo auth import --browser brave --browser-profile "Profile 1"

If your browser's cookie store cannot be decrypted (WSL, locked keychain), copy the whole cookie: request header out of DevTools and paste it:

ytmogo auth paste

Cookies are stored per profile under your config directory. See docs/auth.md for which cookies matter and where they live.

Output

• Human output by default
• --plain for line-oriented, tab-separated output
• --json for structured output

Legal

This tool talks to YouTube's internal web endpoints with your own session. Use it responsibly and in accordance with YouTube's Terms of Service.

License

MIT