Ghost CLI

A powerful, modern CLI tool for managing Ghost CMS deployments, built with TypeScript and Bun. Ghost CLI provides a fast, type-safe interface for managing posts, pages, members, tags, and media across multiple Ghost sites with ease.

Features

• Resource Management - Complete CRUD operations for posts, pages, members, and tags
• Batch Operations - Bulk publishing, unpublishing, label management with concurrency control
• Multi-profile Configuration - Manage multiple Ghost sites with named profiles
• Advanced Filtering - Type-safe filter builder with Ghost's query syntax
• Media Upload - Upload images with validation and automatic markdown generation
• Export & Backup - Full site exports with posts, pages, tags, and authors
• Secure Credentials - API keys stored with 0600 file permissions
• Environment Overrides - Override configuration with environment variables
• JWT Authentication - Secure authentication for Ghost Admin API
• Type-safe - Built with TypeScript in strict mode with Zod validation
• Docker Support - Containerized deployments
• Comprehensive CI/CD - Automated testing, linting, and deployment

Prerequisites

• Bun >= 1.0.0 (recommended) or npm >= 9.0.0
• Node.js >= 18.0.0 (if using npm)
• Docker (optional, for containerized usage)
• A Ghost CMS instance with Admin API credentials

Installation

Using Bun (Recommended)

git clone https://github.com/agileguy/ghost-cli.git
cd ghost-cli
bun install
bun run build

Using npm

git clone https://github.com/agileguy/ghost-cli.git
cd ghost-cli
npm install
npm run build

Using Docker

docker pull registry.digitalocean.com/agileguy/ghost-cli:latest

Quick Start

1. Configure Ghost Site

Create a configuration file at ~/.ghost-cli/config.json:

{
  "version": "1.0",
  "currentProfile": "default",
  "profiles": {
    "default": {
      "name": "default",
      "url": "https://yourghost.com",
      "adminApiKey": "your-admin-api-key",
      "contentApiKey": "your-content-api-key"
    }
  }
}

Or use environment variables:

export GHOST_URL="https://yourghost.com"
export GHOST_ADMIN_API_KEY="your-admin-api-key"
export GHOST_CONTENT_API_KEY="your-content-api-key"

2. Basic Commands

# List all posts
ghost posts list

# Create a new post
ghost posts create --title "My First Post" --content "<p>Hello World!</p>"

# Publish a draft post
ghost posts publish <post-id>

# List members
ghost members list --limit 50

# Upload an image
ghost media upload ./image.jpg

# Export entire site
ghost export full --output ./backup

Command Overview

| Command | Description | |---------|-------------| | ghost posts | Manage blog posts (list, create, update, delete, publish) | | ghost pages | Manage static pages | | ghost members | Manage site members | | ghost tags | Manage content tags | | ghost media | Upload and manage media files | | ghost export | Export content and create backups | | ghost version | Show CLI version information |

For detailed command documentation, see docs/COMMANDS.md.

Configuration

Configuration File

Ghost CLI stores configuration in ~/.ghost-cli/config.json with secure 0600 permissions.

Structure:

{
  "version": "1.0",
  "currentProfile": "default",
  "profiles": {
    "default": {
      "name": "default",
      "url": "https://example.com",
      "adminApiKey": "id:secret",
      "contentApiKey": "contentkey",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "lastModified": "2024-01-01T00:00:00.000Z",
      "lastUsed": "2024-01-01T00:00:00.000Z"
    },
    "production": {
      "name": "production",
      "url": "https://blog.example.com",
      "adminApiKey": "prod-id:prod-secret",
      "contentApiKey": "prod-contentkey"
    }
  }
}

Getting Your API Keys

1. Log in to your Ghost Admin panel
2. Navigate to Settings → Integrations
3. Create a new Custom Integration
4. Copy the Admin API Key and Content API Key

Multiple Profiles

Use the --profile flag to target specific sites:

ghost posts list --profile production
ghost posts create --title "Hello" --profile staging

Environment Variables

Environment variables take precedence over config files:

# Required
export GHOST_URL="https://example.com"

# At least one API key required
export GHOST_ADMIN_API_KEY="id:secret"         # For write operations
export GHOST_CONTENT_API_KEY="contentkey"      # For read operations

Filter Syntax

Ghost CLI supports Ghost's powerful filter syntax for querying resources:

# Filter by status
ghost posts list --status published

# Filter by tag
ghost posts list --tag getting-started

# Filter by author
ghost posts list --author john-doe

# Featured posts only
ghost posts list --featured

# Combine filters with custom query
ghost posts list --filter "status:published+tag:news"

Filter Operators:

• : - Equals
• :> - Greater than
• :>= - Greater than or equal
• :< - Less than
• :<= - Less than or equal
• :~ - Contains (case-insensitive)
• :!~ - Does not contain

Combining Filters:

• + - AND (all conditions must match)
• , - OR (any condition must match)

See docs/COMMANDS.md#filter-syntax for more examples.

Development

Local Development

# Run in development mode
bun run dev

# Run tests
bun test

# Lint code
bun run lint

# Fix linting issues
bun run lint:fix

# Type check
bun run typecheck

# Build for production
bun run build

# Run production build
bun start

Project Structure

ghost-cli/
├── src/
│   ├── index.ts              # CLI entry point
│   ├── commands/             # Command implementations
│   │   ├── posts/           # Posts commands
│   │   ├── pages/           # Pages commands
│   │   ├── members/         # Members commands
│   │   ├── tags/            # Tags commands
│   │   ├── media/           # Media commands
│   │   └── export/          # Export commands
│   └── lib/
│       ├── api/             # API clients and schemas
│       ├── auth/            # JWT authentication
│       ├── config/          # Configuration management
│       └── utils/           # Utilities (filters, batch, validation)
├── tests/                   # Unit tests
├── docs/                    # Documentation
├── .github/workflows/       # CI/CD pipelines
└── Dockerfile              # Docker image

Running Tests

# Run all tests
bun test

# Run tests in watch mode
bun test --watch

# Run with coverage
bun test --coverage

# Run specific test file
bun test src/lib/api/__tests__/admin-client.test.ts

Code Quality

This project enforces strict code quality standards:

• ESLint with TypeScript rules
• TypeScript strict mode
• Zod for runtime validation
• Bun test for testing

# Check code quality
bun run lint        # ESLint
bun run typecheck   # TypeScript
bun test            # Tests

Docker Usage

Run Commands

# Run using Docker
docker run --rm registry.digitalocean.com/agileguy/ghost-cli:latest version

# With configuration file
docker run --rm \
  -v ~/.ghost-cli:/root/.ghost-cli:ro \
  registry.digitalocean.com/agileguy/ghost-cli:latest posts list

# With environment variables
docker run --rm \
  -e GHOST_URL="https://example.com" \
  -e GHOST_ADMIN_API_KEY="id:secret" \
  registry.digitalocean.com/agileguy/ghost-cli:latest posts list

Docker Image Tags

• latest - Latest main branch build
• main-<sha> - Specific commit from main branch

CI/CD Pipeline

The project includes a comprehensive GitHub Actions pipeline:

1. Test - Unit and integration tests
2. Lint - Code style and quality validation
3. Type Check - TypeScript type safety
4. Build - Application compilation and Docker image
5. Push - Docker image to DigitalOcean Container Registry (main branch only)

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Changelog

See CHANGELOG.md for version history and release notes.

License

MIT License - see LICENSE file for details.

Support

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Links

• Ghost CMS Documentation
• Ghost Admin API Reference
• Ghost Content API Reference
• Bun Documentation