You point to the video and give the context. Codex writes the title, description and tags and draws the thumbnail art; yt-pubx applies your brand, publishes to the right channel and hands back the link.
yt-pubx is a command-line program that publishes videos to YouTube for you. It is meant for people who publish often, on one or several channels, and don't want to fill in the title, description, tags and thumbnail by hand every time. From a short text or the video's subtitles, the Codex CLI writes the texts and creates the thumbnail art, and yt-pubx uploads everything through the official YouTube API. To use it, you need Python, a logged-in Codex CLI and a free Google Cloud project with the YouTube Data API enabled.
A single Python file. The configuration and tokens stay on your machine.
A title of up to 90 characters, a description with bullet points and only the links you provided, tags, and the thumbnail phrase and scene. All through your Codex subscription, with no model API key.
The art comes from the Codex image generator; yt-pubx darkens the text side and applies the phrase, the brand label and the colors defined for each channel.
Each channel is one block in config.json and one yt-pubx auth. Pick it with --canal; without it, the video goes to the default channel.
With --dry-run it stops before uploading and shows everything; with --plano it publishes exactly what you reviewed.
Local file, direct .mp4 link or a YouTube, TikTok or Instagram link (downloaded with yt-dlp, or with the command you configure).
Resumable upload in 16 MB chunks with retries. Public, unlisted, private or scheduled with --agendar.
Each upload creates a folder with plano.json, the thumbnail and the art, plus a line in historico.jsonl.
Linux, macOS or Windows (WSL). Nothing lives on a third-party server.
Python 3.10 or newer, with requests and Pillow; ffprobe comes with ffmpeg.
pip install requests pillow ffprobe -version
Logged in to your ChatGPT account. It is what writes the texts and draws the art.
npm i -g @openai/codex codex login
A free project with the YouTube Data API v3 enabled and an OAuth client ID of type "Desktop app" (step 2 of the guide).
# optional, for links pip install yt-dlp
Steps 2 to 4 are done once per channel. After that, publishing is just step 5.
Clone the repository, put the command on your PATH and generate the sample file at ~/.config/yt-pubx/config.json.
git clone https://github.com/inematds/yt-pubx.git cd yt-pubx && ln -s "$PWD/yt-pubx" ~/.local/bin/yt-pubx yt-pubx init
At console.cloud.google.com: create a project; under APIs & Services → Library enable the YouTube Data API v3; on the OAuth consent screen choose "External" and add the email of the account that owns the channel as a test user; under Credentials → Create credentials → OAuth client ID choose Desktop app and download the JSON.
# keep the JSON outside any repository mv ~/Downloads/client_secret_*.json ~/.config/yt-pubx/
Name, one sentence about the channel (it sets the tone of the texts), the line that closes every description and the thumbnail identity.
"principal": {
"nome": "My Channel",
"sobre": "Short smartphone photography tutorials.",
"assinatura": "Subscribe: https://www.youtube.com/@meucanal",
"idioma": "pt", "categoria": "27", "privacy": "public",
"thumb": { "marca": "MY CHANNEL", "cor_marca": "#f0e805", "cor_destaque": "#f91f06" }
}
It opens the browser; sign in with the account that owns the channel and accept. The token is stored in ~/.config/yt-pubx/tokens/ with permission 600. For another channel, create another block and repeat with its name.
yt-pubx auth principal --client-secret ~/.config/yt-pubx/client_secret_XXXX.json yt-pubx canais # * principal My Channel ... ok
--dry-run generates the title, description, tags and thumbnail and shows everything without publishing. Open the thumb.jpg in the folder it points to.
yt-pubx publicar aula.mp4 --legenda aula.srt \ --contexto "Lesson 3 of course X. Page: https://exemplo.com/curso" --dry-run # PLANO: ~/.local/share/yt-pubx/trabalhos/20261007-163325-aula-mp4/plano.json
--plano reuses the text and the art without generating them again. You can change just the thumbnail phrase. At the end you get the video link and the Studio link.
yt-pubx publicar aula.mp4 --plano ~/.local/share/yt-pubx/trabalhos/<folder>/plano.json \ --frase-thumb "From zero to live" # URL: https://www.youtube.com/watch?v=...
Another channel, a link instead of a file, scheduling, or everything by hand without Codex.
yt-pubx publicar https://exemplo.com/video.mp4 --canal segundo --contexto "..." yt-pubx publicar video.mp4 --contexto "..." --agendar "2026-12-01 18:00" yt-pubx publicar video.mp4 --title "..." --description "..." --tags "a,b" --thumb capa.jpg yt-pubx atualizar https://www.youtube.com/watch?v=XXXXXXXXXXX --description-arquivo descricao.txt # edit a video that is already published
Put this instruction in your agent's CLAUDE.md or AGENTS.md; then just ask "publish this video on channel X".
# Publish a video to YouTube
Gather the context (topic, official links, SRT), run
yt-pubx publicar <video> --contexto "..." --dry-run, open thumb.jpg,
check the title and description and publish with --plano <folder>/plano.json.
App in Testing mode: access expires in 7 days; publish the app on the consent screen so it doesn't expire. Unaudited project: YouTube may lock videos from new projects as private until the YouTube API Services audit (free). Quota: 10,000 units per day; each upload uses a good part of it. Custom thumbnail: requires a phone-verified channel.
Art from Codex image_gen, phrase and brand applied by yt-pubx with each channel's colors.
--canal.What already works today and what may come next.
yt-pubx auth, thumbnail composer, --dry-run and --plano, scheduling, SRT subtitles.