Ghost CMS

Manage Ghost blog content, members, analytics, and newsletters through the Ghost Admin API.

⚠️ Security Warning

Ghost Admin API keys provide FULL access to your Ghost site:

• Content Management: Create, update, delete, publish posts and pages
• Member Management: Add, modify, delete members and subscriptions
• Subscription Management: Create, modify, delete membership tiers
• Comment Management: Reply to, approve, delete comments
• User Management: Invite, modify, delete users
• Media Management: Upload images and files (affects storage)
• Site Configuration: Modify newsletters and settings

Security Best Practices:

• Store API keys securely - Use 1Password CLI or secure env vars
• Review before publishing - Always check content before making it public
• Never commit keys - Keep credentials out of version control
• Rotate keys regularly - Create new integrations every 90 days
• Use dedicated integrations - Separate keys for different use cases
• Test on staging first - Use a test Ghost site when possible

Operation Types:

Read-Only Operations (✅ Safe):

• List posts, pages, tags, members, tiers, newsletters, comments
• Get analytics and member stats
• All GET requests

• Create/update/delete posts, pages, tags (POST, PUT, DELETE)
• Publish/unpublish/schedule posts (makes content public)
• Create/update/delete members, tiers, newsletters
• Create replies, approve/delete comments
• Upload images (uses storage quota)
• All POST, PUT, DELETE requests

Quick Setup

• Get your Ghost Admin API credentials:
• Ghost dashboard → Settings → Integrations
• Create a new "Custom Integration"
• Copy the Admin API Key and API URL
• Store credentials securely:

# Add to your shell profile (~/.zshrc, ~/.bashrc)
   export GHOST_ADMIN_KEY="YOUR_ADMIN_API_KEY"
   export GHOST_API_URL="YOUR_GHOST_URL"

API URL Examples (works with ALL hosting types):

# Ghost(Pro) hosted
   export GHOST_API_URL="https://yourblog.ghost.io"
   
   # Self-hosted with reverse proxy (production)
   export GHOST_API_URL="https://blog.yourdomain.com"
   
   # Self-hosted development (Ghost default port 2368)
   export GHOST_API_URL="http://localhost:2368"
   
   # Self-hosted with custom port
   export GHOST_API_URL="https://ghost.example.com:8080"

Important:

