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

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:

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)

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

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/
```

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:

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

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:

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

Weekly content series:

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

Comment management:

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

Analytics check:

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

Ghost CMS

AI Skill Market Insights

Be Part of the 2,275+ Developer Community

Ghost CMS

⚠️ Security Warning

Quick Setup

Self-hosted with reverse proxy (production)

Self-hosted development (Ghost default port 2368)

Self-hosted with custom port

Secure the files (owner read-only)

Use in commands

Tools & Utilities

Snippet Extractor

Validate format before extracting

Preview without saving

Custom marker prefix

Full help

Theme Manager

List all installed themes

Upload theme ZIP

Upload and activate immediately

Activate existing theme

Download theme backup

Delete theme (cannot delete active theme)

Show current active theme

Theme Validator

Validate theme directory

Validate ZIP file

Target specific Ghost version

JSON output for CI/CD

Show only errors (hide warnings)

2. Fix any errors

3. Re-validate

4. Upload when clean

Core Operations

Content Management

Validate format before extracting

Preview without saving

Custom marker format

Full help

Analytics & Insights

Comments & Engagement

Members & Subscribers

Newsletters

API Reference

Common Workflows

Quick Start

Manual Installation

TEAR & SHARE

Tags

Channels

Learn

Compare

Company