ghostctl

A command-line interface for managing Ghost blogs via the Content API (public, read-only) and the Admin API (full content management).

Installation

brew tap stumpyfr/tap
brew install ghostctl

Or, as a one-liner:

brew install stumpyfr/tap/ghostctl

Or install with Go:

go install github.com/stumpyfr/ghostctl/cmd/ghostctl@latest

Or build from source:

make build          # produces bin/ghostctl

Quick start

# Configure your site
ghostctl config set --url https://your-site.ghost.io \
                    --admin-key YOUR_ID:YOUR_SECRET \
                    --content-key YOUR_CONTENT_KEY

# Check connectivity
ghostctl doctor

# Who am I?
ghostctl whoami

Help output

ghostctl is a command-line interface for managing a Ghost blog
using the Content API (public, read-only) and the Admin API (content management).

Usage:
  ghostctl [command]

Available Commands:
  auth        Manage authentication
  completion  Generate shell completion scripts
  config      Manage ghostctl configuration
  diff        Compare admin and public versions of content
  doctor      Check Ghost site connectivity and credentials
  export      Export Ghost content to local files
  help        Help about any command
  image       Manage Ghost images (Admin API)
  import      Import Ghost content from local files
  invite      Manage Ghost invites (Admin API)
  member      Manage Ghost members (Admin API)
  newsletter  Manage Ghost newsletters (Admin API)
  offer       Manage Ghost offers (Admin API)
  page        Manage Ghost pages (Admin API)
  post        Manage Ghost posts (Admin API)
  public      Read public (Content API) resources
  role        List Ghost roles (Admin API)
  settings    Manage Ghost site settings (Admin API)
  sync        Check synchronisation between admin and public content
  tag         Manage Ghost tags (Admin API)
  theme       Manage Ghost themes (Admin API)
  tier        Manage Ghost tiers (Admin API)
  user        Manage Ghost users (Admin API)
  version     Print the ghostctl version
  webhook     Manage Ghost webhooks (Admin API)
  whoami      Show current site config and authenticated user

Flags:
      --admin-key string     override admin API key (id:secret)
      --admin-token string   staff access token
      --api-version string   Accept-Version value (e.g. v5.0)
      --content-key string   override content API key
      --dry-run              print what would be done without executing
  -h, --help                 help for ghostctl
      --json                 output machine-readable JSON
      --no-color             disable ANSI color output
      --quiet                suppress non-essential output
      --retry int            number of retries for transient failures (default 3)
      --site string          named site context from config
      --timeout string       HTTP request timeout (e.g. 30s, 2m) (default "15s")
      --trace-http           log full HTTP request/response
      --url string           override site base URL
      --verbose              enable verbose logging
      --yaml                 output YAML

Common workflows

# List and manage posts
ghostctl post list
ghostctl post create --title "Hello World" --from-markdown ./post.md
ghostctl post publish <id>
ghostctl post send <id> --newsletter <newsletter-id>

# Compare admin vs public (exits 6 on drift)
ghostctl diff post my-slug --slug
ghostctl diff page my-page --slug

# Members
ghostctl member list --filter "subscribed:true"
ghostctl member export --format csv --output members.csv

# Themes
ghostctl theme upload ./casper.zip
ghostctl theme activate casper

# Export/import
ghostctl export posts --format json --output posts.json
ghostctl import post-json posts.json

# Multi-site
ghostctl --site staging post list
ghostctl --url https://other.ghost.io --admin-key id:secret post list

Output formats

All commands support --json and --yaml for machine-readable output:

ghostctl post list --json | jq '.[].title'
ghostctl settings get --yaml

Configuration

Config lives at ~/.config/ghostctl/config.yaml (or $XDG_CONFIG_HOME/ghostctl/config.yaml):

default_site: production
sites:
  production:
    url: https://your-site.ghost.io
    api_version: v5.0
    auth:
      mode: integration        # or: staff-token
      admin_key: KEY_ID:SECRET
      content_key: YOUR_CONTENT_KEY
  staging:
    url: https://staging.ghost.io
    auth:
      mode: integration
      admin_key: KEY_ID:SECRET

Exit codes

Code	Meaning
0	Success
1	General error
2	Configuration / credential error
3	Resource not found
4	Validation error
5	Rate limited
6	Content drift detected (diff commands)

Releases

Maintainers publish tagged releases from this repository. On each v* tag:

git tag v0.1.0
git push origin v0.1.0

Set the HOMEBREW_TAP_GITHUB_TOKEN GitHub Actions secret with write access to stumpyfr/tap. GitHub Actions then publishes the release assets and updates stumpyfr/tap automatically.

Users can then upgrade with:

brew upgrade ghostctl