@clickminded/coauthor-cli 0.0.83 → 0.0.84
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/commands.js
CHANGED
|
@@ -816,6 +816,13 @@ async function runPostDetailsCommand(action, input, client) {
|
|
|
816
816
|
}
|
|
817
817
|
if (action === 'set') {
|
|
818
818
|
const body = parseJsonOption(input.values);
|
|
819
|
+
// The display title (H1, the post title in exports) is stored as the project title. It cannot be cleared.
|
|
820
|
+
const title = getString(input.values, 'title');
|
|
821
|
+
if (title !== undefined) {
|
|
822
|
+
if (!title.trim())
|
|
823
|
+
throw new Error('--title needs a title (1 to 300 characters); a post always has one.');
|
|
824
|
+
body.title = title.trim();
|
|
825
|
+
}
|
|
819
826
|
for (const [flag, field] of POST_DETAILS_FLAG_FIELDS) {
|
|
820
827
|
const value = getString(input.values, flag);
|
|
821
828
|
if (value !== undefined)
|
|
@@ -849,7 +856,7 @@ async function runPostDetailsCommand(action, input, client) {
|
|
|
849
856
|
body.tracking_keyword = null;
|
|
850
857
|
}
|
|
851
858
|
if (Object.keys(body).length === 0) {
|
|
852
|
-
throw new Error('Usage: coauthor post-details set <projectId> [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."] [--live-url <url> | --clear-live-url] [--track-search <search> | --clear-track-search]');
|
|
859
|
+
throw new Error('Usage: coauthor post-details set <projectId> [--title "..."] [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."] [--live-url <url> | --clear-live-url] [--track-search <search> | --clear-track-search]');
|
|
853
860
|
}
|
|
854
861
|
return { ok: true, data: await client.request({ method: 'PATCH', path, body }) };
|
|
855
862
|
}
|
|
@@ -3782,7 +3789,7 @@ function commandHelp(command) {
|
|
|
3782
3789
|
'Usage: coauthor draft get <project-id> [--format json|markdown|html|text] [--frontmatter] [--widgets image|embed] [--json]',
|
|
3783
3790
|
'',
|
|
3784
3791
|
'Retrieves a saved generated draft. Chat responses are available through coauthor chat show.',
|
|
3785
|
-
'--frontmatter (markdown only) prepends YAML frontmatter from the post details: title, seo_title, description, slug, excerpt, and the featured image. Posts without post details get no frontmatter.',
|
|
3792
|
+
'--frontmatter (markdown only) prepends YAML frontmatter from the post details: title (the display title), seo_title, description, slug, excerpt, and the featured image. Posts without post details get no frontmatter.',
|
|
3786
3793
|
'--widgets (markdown or html only) chooses how built interactives export. image (default) is the linked poster image, safe for email and newsletters. embed is the live sandboxed iframe plus one embed.js script, for a website you control (Astro, Hugo, Next, custom HTML). In markdown the iframe is a raw HTML block that is also valid MDX.',
|
|
3787
3794
|
].join('\n'),
|
|
3788
3795
|
'draft save': [
|
|
@@ -3797,6 +3804,7 @@ function commandHelp(command) {
|
|
|
3797
3804
|
'',
|
|
3798
3805
|
'create: --title, --topic, --audience, --contract <json|@file>. show: one project.',
|
|
3799
3806
|
'list: --limit <n> (1-100), --cursor <next_cursor from the previous page>, --status <state> (a project_state such as research_running or editing, or the publication status submitted|published).',
|
|
3807
|
+
'rename <project-id> --title "...": changes the post\'s display title (its H1 and the post title in exports, the same as post-details set --title). A drafted post keeps a renamed title when the draft is regenerated.',
|
|
3800
3808
|
'duplicate <project-id> [--title "..."]: copies the brief, outline, research, chats, draft, images and repurposed posts into a new project that keeps the same profile (default title is "<title> (Copy)"). Prints the new project id.',
|
|
3801
3809
|
].join('\n'),
|
|
3802
3810
|
profile: [
|
|
@@ -3963,10 +3971,11 @@ function commandHelp(command) {
|
|
|
3963
3971
|
].join('\n'),
|
|
3964
3972
|
'post-details': [
|
|
3965
3973
|
'Usage: coauthor post-details show <project-id> [--json]',
|
|
3966
|
-
' coauthor post-details set <project-id> [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."] [--live-url <url> | --clear-live-url] [--track-search <search> | --clear-track-search] [--json]',
|
|
3974
|
+
' coauthor post-details set <project-id> [--title "..."] [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."] [--live-url <url> | --clear-live-url] [--track-search <search> | --clear-track-search] [--json]',
|
|
3967
3975
|
'',
|
|
3968
3976
|
'Post details are the SEO title, meta description, slug and excerpt CoAuthor writes after a draft. Exports use them as defaults.',
|
|
3969
|
-
'
|
|
3977
|
+
'title is the post\'s display title: its H1 and the post title in WordPress, ClickMinded and Markdown exports. It is the project title (CoAuthor writes it with the draft; `project rename` changes it too). seo_title is only the title shown in search results and the meta title in exports.',
|
|
3978
|
+
'set changes only the fields you pass; an empty value clears a field (except --title: a post always has a title). Edited fields, including a title you set or renamed, are kept when the draft is regenerated.',
|
|
3970
3979
|
'The live URL is where the post is published. show returns published_url and published_url_source (export, manual, auto_detect or cleared). --live-url sets it by hand (an http or https address) and wins over later exports; --clear-live-url removes it, and CoAuthor then does not look for it again.',
|
|
3971
3980
|
'Posts written without a target search (mostly drafted before SEO mode) are tracked by the monthly check anyway: CoAuthor finds the live page and picks a search. show returns tracking (published_url, published_url_source, tracking_keyword, tracking_keyword_source: ranked or suggested = CoAuthor picked it, manual = you did). --track-search sets the search to track (1 to 120 characters; wins over later picks); --clear-track-search has CoAuthor pick again at the next check. To stop tracking such a post, use --clear-live-url. --track-search is for posts without a target search (a post with one answers post_has_target_search).',
|
|
3972
3981
|
'Posts drafted before post details launched have no SEO fields (show returns post_details: null; setting SEO fields returns post_details_unavailable), but --live-url, --clear-live-url and --track-search still work for them.',
|
package/package.json
CHANGED
|
@@ -10,24 +10,27 @@ coauthor draft get <id> --format text --json # data.text, plain text with
|
|
|
10
10
|
coauthor draft get <id> --format json --json # data.content, the editor document (for edits)
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
The markdown and HTML have no H1: they start with the featured image (once generated) and then the first section. Add the title yourself from `coauthor
|
|
13
|
+
The markdown and HTML have no H1: they start with the featured image (once generated) and then the first section. Add the title yourself from `coauthor post-details show <id> --json` (`data.post_details.title`, or `data.project.title` from `coauthor project show` for drafts without post details) when you hand over a file. Images appear only after they have been generated, and their URLs are public, so the markdown can be pasted anywhere.
|
|
14
14
|
|
|
15
15
|
For a markdown file going into a static-site generator (Astro, Hugo, Next.js, Ghost), add `--frontmatter`: the markdown then starts with a YAML block holding the title, SEO title, meta description, slug, excerpt, and featured image from the post details. Drafts made before post details launched get no frontmatter. SEO posts also get `keyword` and `secondary_keywords`. Every `draft get` response includes `search` in its metadata: `{keyword, secondary_keywords, market}` for SEO posts, `null` otherwise.
|
|
16
16
|
|
|
17
|
-
## Post details (SEO title, meta description, slug, excerpt)
|
|
17
|
+
## Post details (title, SEO title, meta description, slug, excerpt)
|
|
18
18
|
|
|
19
19
|
After a draft, CoAuthor writes the post's SEO title, meta description, slug, and excerpt. Exports use them as defaults, so set them once here rather than on every export.
|
|
20
20
|
|
|
21
|
+
`post_details.title` is the display title: the post's H1 and the post title in WordPress, ClickMinded and Markdown exports. It is the project title, which CoAuthor writes with the draft. `seo_title` is only the title shown in search results (keyword first, about 60 characters) and the meta title in exports, so never use it as the H1. Change the display title with `--title` (or `project rename`, which is the same thing); it cannot be cleared.
|
|
22
|
+
|
|
21
23
|
```sh
|
|
22
24
|
coauthor post-details show <id> --json # data.post_details (null for drafts made before post details launched)
|
|
23
25
|
coauthor post-details set <id> --seo-title "..." --description "..." --slug "..." --excerpt "..." --json
|
|
26
|
+
coauthor post-details set <id> --title "The Post's Headline" --json # display title (H1); kept when the draft is regenerated
|
|
24
27
|
coauthor post-details set <id> --live-url https://example.com/my-post/ --json # where the post is live
|
|
25
28
|
coauthor post-details set <id> --clear-live-url --json
|
|
26
29
|
coauthor post-details set <id> --track-search "welcome email examples" --json # posts written without a target search: the search to track
|
|
27
30
|
coauthor post-details set <id> --clear-track-search --json # CoAuthor picks the search again at the next check
|
|
28
31
|
```
|
|
29
32
|
|
|
30
|
-
`set` changes only the fields you pass; an empty value clears one. Fields the user or you edited are kept when the draft is regenerated. Keep the SEO title near 60 characters and the description near 155. `post_details_unavailable` means the draft predates post details and you tried to change an SEO field
|
|
33
|
+
`set` changes only the fields you pass; an empty value clears one. Fields the user or you edited are kept when the draft is regenerated, and so is a title set with `--title` or `project rename` (`user_edited_fields` then lists `title`). Keep the SEO title near 60 characters and the description near 155. `post_details_unavailable` means the draft predates post details and you tried to change an SEO field or the title; rename such a post with `project rename`.
|
|
31
34
|
|
|
32
35
|
The live URL is where the post is published. `post_details.published_url` holds it (null until it is known) and `published_url_source` says where it came from: `export` (an export reported the post live, or a WordPress post the user published afterwards), `manual` (set with `--live-url` or in the app), `auto_detect` (CoAuthor found the page on the user's site) or `cleared` (removed on purpose). Set it when the user tells you where a post went live. A URL set by hand wins over later exports, and `--clear-live-url` removes it so CoAuthor does not look for it again. It must be an `http` or `https` address, and it is not one of the four SEO fields, so it never counts as an edited field.
|
|
33
36
|
|
|
@@ -59,7 +59,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
59
59
|
| `invalid_seo_mode` | `--seo` or `set-mode` got something other than `optimize`, `my-way` or `off`, or `--seo off` was combined with `--keyword`. | Pass one of the three modes; drop `--keyword` with `off`. |
|
|
60
60
|
| `no_search_target` | `search-brief set-mode optimize` or `my-way` on a project with no target keyword. | Set one with `search-brief set-keyword`, or let the outline pick one. |
|
|
61
61
|
| `post_details_unavailable` | The draft was made before post details launched, so it has no SEO fields to edit (`--live-url` and `--track-search` still work). | Pass the slug and description to the export directly. |
|
|
62
|
-
| `invalid_post_details` | `post-details set` got something other than text for a field, a live URL that is not an `http` or `https` address, or a `--track-search` that is empty or over 120 characters. | Pass plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`, a full address with `--live-url`, and a search of 1 to 120 characters with `--track-search`. |
|
|
62
|
+
| `invalid_post_details` | `post-details set` got an empty or over-300-character `--title`, something other than text for a field, a live URL that is not an `http` or `https` address, or a `--track-search` that is empty or over 120 characters. | Pass a title of 1 to 300 characters with `--title`, plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`, a full address with `--live-url`, and a search of 1 to 120 characters with `--track-search`. |
|
|
63
63
|
| `post_has_target_search` | `post-details set --track-search` on a post that was written for a target search. | Nothing to do: that post is tracked with its target search. Change it with `search-brief set-keyword` if the user wants another. |
|
|
64
64
|
| `structured_brief` | `image generate --prompt` on a comparison or technical-diagram image, which is built from structured fields. | Generate without `--prompt`, then `image edit --edit-prompt "..."`. |
|
|
65
65
|
| `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
|
|
@@ -460,24 +460,27 @@ coauthor draft get <id> --format text --json # data.text, plain text with
|
|
|
460
460
|
coauthor draft get <id> --format json --json # data.content, the editor document (for edits)
|
|
461
461
|
```
|
|
462
462
|
|
|
463
|
-
The markdown and HTML have no H1: they start with the featured image (once generated) and then the first section. Add the title yourself from `coauthor
|
|
463
|
+
The markdown and HTML have no H1: they start with the featured image (once generated) and then the first section. Add the title yourself from `coauthor post-details show <id> --json` (`data.post_details.title`, or `data.project.title` from `coauthor project show` for drafts without post details) when you hand over a file. Images appear only after they have been generated, and their URLs are public, so the markdown can be pasted anywhere.
|
|
464
464
|
|
|
465
465
|
For a markdown file going into a static-site generator (Astro, Hugo, Next.js, Ghost), add `--frontmatter`: the markdown then starts with a YAML block holding the title, SEO title, meta description, slug, excerpt, and featured image from the post details. Drafts made before post details launched get no frontmatter. SEO posts also get `keyword` and `secondary_keywords`. Every `draft get` response includes `search` in its metadata: `{keyword, secondary_keywords, market}` for SEO posts, `null` otherwise.
|
|
466
466
|
|
|
467
|
-
### Post details (SEO title, meta description, slug, excerpt)
|
|
467
|
+
### Post details (title, SEO title, meta description, slug, excerpt)
|
|
468
468
|
|
|
469
469
|
After a draft, CoAuthor writes the post's SEO title, meta description, slug, and excerpt. Exports use them as defaults, so set them once here rather than on every export.
|
|
470
470
|
|
|
471
|
+
`post_details.title` is the display title: the post's H1 and the post title in WordPress, ClickMinded and Markdown exports. It is the project title, which CoAuthor writes with the draft. `seo_title` is only the title shown in search results (keyword first, about 60 characters) and the meta title in exports, so never use it as the H1. Change the display title with `--title` (or `project rename`, which is the same thing); it cannot be cleared.
|
|
472
|
+
|
|
471
473
|
```sh
|
|
472
474
|
coauthor post-details show <id> --json # data.post_details (null for drafts made before post details launched)
|
|
473
475
|
coauthor post-details set <id> --seo-title "..." --description "..." --slug "..." --excerpt "..." --json
|
|
476
|
+
coauthor post-details set <id> --title "The Post's Headline" --json # display title (H1); kept when the draft is regenerated
|
|
474
477
|
coauthor post-details set <id> --live-url https://example.com/my-post/ --json # where the post is live
|
|
475
478
|
coauthor post-details set <id> --clear-live-url --json
|
|
476
479
|
coauthor post-details set <id> --track-search "welcome email examples" --json # posts written without a target search: the search to track
|
|
477
480
|
coauthor post-details set <id> --clear-track-search --json # CoAuthor picks the search again at the next check
|
|
478
481
|
```
|
|
479
482
|
|
|
480
|
-
`set` changes only the fields you pass; an empty value clears one. Fields the user or you edited are kept when the draft is regenerated. Keep the SEO title near 60 characters and the description near 155. `post_details_unavailable` means the draft predates post details and you tried to change an SEO field
|
|
483
|
+
`set` changes only the fields you pass; an empty value clears one. Fields the user or you edited are kept when the draft is regenerated, and so is a title set with `--title` or `project rename` (`user_edited_fields` then lists `title`). Keep the SEO title near 60 characters and the description near 155. `post_details_unavailable` means the draft predates post details and you tried to change an SEO field or the title; rename such a post with `project rename`.
|
|
481
484
|
|
|
482
485
|
The live URL is where the post is published. `post_details.published_url` holds it (null until it is known) and `published_url_source` says where it came from: `export` (an export reported the post live, or a WordPress post the user published afterwards), `manual` (set with `--live-url` or in the app), `auto_detect` (CoAuthor found the page on the user's site) or `cleared` (removed on purpose). Set it when the user tells you where a post went live. A URL set by hand wins over later exports, and `--clear-live-url` removes it so CoAuthor does not look for it again. It must be an `http` or `https` address, and it is not one of the four SEO fields, so it never counts as an edited field.
|
|
483
486
|
|
|
@@ -780,7 +783,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
780
783
|
| `invalid_seo_mode` | `--seo` or `set-mode` got something other than `optimize`, `my-way` or `off`, or `--seo off` was combined with `--keyword`. | Pass one of the three modes; drop `--keyword` with `off`. |
|
|
781
784
|
| `no_search_target` | `search-brief set-mode optimize` or `my-way` on a project with no target keyword. | Set one with `search-brief set-keyword`, or let the outline pick one. |
|
|
782
785
|
| `post_details_unavailable` | The draft was made before post details launched, so it has no SEO fields to edit (`--live-url` and `--track-search` still work). | Pass the slug and description to the export directly. |
|
|
783
|
-
| `invalid_post_details` | `post-details set` got something other than text for a field, a live URL that is not an `http` or `https` address, or a `--track-search` that is empty or over 120 characters. | Pass plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`, a full address with `--live-url`, and a search of 1 to 120 characters with `--track-search`. |
|
|
786
|
+
| `invalid_post_details` | `post-details set` got an empty or over-300-character `--title`, something other than text for a field, a live URL that is not an `http` or `https` address, or a `--track-search` that is empty or over 120 characters. | Pass a title of 1 to 300 characters with `--title`, plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`, a full address with `--live-url`, and a search of 1 to 120 characters with `--track-search`. |
|
|
784
787
|
| `post_has_target_search` | `post-details set --track-search` on a post that was written for a target search. | Nothing to do: that post is tracked with its target search. Change it with `search-brief set-keyword` if the user wants another. |
|
|
785
788
|
| `structured_brief` | `image generate --prompt` on a comparison or technical-diagram image, which is built from structured fields. | Generate without `--prompt`, then `image edit --edit-prompt "..."`. |
|
|
786
789
|
| `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
|