ghst cli (beta)

ghst is a CLI tool for managing Ghost instances from the terminal. Anything you can do with the Ghost Admin API, you can do with ghst. (And a bit more)

• CRUD for Ghost resources
• Full Admin API support
• JSON-first scripting support (--json, --jq)
• Built-in MCP server mode for editor/agent integration
• Utility functions for development

[!IMPORTANT] This tool is pre-1.0 and not yet stable. Use with caution, and back up critical data.

Contents

• Install
• Quick Start
• Authentication and Site Selection
• Command Reference
• Global Options
• Common Workflows
• Configuration and Environment Variables
• Output, Automation, and Exit Codes
• MCP Server Mode
• Troubleshooting
• Development
• License & trademark

Install

Install globally with npm:

npm install -g @tryghost/ghst

or run instantly without global install:

npx @tryghost/ghst

Other package managers:

pnpm add -g @tryghost/ghst

yarn global add @tryghost/ghst

Quick Start

1. Authenticate:

ghst auth login

2. Verify active auth:

ghst auth status

3. Fetch content:

ghst post list --limit 5

4. Create content:

ghst post create --title "Launch" --markdown-file ./launch.md

5. Get help:

ghst --help
ghst <resource> --help
ghst <resource> <action> --help

Authentication and Site Selection

Interactive auth flow:

1. Run ghst auth login.
2. Open Ghost Admin when prompted.
3. Create or copy a staff access token from your user profile.
4. Paste Ghost API URL and Ghost Staff Access Token.

Non-interactive auth for CI/scripts:

ghst auth login \
  --non-interactive \
  --url https://myblog.ghost.io \
  --staff-token "{id}:{secret}" \
  --json

Site/profile management:

ghst auth list
ghst auth switch <site-alias>
ghst auth link --site <site-alias>
ghst --enable-destructive-actions auth link --site <site-alias> --yes
ghst --enable-destructive-actions auth logout --yes
ghst auth token

ghst auth token prints a short-lived staff JWT. Treat the output as sensitive. Destructive commands require --enable-destructive-actions; use --yes in non-interactive scripts when a destructive command also asks for confirmation. ghst auth logout requires confirmation when removing all configured sites. ghst auth link requires confirmation before replacing an existing project link. Interactive destructive confirmations also emit GHST_AGENT_NOTICE: lines on stderr instructing cooperative agents to ask the user for approval before continuing.

Command Reference

| Resource | Actions | | --- | --- | | auth | login, status, list, switch, logout, link, token | | comment | list, get, thread, replies, likes, reports, hide, show, delete | | post | list, get, create, update, delete, publish, schedule, unschedule, copy, bulk | | page | list, get, create, update, delete, copy, bulk | | tag | list, get, create, update, delete, bulk | | member | list, get, create, update, delete, import, export, bulk | | newsletter | list, get, create, update, bulk | | tier | list, get, create, update, bulk | | offer | list, get, create, update, bulk | | label | list, get, create, update, delete, bulk | | webhook | create, update, delete, events, listen | | user | list, get, me | | image | upload | | theme | list, upload, activate, validate, dev | | site | info | | socialweb | status, enable, disable, profile, profile-update, search, notes, reader, notifications, notifications-count, posts, likes, followers, following, post, thread, follow, unfollow, like, unlike, repost, derepost, delete, note, reply, blocked-accounts, blocked-domains, block, unblock, block-domain, unblock-domain, upload | | stats | overview, web (content, sources, locations, devices, utm-sources, utm-mediums, utm-campaigns, utm-contents, utm-terms), growth, posts, email (clicks, subscribers), post <id> (web, growth, newsletter, referrers) | | setting | list, get, set | | migrate | wordpress, medium, substack, csv, json, export | | config | show, path, list, get, set | | api | raw Ghost request command (ghst api [endpointPath]) | | mcp | stdio, http | | completion | bash, zsh, fish, or powershell |

Global Options

