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

Published content is IMMEDIATELY PUBLIC - be extra careful with publish operations.

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

Admin API Key Scope: Ghost Admin API keys have no scoping options - they provide full access to everything. There are no read-only keys.

Operation Types:

Read-Only Operations (✅ Safe):

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

Destructive Operations (⚠️ Modify or delete data, may be public):

• 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

For detailed operation documentation, see api-reference.md.

Quick Setup

1. Get your Ghost Admin API credentials:

   • Ghost dashboard → Settings → Integrations
   • Create a new "Custom Integration"
   • Copy the Admin API Key and API URL

2. Store credentials securely:

   Option A: Environment Variables (Recommended)

   # 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)

   Option B: Config Files

   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)

3. 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

   Optional dependencies (install manually if needed):

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

   All dependencies from public npm registry. No custom downloads.

4. Test connection: See setup.md for detailed authentication and troubleshooting.

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:

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

Features:

• ✅ 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

Example:

# 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

⚠️ Important:

• 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

Workflow:

# 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)

Validation levels:

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

Safe deployment workflow:

# 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

When to use: Creating drafts, publishing posts, scheduling content, managing pages

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

See lexical-cards.md for:

• 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 Snippets Limitation:

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

Solution: Automated Snippet Extraction

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

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

Commands:

# 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

See snippets/README.md for complete documentation on extraction workflow and local snippet usage.

Analytics & Insights

When to use: Checking subscriber counts, popular content, traffic trends

See analytics.md for:

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

Comments & Engagement

When to use: Responding to comments, moderating discussions

See comments.md for:

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

Members & Subscribers

When to use: Managing subscriber tiers, member access, premium content

See members.md for:

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

Newsletters

When to use: Managing newsletter settings, email campaigns

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:

1. Draft content collaboratively in Notion
2. Finalize content
3. Use this skill to copy to Ghost as draft
4. Review in Ghost admin
5. Schedule or publish

Weekly content series:

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

Comment management:

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

Analytics check:

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