Common sticking points
This collects the spots you commonly hit on the way to a first publish. Find by symptom and read only the relevant item. For a symptom not here, copying the error message verbatim into Claude Code and asking is faster.
Python and install
Section titled “Python and install””command not found: python3”
Section titled “”command not found: python3””Python 3 isn’t installed. macOS: brew install python3. Linux and WSL2: sudo apt install -y python3 python3-pip. After installing, check with python3 --version.
”command not found: pip”
Section titled “”command not found: pip””Try pip3 instead of pip.
pip3 install -r scripts/requirements.txtIf that still fails, call it as python3 -m pip install -r scripts/requirements.txt. On a permission error, add --user.
OAuth and credentials
Section titled “OAuth and credentials”Publishing stops at dry-run saying a file is missing
Section titled “Publishing stops at dry-run saying a file is missing”scripts/credentials.json isn’t there. In the Google Cloud console, enable the Blogger API, issue an OAuth client ID of the desktop app type, and save it as scripts/credentials.json. The detailed screen order is in scripts/README.md.
The consent screen doesn’t appear on first publish
Section titled “The consent screen doesn’t appear on first publish”token.json is generated via browser consent on first publish. If the consent window doesn’t appear, check that credentials.json is in place (under scripts/) and was issued as the desktop app type. The consent flow is different if it was issued as a web app type.
”invalid_grant” or token expired
Section titled “”invalid_grant” or token expired”token.json has expired or its permissions changed. Delete scripts/token.json and call publish again; the consent screen reappears and reissues the token.
Blog IDs
Section titled “Blog IDs”I don’t know which blog it’ll go to
Section titled “I don’t know which blog it’ll go to”The list-blogs command shows your Google account’s blog list and IDs. Write the ID of the blog the Korean version goes to into .env’s BLOG_ID_KO, and the English one’s into BLOG_ID_EN.
The post went to the wrong blog
Section titled “The post went to the wrong blog”BLOG_ID_KO and BLOG_ID_EN may be swapped in .env. Check both IDs again and see that the Korean blog and English blog IDs are in their right slots.
The AI-smell gate fail won’t let it publish
Section titled “The AI-smell gate fail won’t let it publish”The post’s AI-flavor score is over 60. Publishing gets blocked on purpose. Read the post once and look at the intro, paragraph lengths, and whether there’s first-person experience. The detailed way out is in when-ai-gets-stuck.
A post got flagged at the AdSense gate
Section titled “A post got flagged at the AdSense gate”A signal that might trip ad policy got caught. Fix the spot the gate pointed at, or if it’s a post you won’t put ads on, decide whether to proceed as is.
ko/en parity
Section titled “ko/en parity”Only the Korean version exists, no English one
Section titled “Only the Korean version exists, no English one”You didn’t run translation, or the slug drifted. Call translation with “make the English version of the post I just wrote,” and confirm with find _workspace/posts/new -iname "*{slug}*" that the two files are paired under the same slug.
Publishing stops at ko/en parity
Section titled “Publishing stops at ko/en parity”The quality gate saw the hreflang cross-reference or structure correspondence between the Korean and English versions drift. Say “realign ko/en parity” and the gate fixes the spot it pointed at.
Publish script
Section titled “Publish script””Permission denied: ./scripts/deploy.sh”
Section titled “”Permission denied: ./scripts/deploy.sh””The script doesn’t have execute permission.
chmod +x scripts/deploy.shPosts I didn’t mean went up together
Section titled “Posts I didn’t mean went up together”That’s when you called publish-new without a slug. Every post in staging becomes a target. To put up just one, narrow with --slug {slug}.
If it still doesn’t resolve
Section titled “If it still doesn’t resolve”Open a GitHub issue or post in the team Slack. Write down three things together.
- Where you got stuck (which step, which command)
- The full error message
- Environment info (operating system, Python version)