ghst

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

(★ 34)

A modern Ghost CLI tool

ghst Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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](#install)
- [Quick Start](#quick-start)
- [Authentication and Site Selection](#authentication-and-site-selection)
- [Command Reference](#command-reference)
- [Global Options](#global-options)
- [Common Workflows](#common-workflows)
- [Configuration and Environment Variables](#configuration-and-environment-variables)
- [Output, Automation, and Exit Codes](#output-automation-and-exit-codes)
- [MCP Server Mode](#mcp-server-mode)
- [Troubleshooting](#troubleshooting)
- [Development](#development)
- [License & trademark](#license--trademark)

## Install

Install globally with npm:

```bash
npm install -g @tryghost/ghst
```

or run instantly without global install:

```bash
npx @tryghost/ghst
```

Other package managers:

```bash
pnpm add -g @tryghost/ghst
```

```bash
yarn global add @tryghost/ghst
```

## Quick Start

1. Authenticate:

```bash
ghst auth login
```

2. Verify active auth:

```bash
ghst auth status
```

3. Fetch content:

```bash
ghst post list --limit 5
```

4. Create content:

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

5. Get help:

```bash
ghst -v
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:

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

Site/profile management:

```bash
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 |
| --- | --- |
| `-v`, `--version` | Print the installed `ghst` version |
| `--json` | Emit JSON output for automation |
| `--jq <filter>` | Apply a jq filter to JSON output (full jq syntax; runs against the response envelope) |
| `--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:

```bash
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.

Pages share the same content flags as posts, including `--slug`, `--tags`, `--from-json`, and `--markdown-file`:

```bash
ghst page create --title "About" --slug about --tags company,legal --markdown-file ./about.md
```

Bulk updates:

```bash
ghst post bulk --filter "status:draft" --update --add-tag release-notes --authors editor@example.com
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:

```bash
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:

```bash
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:

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

Webhook relay for local development:

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

Direct API calls:

```bash
ghst api /posts/ --paginate --include-headers
ghst api /settings/ -X PUT -f settings[0].key=title -f settings[0].value="New title"
ghst --enable-destructive-actions api /posts/<post-id>/ -X DELETE
```

Analytics reporting:

```bash
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:

```bash
ghst socialweb status
ghst socialweb profile
ghst socialweb notes --json
ghst socialweb follow @alice@example.com
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 filtering:

`--jq` accepts full jq syntax (pipes, indexing, object construction, and built-ins) and runs against the full JSON response, so reach into the collection with `.posts[]` rather than `.[]`:

```bash
ghst post list --json
ghst post list --json --jq '.posts[].title'
ghst post list --json --jq '.posts[0] | {title, slug}'
ghst post list --json --jq '.posts[] | select(.status == "published") | .slug'
```

Each result is printed on its own line as compact JSON, so the output stays pipe-friendly. An invalid `--jq` filter exits with code `2` (`USAGE_ERROR`) rather than leaking interpreter errors.

Raw `ghst api` requests allow ordinary `POST`/`PUT`/`PATCH` writes by default; `DELETE` requests and overwrite/import routes (e.g. `POST /db/`) 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:

```bash
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 also carry standard `readOnlyHint`/`destructiveHint` annotations so clients like Claude Desktop group them into read-only and write/delete buckets automatically.
- 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:

```text
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](CONTRIBUTING.md).

## License & trademark

Copyright (c) 2013-2026 Ghost Foundation - Released under the [MIT license](LICENSE).
Ghost and the Ghost Logo are trademarks of Ghost Foundation Ltd. Please see our [trademark policy](https://ghost.org/trademark/) for info on acceptable usage.

ghst

ghst Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

ghst

ghst Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README