| Flag | Purpose | | --- | --- | | --json | Emit JSON output for automation | | --jq <filter> | Apply jq-style extraction to JSON output | | --site <alias> | Use configured site alias | | --url <url> + --staff-token <token> | Use direct credentials for this invocation | | --enable-destructive-actions | Allow destructive operations such as deletes | | --debug [level] | Enable debug output | | --no-color | Disable color output |

Common Workflows

Create and publish:

ghst post create --title "Launch" --markdown-file ./launch.md
ghst post publish <post-id> --newsletter weekly --email-segment all

The email delivery flags (--newsletter, --email-only, --email-segment) belong on post publish (or post schedule / post update) — Ghost's email send pipeline fires on the publish transition, not on create.

Bulk updates:

ghst post bulk --filter "status:draft" --update --add-tag release-notes --authors [email protected]
ghst member bulk --update --filter "status:free" --labels "trial,needs-follow-up"
ghst --enable-destructive-actions label bulk --filter "name:'legacy'" --action delete --yes

Comment moderation:

ghst comment list --filter "status:hidden"
ghst comment thread <comment-id>
ghst comment replies <comment-id>
ghst comment hide <comment-id>
ghst comment show <comment-id>
ghst --enable-destructive-actions comment delete <comment-id> --yes

Scheduling:

ghst post schedule <post-id> --at 2026-03-01T10:00:00Z --newsletter weekly --email-only --email-segment status:paid
ghst post unschedule <post-id>

Theme development:

ghst theme validate ./theme-dir
ghst theme dev ./theme-dir --watch --activate

Webhook relay for local development:

ghst webhook listen \
  --public-url https://hooks.example.com/ghost \
  --forward-to http://localhost:3000/webhooks

Direct API calls:

ghst api /posts/ --paginate --include-headers
ghst --enable-destructive-actions api /settings/ -X PUT -f settings[0].key=title -f settings[0].value="New title"

Analytics reporting:

ghst stats overview
ghst stats web
ghst stats web sources --range 90d --csv
ghst stats growth
ghst stats posts --range 30d --csv
ghst stats email subscribers --csv
ghst stats post <post-id> referrers --csv --output ./referrers.csv

Social web / ActivityPub:

ghst socialweb status
ghst socialweb profile
ghst socialweb notes --json
ghst socialweb follow @[email protected]
ghst --enable-destructive-actions socialweb delete https://example.com/.ghost/activitypub/note/1 --yes
ghst socialweb note --content "Hello fediverse"
ghst socialweb reply https://example.com/users/alice/statuses/1 --content "Replying from ghst"

Social web auth note:

• ghst socialweb bootstraps a short-lived identity JWT from /ghost/api/admin/identities/.
• That bridge requires an Owner or Administrator staff access token.
• ghst socialweb delete requires --enable-destructive-actions and confirmation; use --yes in non-interactive scripts.
• Public Ghost post publishing still lives under ghst post; ghst socialweb is for notes, interactions, profile, feed, and moderation flows.

Ghost analytics filter semantics:

• source and utm_* filters are session-scoped.
• post and member-status filters are hit-scoped.

Ghost range semantics:

• stats growth clips member, MRR, and subscription histories client-side when Ghost only exposes broader source data.
• stats post ... growth clips Ghost's lifetime post-growth history to the selected window.

File output safety:

• ghst member export --output, ghst stats ... --csv --output, and ghst migrate export --output refuse to overwrite an existing file.

endpointPath must stay within the selected Ghost API root. Use resource paths such as /posts/ or canonical Ghost API paths such as /ghost/api/admin/posts/.

Configuration and Environment Variables

Connection resolution order:

1. --site
2. --url + --staff-token
3. GHOST_URL + GHOST_STAFF_ACCESS_TOKEN
4. project link file .ghst/config.json
5. active site in user config

Primary config/state files:

| Path | Purpose | | --- | --- | | ~/.config/ghst/config.json | User config (saved sites, active site) | | .ghst/config.json | Project-level linked site | | .env.example | Example environment configuration |

Environment variables:

