@tryghost/ghst 0.4.3 → 0.6.0

package/README.md

@@ -109,14 +109,22 @@ Site/profile management:
 ghst auth list
 ghst auth switch <site-alias>
 ghst auth link --site <site-alias>
+ghst auth link --site <site-alias> --yes
+ghst auth logout --yes
 ghst auth token
 ```
 
+`ghst auth token` prints a short-lived staff JWT. Treat the output as sensitive.
+`ghst auth logout` requires confirmation when removing all configured sites; use `--yes` in non-interactive scripts.
+`ghst auth link` requires confirmation before replacing an existing project link; use `--yes` in non-interactive scripts.
+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` |
@@ -130,6 +138,8 @@ ghst auth token
 | `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` |
@@ -165,10 +175,21 @@ ghst member bulk --update --filter "status:free" --labels "trial,needs-follow-up
 ghst 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 comment delete <comment-id> --yes
+```
+
 Scheduling:
 
 ```bash
-ghst post schedule <post-id> --at 2026-03-01T10:00:00Z
+ghst post schedule <post-id> --at 2026-03-01T10:00:00Z --newsletter weekly --email-only --email-segment status:paid
 ghst post unschedule <post-id>
 ```
 
@@ -194,6 +215,50 @@ ghst api /posts/ --paginate --include-headers
 ghst api /settings/ -X PUT -f settings[0].key=title -f settings[0].value="New title"
 ```
 
+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 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 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:
@@ -261,20 +326,43 @@ 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
+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`.
+
 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 private `ghst socialweb` admin surface for status,
+profile, feeds, interactions, moderation, and uploads. They use the same Owner/Admin
+identity-token bridge as the CLI and remain limited to Ghost's private social web admin APIs.
+
+## 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