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:
2. Ghost dashboard → Settings → Integrations
3. Create a new "Custom Integration"

4. Copy the Admin API Key and API URL

5. Store credentials securely:

Option A: Environment Variables (Recommended) bash # 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): ```bash # 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 ```bash 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) ```bash # 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)

1. Install dependencies: bash 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.

1. 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?"