| Variable | Purpose | | --- | --- | | GHOST_URL | Ghost site URL override | | GHOST_STAFF_ACCESS_TOKEN | Ghost staff access token ({id}:{secret}) | | GHOST_API_VERSION | Admin API version override (default v6.0) | | GHOST_SITE | Site alias fallback lookup in user config | | GHOST_CONTENT_API_KEY | Required when using ghst api --content-api | | GHST_CONFIG_DIR | Override user config directory path | | GHST_OUTPUT | Force JSON output when set to json | | GHST_FORCE_TTY | Force TTY behavior for non-interactive environments | | GHST_NO_COLOR / NO_COLOR | Disable colorized output |

Output, Automation, and Exit Codes

JSON + jq-style extraction:

ghst post list --json
ghst post list --json --jq '.posts[].title'

Raw ghst api requests using non-read HTTP methods also require --enable-destructive-actions.

Common machine-safe practices:

• Use --json for scripts.
• Use --non-interactive for CI where prompts are invalid.
• Pass explicit auth (--url and --staff-token) or set env vars.

Exit code mapping:

| Code | Meaning | | --- | --- | | 0 | Success | | 1 | General error | | 2 | Usage/argument error | | 3 | Authentication/authorization error | | 4 | Operation cancelled | | 5 | Not found | | 6 | Conflict | | 7 | Validation error | | 8 | Rate limited |

MCP Server Mode

Run MCP over stdio or HTTP:

ghst mcp stdio --tools all
ghst mcp http --host 127.0.0.1 --port 3100 --tools posts,tags,site --auth-token token-123

Notes:

• ghst mcp http binds to loopback by default. Binding to a non-loopback host requires --unsafe-public-bind.
• --cors-origin accepts a single exact origin only, for example https://app.example.com.
• --tools accepts all or comma-separated group names such as posts,stats.
• Exposed MCP tools include ghst/toolGroup and ghst/toolGroupTitle metadata for clients that render grouped tools.
• MCP tools accept an optional site argument to target a configured site alias per call. When omitted, ghst uses the normal site resolution order.
• Use ghost_site_list to list configured site aliases without exposing stored credentials.

Example multi-instance workflow:

ghost_post_get({ id: "abc123", site: "blog-fr" })
ghost_post_create({ title: "Translated title", html: "<p>...</p>", site: "blog-en" })

Supported tool groups:

• posts
• pages
• tags
• members
• comments
• site
• settings
• users
• api
• search
• socialweb
• stats

The stats MCP tools mirror the CLI analytics surface, including ghst stats overview, ghst stats web, ghst stats growth, ghst stats posts, ghst stats email subscribers, and ghst stats post <post-id> referrers. The same Ghost analytics filter and range semantics shown above apply to both the CLI and MCP stats tooling.

The socialweb MCP tools mirror the ghst socialweb CLI surface for status, profile, feeds, interactions, moderation, and uploads. They use the same Owner/Admin auth flow as the CLI.

Safe Operation

• Keep ghst mcp http on loopback unless you explicitly intend to expose Ghost admin automation.
• Treat ghst api and MCP ghost_api_request as privileged admin access.
• Avoid sharing terminal output that contains ghst auth token output or values revealed with config --show-secrets.

Troubleshooting

No site configuration found:

• Run ghst auth login, or
• Provide --url and --staff-token, or
• Set GHOST_URL and GHOST_STAFF_ACCESS_TOKEN.

GHOST_CONTENT_API_KEY is required for --content-api requests:

• Export GHOST_CONTENT_API_KEY before ghst api --content-api.

Use --non-interactive when combining auth login with --json:

• Re-run auth with --non-interactive and explicit credentials.

Commands and flags drift:

• Re-check current command docs with ghst <resource> --help.

Development

For cloning, testing, and developing the repository from source, see CONTRIBUTING.md.

License & trademark

Copyright (c) 2013-2026 Ghost Foundation - Released under the MIT license. Ghost and the Ghost Logo are trademarks of Ghost Foundation Ltd. Please see our trademark policy for info on acceptable usage.