• Always include protocol (http:// or https://)
• Include :PORT if Ghost runs on non-standard port
• Do NOT include trailing slash
• Do NOT include /ghost/api/admin (added automatically)

mkdir -p ~/.config/ghost
   echo "YOUR_ADMIN_API_KEY" > ~/.config/ghost/api_key
   echo "YOUR_GHOST_URL" > ~/.config/ghost/api_url
   
   # Secure the files (owner read-only)
   chmod 600 ~/.config/ghost/api_key
   chmod 600 ~/.config/ghost/api_url

Option C: 1Password CLI (Most Secure)

# Store key in 1Password
   op item create --category=API_CREDENTIAL \
     --title="Ghost Admin API" \
     admin_key[password]="YOUR_ADMIN_API_KEY" \
     api_url[text]="YOUR_GHOST_URL"

   # Use in commands
   export GHOST_ADMIN_KEY=$(op read "op://Private/Ghost Admin API/admin_key")
   export GHOST_API_URL=$(op read "op://Private/Ghost Admin API/api_url")

Security Notes:

• Keys provide full site access - protect them like passwords
• Rotate keys every 90 days (create new integration, revoke old)
• Never commit to git or share keys publicly
• Consider separate keys for production vs. staging
• HTTPS recommended: Use HTTPS for production (HTTP acceptable for localhost only)
• Install dependencies:

cd ghost-cms-skill/scripts
   npm install

Dependencies installed:

• form-data (^4.0.5) - Multipart file uploads (theme ZIP files)
• jsonwebtoken (^9.0.3) - JWT token generation for Ghost Admin API authentication

• gscan (^5.2.4) - Official Ghost theme validator (from TryGhost)
• Only needed for theme validation feature
• Install with: cd scripts && npm install gscan

• Test connection:

Tools & Utilities

Snippet Extractor

Purpose: Migrate existing Ghost snippets to local library for programmatic use.

Why needed: Ghost Admin API blocks snippet access (403 Forbidden) for integration tokens. This tool works around that limitation.

Usage:

# Extract snippets from a specially-formatted draft post
node scripts/snippet-extractor.js my-snippets-post

# Validate format before extracting
node scripts/snippet-extractor.js my-snippets-post --validate

# Preview without saving
node scripts/snippet-extractor.js my-snippets-post --dry-run

# Custom marker prefix
node scripts/snippet-extractor.js my-snippets-post --marker "This is:"

# Full help
node scripts/snippet-extractor.js --help

Workflow:

• Create draft post in Ghost
• For each snippet: add paragraph marker (e.g., "SNIPPET: name" or "This is: name")
• Insert the snippet content below each marker
• Run extractor → all snippets saved to snippets/library/

• ✅ Extracts all card types (bookmarks, callouts, images, markdown, HTML, etc.)
• ✅ Preserves exact Lexical structure
• ✅ Auto-detects credentials from ~/.config/ghost/ or env vars
• ✅ Supports custom marker formats
• ✅ Dry-run and validation modes
• ✅ Verbose output for debugging

# User has 12 snippets in Ghost
# Creates "My Snippets" draft with markers
# Runs: node scripts/snippet-extractor.js my-snippets --marker "This is:"
# Result: All 12 snippets in library/ ready for use

See snippets/README.md for complete documentation.

Theme Manager

Purpose: Upload, activate, switch, and manage Ghost themes programmatically.

Why needed: Automate theme deployments, switch themes, manage theme versions.

Usage:

cd scripts

# List all installed themes
node theme-manager.js list

# Upload theme ZIP
node theme-manager.js upload /path/to/theme.zip

# Upload and activate immediately
node theme-manager.js upload /path/to/theme.zip --activate

# Activate existing theme
node theme-manager.js activate theme-name

# Download theme backup
node theme-manager.js download theme-name backup.zip

# Delete theme (cannot delete active theme)
node theme-manager.js delete old-theme

# Show current active theme
node theme-manager.js active

Features:

• ✅ Upload custom themes from ZIP files
• ✅ Switch between installed themes
• ✅ Download theme backups
• ✅ Delete unused themes
• ✅ Validation and error handling
• ✅ Immediate activation - theme changes are public instantly

• Theme activation is immediate and public - site appearance changes instantly
• Cannot delete the currently active theme (switch first)
• Themes must be valid Ghost theme ZIP files

# Safe theme switching with rollback
node theme-manager.js active              # Note current theme
node theme-manager.js activate new-theme  # Switch to new theme
# Test site in browser
node theme-manager.js activate old-theme  # Rollback if needed

See references/themes.md for complete theme management documentation and best practices.

Theme Validator

Purpose: Validate Ghost themes before uploading using official gscan validator.

⚠️ Optional Feature: Requires gscan package. Install with:

cd scripts
npm install gscan

Why needed: Catch errors early - missing files, invalid syntax, deprecated helpers, version incompatibility.

Usage:

cd scripts

# Validate theme directory
node theme-validator.js ~/themes/my-theme/

# Validate ZIP file  
node theme-validator.js theme.zip

# Target specific Ghost version
node theme-validator.js theme.zip --version v6

# JSON output for CI/CD
node theme-validator.js theme.zip --json

# Show only errors (hide warnings)
node theme-validator.js theme.zip --errors-only

Features:

• ✅ Official Ghost validator (gscan from TryGhost)
• ✅ Same validation as Ghost Admin
• ✅ Validates directories or ZIP files
• ✅ Ghost v5/v6 compatibility checking
• ✅ Finds deprecated helpers and syntax errors
• ✅ CI/CD integration (JSON output, exit codes)
• ✅ Categorized issues (errors, warnings, recommendations)

• Errors - Must fix before upload (theme will be rejected)
• Warnings - Should fix for best compatibility
• Recommendations - Nice to have (best practices)

# 1. Validate before upload
node theme-validator.js my-theme.zip

# 2. Fix any errors

# 3. Re-validate
node theme-validator.js my-theme.zip

# 4. Upload when clean
node theme-manager.js upload my-theme.zip

CI/CD integration:

node theme-validator.js theme.zip --json
if [ $? -eq 0 ]; then
  node theme-manager.js upload theme.zip --activate
fi

Exit codes: 0 = valid, 1 = errors found, 2 = invalid arguments

See references/themes.md for complete validation documentation and common error fixes.

Core Operations

This skill covers all major Ghost operations. Navigate to the relevant reference for detailed guidance:

Content Management

See content.md for:

• Creating new posts (drafts)
• Publishing and scheduling posts
• Updating existing content
• Managing tags, featured images, metadata
• Working with pages vs posts

• Complete Lexical card type reference (23 documented types)
• Most comprehensive Ghost Lexical documentation available
• Full JSON structures with field references
• Video, audio, file uploads, buttons, toggles, embeds
• Product cards, headers, call-to-action, paywall
• Member visibility and content personalization

Ghost's native snippet feature (reusable content blocks saved in the editor) cannot be accessed via the Admin API with integration tokens (403 Forbidden). This means:

• ❌ Cannot list available snippets
• ❌ Cannot fetch snippet content
• ❌ Cannot programmatically use author's existing snippets

The skill includes a snippet extractor tool that migrates Ghost snippets to local files:

• Create extraction post in Ghost with all snippets (one-time setup)
• Run extractor: node scripts/snippet-extractor.js post-slug
• Done! All snippets saved to snippets/library/ for programmatic use

# Extract snippets (auto-detects credentials from ~/.config/ghost/)
node scripts/snippet-extractor.js my-snippets-post

# Validate format before extracting
node scripts/snippet-extractor.js my-snippets-post --validate

# Preview without saving
node scripts/snippet-extractor.js my-snippets-post --dry-run

# Custom marker format
node scripts/snippet-extractor.js my-snippets-post --marker "This is:"

# Full help
node scripts/snippet-extractor.js --help

Benefits:

• ✅ Migrate all existing Ghost snippets in seconds
• ✅ Preserves exact Lexical structure (bookmarks, callouts, images, etc.)
• ✅ Git version control
• ✅ Use programmatically in automated posts
• ✅ Works with any card types

Analytics & Insights

See analytics.md for:

• Subscriber growth and counts
• Most popular posts (views, engagement)
• Tag/topic performance over time
• Member tier distribution

Comments & Engagement

See comments.md for:

• Listing pending/unanswered comments
• Responding to comments
• Comment moderation

Members & Subscribers

See members.md for:

• Subscriber tier management
• Member-only content settings
• Recent subscriber activity
• Subscription status

Newsletters

See newsletters.md for:

• Newsletter configuration
• Sending newsletters
• Subscriber email settings

API Reference

For advanced operations or endpoint details, see api-reference.md.

Common Workflows

Draft → Notion → Ghost:

• Draft content collaboratively in Notion
• Finalize content
• Use this skill to copy to Ghost as draft
• Review in Ghost admin
• Schedule or publish

• "Navi, write and publish a unique weekly post about [topic from our discussions this week]"
• Skill creates post, sets author to "Navi", publishes automatically

• "Are there any pending comments?"
• Review list of comments with post titles
• "Respond to comment #123 with [response]"

• "What tags have been most popular in the past 6 months?"
• "How many new subscribers this month?"
• "When was my last subscriber-exclusive post?"