| name | youtube-shorts-publish |
| description | Inspect, plan, authenticate, upload, schedule, and verify YouTube Shorts through the official YouTube Data API, for the user's own channel. Use whenever someone asks to upload, publish, post, or schedule a YouTube Short; check whether a video qualifies as a Short; safely dry-run a YouTube upload; configure YouTube upload OAuth; diagnose a Short stuck processing, rejected, or unexpectedly private; or verify an upload by video ID. Handles local ffprobe media checks, Desktop OAuth, private-by-default resumable uploads, Made for Kids and synthetic-media declarations, and post-upload processing checks. Not for generating or editing the video, bulk multi-channel posting, evading platform enforcement, or claiming Shorts Feed placement that the API cannot prove.
|
Publish YouTube Shorts safely
Use the bundled zero-dependency Node CLI. It separates local eligibility, API acceptance, video
processing, visibility, and Shorts classification instead of treating them as one success state.
Non-negotiable safety rules
- Work with one channel owned or controlled by the user. Never rotate accounts, proxies, or OAuth
clients to evade quotas or enforcement.
- Run a dry plan before every upload.
plan never reads OAuth files, contacts Google, or writes
local state. publish without --yes has the same guarantee.
- Only add
--yes and the reviewed --expected-plan-id when the user's request clearly authorizes
that exact upload and the plan's channel, source SHA-256, title, visibility, schedule, and
declarations match their intent.
- Keep the default
private unless the user explicitly asks for public, unlisted, or a future
publication time. Scheduling a private video means it will become public later.
- Never infer whether content is Made for Kids or contains realistic altered/synthetic media.
Obtain explicit
yes or no choices for both.
- Use the channel ID returned by
auth; the CLI refuses a write if the authorized channel differs.
- Treat a
plan_id as one-shot. Before creating an upload session, the CLI stores a receipt and a
read-only snapshot matching the reviewed SHA-256. A previous receipt blocks the same plan by
default, including after crashes and ambiguous responses.
- After an upload returns an ID, check that ID. Never search by title, delete a same-title video,
or blindly upload again because processing or verification timed out.
- Call an eligible upload a Shorts candidate. The Data API has no Shorts classification field,
so do not claim confirmed Shorts Feed placement.
Locate the CLI
Commands below assume the current directory is this skill directory. Otherwise use the absolute
path to scripts/ytshorts.mjs. Pass an absolute path for the source video when changing directories.
node scripts/ytshorts.mjs --help
node scripts/ytshorts.mjs doctor
Requirements are Node.js 20+ and ffprobe. There are no npm runtime dependencies.
Verify the installed contract without YouTube
Run node examples/verify-zero-publish.mjs with no arguments. It generates and removes a local
one-second portrait fixture, then exercises only inspect and plan. It does not run auth,
status, publish, or --yes; it points OAuth paths at absent sentinels and runs both CLI commands
under a network guard that first passes a deliberately blocked canary. Return its compact stdout
unchanged when the user asks for the evaluation result.
Treat passed: true only as a deterministic installation and safety-contract check. It does not
prove that a real upload will succeed or that YouTube will place media in the Shorts Feed. The
verifier requires ffmpeg as well as ffprobe; both are provided by FFmpeg.
After an independent installed-copy run, use the structured zero-publish tester form.
Choose completed only if the reporter independently installed and actually ran
youtube-shorts-publish for their own non-internal purpose and is not a maintainer, a maintainer's
teammate, or an internal tester. Use the incomplete outcome when the exact no-argument verifier did
not finish, and never include OAuth data, tokens, client secrets, authorization codes, resumable
URLs, a real channel ID, or personal paths. This is installation and safety-contract evidence, not
proof of a live upload or Shorts Feed placement.
First-time authorization
Read OAuth setup, then run:
node scripts/ytshorts.mjs auth
The system browser handles Google consent through a Desktop-app loopback flow. It requests
youtube.upload for insertion and youtube.readonly for the channel guard and owner-only status
read-back. Record the returned channel_id; pass it to every plan and publish command. Never open
or print the token file. If authorization is not needed for the current task, do not run auth
speculatively.
Inspect local media
node scripts/ytshorts.mjs inspect /absolute/path/short.mp4
Treat shorts_candidate: true as a local check against the published duration and displayed aspect
rules. Rotation and sample aspect ratio are applied before deciding whether the video is square or
vertical. A missing audio track is only a warning. Landscape media, unknown duration, or duration
over 180 seconds blocks publishing.
If the video needs conversion, let the user choose crop versus padding and then consult
media preparation. Do not silently alter their composition.
Build an exact, side-effect-free plan
node scripts/ytshorts.mjs plan /absolute/path/short.mp4 \
--title "Launch day in 30 seconds" \
--description-file /absolute/path/description.txt \
--channel-id UCxxxxxxxxxxxxxxxxxxxxxx \
--privacy private \
--made-for-kids no \
--contains-synthetic-media no
Useful metadata flags:
--tag value is repeatable; comma-separated values also work.--category-id 22 defaults to People & Blogs.--notify-subscribers yes|no defaults to no.--default-language en sets the metadata language.--publish-at 2026-08-10T09:00:00+08:00 requires --privacy private and represents future
public visibility. It must remain at least 30 minutes away throughout session creation and chunk
transfer; otherwise the CLI stops rather than risk a past timestamp becoming public immediately.
Inspect safe_to_publish, blocking_issues, warnings, target, source sha256, plan_id, and
the exact API request (including notifySubscribers). Resolve every blocker before proceeding.
The channel is verified online only after confirmation; the plan marks that explicitly.
Publish only after reviewing the plan
The same command without --yes is still a dry run:
node scripts/ytshorts.mjs publish /absolute/path/short.mp4 \
--title "Launch day in 30 seconds" \
--channel-id UCxxxxxxxxxxxxxxxxxxxxxx \
--privacy private \
--made-for-kids no \
--contains-synthetic-media no
For a user-authorized real upload, repeat the unchanged command with the dry run's plan_id and
--yes:
node scripts/ytshorts.mjs publish /absolute/path/short.mp4 \
--title "Launch day in 30 seconds" \
--channel-id UCxxxxxxxxxxxxxxxxxxxxxx \
--privacy private \
--made-for-kids no \
--contains-synthetic-media no \
--expected-plan-id PLAN_ID_FROM_DRY_RUN \
--yes
The CLI hashes the video and canonical request again before touching OAuth. A changed video,
description file, metadata flag, or target produces PLAN_CHANGED and no upload starts. After the
channel check it copies those reviewed bytes to a 0400 local snapshot and atomically creates an
operation receipt immediately before mutation.
The uploader creates one resumable session, sends fixed 8 MiB chunks, follows YouTube's 308 Range
offset after interruptions, renews OAuth access before expiry without restarting the session, and
polls the returned video ID for up to 60 seconds by default. Set --wait-seconds 0..900 to change
that window. Progress goes to stderr; structured results go to stdout.
One plan_id gets one upload attempt by default. Receipts live under the configured
operations/ directory and contain no OAuth token or resumable session URL. If a prior attempt is
ambiguous, inspect its receipt and YouTube Studio. Only after confirming no video exists may the
user explicitly authorize the same command with --new-attempt; never add that flag automatically.
The CLI permits at most one such exceptional retry and refuses it when any prior receipt already
contains a video ID. It also requires the primary receipt itself to say ambiguous; a preparing or
active-looking receipt is fail-closed so a second process cannot upload concurrently.
Interpret and recheck the result
| state | meaning | next action |
|---|
uploaded_processing | bytes arrived; YouTube is still processing | wait, then run status; do not re-upload |
processed_private | processing succeeded; actual visibility is private | review metadata or publish manually when intended |
processed_unlisted / processed_public | processing and requested visibility succeeded | report success, still as a Shorts candidate |
processed_scheduled | processing succeeded and future public release remains scheduled | report the schedule and preserve private-until-publish state |
processing_failed / rejected | YouTube failed or rejected the video | report the returned reason; fix before a new upload |
verification_timeout | a video ID exists, but the wait window ended | run status VIDEO_ID; do not re-upload |
not_found_after_insert | ID returned but read-back is not visible yet | preserve the ID and recheck; treat outcome as unresolved |
node scripts/ytshorts.mjs status VIDEO_ID
node scripts/ytshorts.mjs status VIDEO_ID --wait-seconds 120
If public or unlisted was requested but read-back says private, report privacy_restricted and
explain that an unaudited API project is a common cause. Do not auto-update visibility. Read
YouTube API and Shorts behavior before diagnosing policy,
quota, Content ID, scheduling, or classification behavior.
For publish, top-level upload_accepted: true means YouTube returned a video ID. Top-level
ok: true requires semantic verification too. A false ok with a video ID is not permission to
retry; follow verification.state and the receipt.
Troubleshooting
| symptom | likely cause | response |
|---|
FFPROBE_NOT_FOUND | ffprobe is not installed or not on PATH | install FFmpeg or set YTSHORTS_FFPROBE_BIN |
CLIENT_SECRETS_NOT_FOUND | Desktop OAuth JSON is not configured | follow references/oauth-setup.md |
OAUTH_REAUTH_REQUIRED | token revoked/expired; Testing projects often expire it after 7 days | run auth again; review consent-screen publishing status |
OAUTH_REFRESH_TOKEN_REQUIRED | stored authorization cannot renew during a long upload | run auth again; do not substitute a short-lived access token |
CHANNEL_MISMATCH | Google authorized a different channel | stop; authorize/select the intended channel or correct --channel-id |
PLAN_CHANGED | source bytes or normalized request differ from the reviewed dry run | inspect the new plan; never reuse the old ID |
PLAN_ALREADY_ATTEMPTED | this exact plan already has a durable receipt | inspect the receipt and Studio; default is never retry |
PLAN_VIDEO_ALREADY_EXISTS | a prior receipt already records a YouTube video ID | check that video; this plan is permanently ineligible for retry |
PRIOR_ATTEMPT_NOT_AMBIGUOUS | the prior receipt is preparing, active-looking, or completed | do not override it; this prevents concurrent duplicate uploads |
UPLOAD_OUTCOME_AMBIGUOUS | a session started but completion could not be proven | do not repeat; inspect Studio, then require explicit user approval for --new-attempt if absent |
| requested public, actual private | API project may require a YouTube compliance audit | keep the video private and follow Google's audit path |
| state remains processing | normal asynchronous transcode or an eventual processing issue | re-run status; never duplicate the upload |
Do not expose OAuth codes, bearer/refresh tokens, client secrets, or resumable session URLs in chat,
logs, commits, or issue reports.
