KO
|
EN
gitlite — search
Search
#python
#javascript
#java
#typescript
#android
#csharp
#framework
#deep-learning
#machine-learning
#python3
#cpp
#express
ghst
★ 34
Open GitHub ↗
A modern Ghost CLI tool
Download README (.md)
Explore Similar Repositories
ghsign
:
Sign/verify data using your local ssh private key and your public key from Github
GHSDD
:
A chrome extension to download any sub-directory or file from a Github repo .
ghsync
:
Sync local git repository and remote GitHub repository automatically.
GHShopCart_flutter
:
flutter版购物车,所有数据真实接口获取
ghs
:
A Github repo search CLI
// repository documentation
Was this content helpful?
★ 0
(0 ratings)
Select Rating:
★
★
★
★
★
Submit Feedback
Recent Feedback
×
Download README
Do you want to download the
README.md
file for
ghst
?
Download (.md)
# 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.
