@clickminded/coauthor-cli 0.0.50 → 0.0.51

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
@@ -283,6 +283,9 @@ async function runProjectCommand(action, input, client) {
283
283
  throw new Error('--keyword needs a search phrase, e.g. --keyword "email marketing for small business"');
284
284
  body.keyword = keyword;
285
285
  }
286
+ const seo = getString(input.values, 'seo');
287
+ if (seo !== undefined)
288
+ body.seo_mode = parseSeoModeOption(seo, '--seo');
286
289
  const rawContract = getString(input.values, 'contract');
287
290
  if (rawContract !== undefined) {
288
291
  if (!rawContract.trim())
@@ -748,18 +751,29 @@ async function runPostDetailsCommand(action, input, client) {
748
751
  }
749
752
  throw new Error('Usage: coauthor post-details <show|set> <projectId>');
750
753
  }
754
+ const SEO_MODES = ['optimize', 'my-way', 'off'];
755
+ /** `optimize` (outline and prose follow the search), `my-way` (keyword in the SEO title, meta and slug only) or `off`. */
756
+ function parseSeoModeOption(raw, flag) {
757
+ const value = raw.trim().toLowerCase();
758
+ if (SEO_MODES.includes(value))
759
+ return value;
760
+ throw new Error(`${flag} must be optimize, my-way or off`);
761
+ }
751
762
  function searchBriefMessage(data) {
752
763
  const brief = data?.search_brief;
753
764
  if (!brief)
754
765
  return undefined;
755
766
  const target = brief.target;
767
+ if (brief.mode === 'off')
768
+ return 'Search targeting is off for this post.';
756
769
  if (target && target.decision === 'search_play' && typeof target.keyword === 'string') {
757
770
  const facts = [
758
771
  typeof target.monthly_volume === 'number' ? `${target.monthly_volume}/mo` : null,
759
772
  typeof target.difficulty === 'number' ? `difficulty ${target.difficulty}` : null,
760
773
  typeof target.market === 'string' ? target.market : null,
761
774
  ].filter(Boolean);
762
- return `Targeting "${target.keyword}"${facts.length ? ` (${facts.join(', ')})` : ''}.`;
775
+ const mode = brief.mode === 'my-way' ? ' Written your way: the keyword goes in the SEO title, meta description and slug only.' : '';
776
+ return `Targeting "${target.keyword}"${facts.length ? ` (${facts.join(', ')})` : ''}.${mode}`;
763
777
  }
764
778
  if (brief.status === 'not_checked')
765
779
  return 'No search check has run for this project yet. It runs when the outline is generated, or set a keyword with `coauthor search-brief set-keyword`.';
@@ -786,7 +800,19 @@ async function runSearchBriefCommand(action, input, client) {
786
800
  });
787
801
  return { ok: true, message: searchBriefMessage(data), data };
788
802
  }
789
- throw new Error('Usage: coauthor search-brief <show|set-keyword> <project-id>');
803
+ if (action === 'set-mode') {
804
+ const usage = 'Usage: coauthor search-brief set-mode <project-id> <optimize|my-way|off> [--confirm-reset]';
805
+ const raw = input.positionals[1];
806
+ if (!raw)
807
+ throw new Error(usage);
808
+ const data = await client.request({
809
+ method: 'POST',
810
+ path: `${path}/mode`,
811
+ body: { mode: parseSeoModeOption(raw, 'set-mode'), confirm_reset: input.values['confirm-reset'] === true },
812
+ });
813
+ return { ok: true, message: searchBriefMessage(data), data };
814
+ }
815
+ throw new Error('Usage: coauthor search-brief <show|set-keyword|set-mode> <project-id>');
790
816
  }
791
817
  // Revise by instruction: CoAuthor's editor proposes the change, and the
792
818
  // calling agent reviews the groups and applies or discards them.
@@ -2717,7 +2743,7 @@ export function helpResult(command = []) {
2717
2743
  ' draft get supports --format json|markdown|html|text (--frontmatter adds post details to markdown)',
2718
2744
  ' post-details show|set',
2719
2745
  ' seo markets [--country <country>] [--language <language>]',
2720
- ' search-brief show|set-keyword (limited rollout)',
2746
+ ' search-brief show|set-keyword|set-mode (limited rollout)',
2721
2747
  ' workflow show|status|advance|run|rewind|approve|resume',
2722
2748
  ' workflow run/advance supports --briefing-mode auto|strict|off and --require-brief-review',
2723
2749
  ' image list|status|show|generate|edit|metadata|replace',
@@ -2755,11 +2781,12 @@ function commandHelp(command) {
2755
2781
  'Copies the brief, outline, research, chats, draft, images and repurposed posts into a new project that keeps the same profile. The default title is "<title> (Copy)". Prints the new project id.',
2756
2782
  ].join('\n'),
2757
2783
  'project create': [
2758
- 'Usage: coauthor project create [--title <title>] [--topic <brief>] [--audience <audience>] [--contract <json>] [--profile <profile-id>] [--keyword <search phrase>] [--json]',
2784
+ 'Usage: coauthor project create [--title <title>] [--topic <brief>] [--audience <audience>] [--contract <json>] [--profile <profile-id>] [--keyword <search phrase>] [--seo optimize|my-way|off] [--json]',
2759
2785
  '',
2760
2786
  'Creates a project. When --topic or --audience is provided, CoAuthor seeds the saved contract so workflow briefing review can use that context.',
2761
2787
  '--contract accepts a JSON editorial contract object. Top-level --topic and --audience fill missing contract topic/audience fields.',
2762
2788
  '--keyword (SEO mode, limited rollout) sets the Google search keyword the post targets. It is researched when the outline is generated and never replaced automatically.',
2789
+ '--seo (SEO mode, limited rollout) sets how the post uses search: optimize (the outline covers what ranks and keeps your angle), my-way (written as planned; the keyword goes only in the SEO title, meta description and slug) or off. Without it, the profile\'s Search optimization setting applies, and "Ask each time" optimizes.',
2763
2790
  ].join('\n'),
2764
2791
  'workflow run': [
2765
2792
  'Usage: coauthor workflow run <project-id> --target <outline|research|draft> [--planning-model <id>] [--writing-model <id>] [--wait] [--briefing-mode auto|strict|off] [--json]',
@@ -2940,10 +2967,12 @@ function commandHelp(command) {
2940
2967
  'search-brief': [
2941
2968
  'Usage: coauthor search-brief show <project-id> [--json]',
2942
2969
  ' coauthor search-brief set-keyword <project-id> "<keyword>" [--confirm-reset] [--json]',
2970
+ ' coauthor search-brief set-mode <project-id> <optimize|my-way|off> [--confirm-reset] [--json]',
2943
2971
  '',
2944
2972
  'SEO mode (limited rollout). show prints the keyword this post targets, its volume, difficulty and market, and what the ranking pages cover and miss.',
2945
2973
  'set-keyword targets a keyword you choose; CoAuthor researches it (SEO research credits) and never replaces it automatically.',
2946
2974
  'If an outline exists, set-keyword answers confirmation_required: changing the keyword regenerates the outline, research and draft. Repeat with --confirm-reset to proceed.',
2975
+ 'set-mode chooses how the post uses its keyword: optimize (reads what ranks; SEO research credits), my-way (no ranking-page read; the keyword goes only in the SEO title, meta description and slug) or off. optimize and my-way need a search target (no_search_target otherwise). After an outline exists, a change answers confirmation_required like set-keyword.',
2947
2976
  'Accounts outside the rollout get feature_unavailable; projects created before SEO mode launched get seo_not_applicable.',
2948
2977
  ].join('\n'),
2949
2978
  'post-details': [
package/dist/parser.js CHANGED
@@ -55,6 +55,7 @@ const OPTIONS = {
55
55
  excerpt: { type: 'string' },
56
56
  'seo-title': { type: 'string' },
57
57
  keyword: { type: 'string' },
58
+ seo: { type: 'string' },
58
59
  'confirm-reset': { type: 'boolean', default: false },
59
60
  frontmatter: { type: 'boolean', default: false },
60
61
  country: { type: 'string' },
@@ -202,7 +203,7 @@ function commandLength(positionals) {
202
203
  if (first === 'seo')
203
204
  return second === 'markets' ? 2 : 1;
204
205
  if (first === 'search-brief')
205
- return second && ['show', 'set-keyword'].includes(second) ? 2 : 1;
206
+ return second && ['show', 'set-keyword', 'set-mode'].includes(second) ? 2 : 1;
206
207
  if (['contract', 'outline', 'research-plan', 'research', 'draft', 'image', 'thread', 'slideshow', 'publish', 'export', 'operation'].includes(first ?? ''))
207
208
  return second ? 2 : 1;
208
209
  return 1;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.50",
3
+ "version": "0.0.51",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -26,7 +26,9 @@ All fields are optional and omitted ones get defaults, but always include at lea
26
26
  SEO mode is rolling out gradually; accounts outside it get `feature_unavailable` from these commands. When it is on, a post on a searchable topic targets one Google keyword chosen from real search data, and the outline and draft are built around it.
27
27
  - You don't have to do anything: when the outline is generated, CoAuthor checks search demand, picks a keyword the user's site can win, and reads what currently ranks (table stakes, gaps, intent, format, a length hint). This costs SEO research credits and is skipped for topics nobody searches for.
28
28
  - `coauthor project create --keyword "<phrase>" ...` targets a keyword the user already chose; it is researched at outline time and never replaced automatically.
29
- - `coauthor search-brief show <id> --json` shows `data.search_brief`: `status` (`search_play`, `not_search_play`, `not_applicable`, `user_declined`, `not_checked`, or `skipped_busy` / `skipped_credits_exhausted`), the `target` (keyword, monthly volume, difficulty, market, alternatives, secondaries, pages on the user's site that already rank, the information-gain angle), the `analysis` of the ranking pages, and `credits_used`.
29
+ - How a post uses its keyword is its search mode: `optimize` (the outline covers what ranks and keeps the user's angle) or `my-way` (written as the user planned it; the keyword goes only into the SEO title, meta description and slug, and nothing reads what ranks). The profile's Search optimization setting decides it, and "Ask each time" means `optimize` from the CLI. Pass `project create --seo optimize|my-way|off` when the user said how they want this post written; `off` turns search targeting off for the post (not with `--keyword`).
30
+ - `coauthor search-brief set-mode <id> optimize|my-way|off --json` changes it later. `optimize` and `my-way` need a search target (`no_search_target` otherwise). If an outline exists it answers `confirmation_required`, like `set-keyword`.
31
+ - `coauthor search-brief show <id> --json` shows `data.search_brief`: `status` (`search_play`, `not_search_play`, `not_applicable`, `user_declined`, `not_checked`, or `skipped_busy` / `skipped_credits_exhausted`), `mode` (`optimize`, `my-way`, `off`, or null before a check), the `target` (keyword, monthly volume, difficulty, market, alternatives, secondaries, pages on the user's site that already rank, the information-gain angle), the `analysis` of the ranking pages, and `credits_used`.
30
32
  - `coauthor search-brief set-keyword <id> "<phrase>" --json` switches to another keyword (an alternative from `show`, or the user's own). If an outline exists it answers `confirmation_required`: say that the outline, research and draft will be regenerated, and only with the user's OK repeat with `--confirm-reset`.
31
33
  - `target.already_ranking_urls` means the user's site already ranks for the keyword with that page; suggest one of the `alternatives` instead of competing with their own page.
32
34
  - With a target, the outline is built around it: it covers the topics most ranking pages cover (table stakes), gives the information-gain angle its own section, and uses secondary keywords in headings. `coauthor outline revise` then also returns `data.seo_findings` (for example "missing table stakes: ..."); tell the user when an edit dropped something the post needs to rank.
@@ -30,13 +30,15 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
30
30
  | `workflow_token_mismatch`, `conflict` | The project moved on since you read it (for example someone used the web app). | Re-read the state with `coauthor workflow status <id> --json` and continue from there. |
31
31
  | `insufficient_scope` | The token can't publish. | `coauthor auth login --with-publish`. |
32
32
  | `wordpress_connection_required` | Several WordPress sites are connected. | Ask which one from `details.connections`, add `--connection-id`. |
33
- | `feature_unavailable` | SEO features (`search-brief`, `project create --keyword`, `site`) aren't enabled for this account yet, or search data is temporarily unavailable. | Continue without a target keyword; the post is written as usual. |
33
+ | `feature_unavailable` | SEO features (`search-brief`, `project create --keyword` or `--seo`, `site`) aren't enabled for this account yet, or search data is temporarily unavailable. | Continue without a target keyword; the post is written as usual. |
34
34
  | `no_website` | `site status`/`site reindex` on a profile with no website. | Ask the user to add their website to the profile in the web app. |
35
35
  | `reindex_too_soon` | `site reindex` within 15 minutes of the last read. | Wait, or check `coauthor site status`. |
36
36
  | `site_index_unavailable` | The site reader couldn't be reached. | Try again later; posts are still written, just without new internal links. |
37
37
  | `seo_not_applicable` | The project was created before SEO mode launched. | Create a new project with `--keyword`. |
38
- | `confirmation_required` | `search-brief set-keyword` on a project that already has an outline. | Tell the user the outline, research and draft will be regenerated; with their OK, repeat with `--confirm-reset`. |
38
+ | `confirmation_required` | `search-brief set-keyword` or `set-mode` on a project that already has an outline. | Tell the user the outline, research and draft will be regenerated; with their OK, repeat with `--confirm-reset`. |
39
39
  | `invalid_keyword` | The keyword is empty or longer than 200 characters. | Pass a plain search phrase. |
40
+ | `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`. |
41
+ | `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. |
40
42
  | `post_details_unavailable` | The draft was made before post details launched, so it has none to edit. | Pass the slug and description to the export directly. |
41
43
  | `invalid_post_details` | `post-details set` got something other than text for a field. | Pass plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`. |
42
44
  | `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 "..."`. |
@@ -105,7 +105,9 @@ All fields are optional and omitted ones get defaults, but always include at lea
105
105
  SEO mode is rolling out gradually; accounts outside it get `feature_unavailable` from these commands. When it is on, a post on a searchable topic targets one Google keyword chosen from real search data, and the outline and draft are built around it.
106
106
  - You don't have to do anything: when the outline is generated, CoAuthor checks search demand, picks a keyword the user's site can win, and reads what currently ranks (table stakes, gaps, intent, format, a length hint). This costs SEO research credits and is skipped for topics nobody searches for.
107
107
  - `coauthor project create --keyword "<phrase>" ...` targets a keyword the user already chose; it is researched at outline time and never replaced automatically.
108
- - `coauthor search-brief show <id> --json` shows `data.search_brief`: `status` (`search_play`, `not_search_play`, `not_applicable`, `user_declined`, `not_checked`, or `skipped_busy` / `skipped_credits_exhausted`), the `target` (keyword, monthly volume, difficulty, market, alternatives, secondaries, pages on the user's site that already rank, the information-gain angle), the `analysis` of the ranking pages, and `credits_used`.
108
+ - How a post uses its keyword is its search mode: `optimize` (the outline covers what ranks and keeps the user's angle) or `my-way` (written as the user planned it; the keyword goes only into the SEO title, meta description and slug, and nothing reads what ranks). The profile's Search optimization setting decides it, and "Ask each time" means `optimize` from the CLI. Pass `project create --seo optimize|my-way|off` when the user said how they want this post written; `off` turns search targeting off for the post (not with `--keyword`).
109
+ - `coauthor search-brief set-mode <id> optimize|my-way|off --json` changes it later. `optimize` and `my-way` need a search target (`no_search_target` otherwise). If an outline exists it answers `confirmation_required`, like `set-keyword`.
110
+ - `coauthor search-brief show <id> --json` shows `data.search_brief`: `status` (`search_play`, `not_search_play`, `not_applicable`, `user_declined`, `not_checked`, or `skipped_busy` / `skipped_credits_exhausted`), `mode` (`optimize`, `my-way`, `off`, or null before a check), the `target` (keyword, monthly volume, difficulty, market, alternatives, secondaries, pages on the user's site that already rank, the information-gain angle), the `analysis` of the ranking pages, and `credits_used`.
109
111
  - `coauthor search-brief set-keyword <id> "<phrase>" --json` switches to another keyword (an alternative from `show`, or the user's own). If an outline exists it answers `confirmation_required`: say that the outline, research and draft will be regenerated, and only with the user's OK repeat with `--confirm-reset`.
110
112
  - `target.already_ranking_urls` means the user's site already ranks for the keyword with that page; suggest one of the `alternatives` instead of competing with their own page.
111
113
  - With a target, the outline is built around it: it covers the topics most ranking pages cover (table stakes), gives the information-gain angle its own section, and uses secondary keywords in headings. `coauthor outline revise` then also returns `data.seo_findings` (for example "missing table stakes: ..."); tell the user when an edit dropped something the post needs to rank.
@@ -551,13 +553,15 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
551
553
  | `workflow_token_mismatch`, `conflict` | The project moved on since you read it (for example someone used the web app). | Re-read the state with `coauthor workflow status <id> --json` and continue from there. |
552
554
  | `insufficient_scope` | The token can't publish. | `coauthor auth login --with-publish`. |
553
555
  | `wordpress_connection_required` | Several WordPress sites are connected. | Ask which one from `details.connections`, add `--connection-id`. |
554
- | `feature_unavailable` | SEO features (`search-brief`, `project create --keyword`, `site`) aren't enabled for this account yet, or search data is temporarily unavailable. | Continue without a target keyword; the post is written as usual. |
556
+ | `feature_unavailable` | SEO features (`search-brief`, `project create --keyword` or `--seo`, `site`) aren't enabled for this account yet, or search data is temporarily unavailable. | Continue without a target keyword; the post is written as usual. |
555
557
  | `no_website` | `site status`/`site reindex` on a profile with no website. | Ask the user to add their website to the profile in the web app. |
556
558
  | `reindex_too_soon` | `site reindex` within 15 minutes of the last read. | Wait, or check `coauthor site status`. |
557
559
  | `site_index_unavailable` | The site reader couldn't be reached. | Try again later; posts are still written, just without new internal links. |
558
560
  | `seo_not_applicable` | The project was created before SEO mode launched. | Create a new project with `--keyword`. |
559
- | `confirmation_required` | `search-brief set-keyword` on a project that already has an outline. | Tell the user the outline, research and draft will be regenerated; with their OK, repeat with `--confirm-reset`. |
561
+ | `confirmation_required` | `search-brief set-keyword` or `set-mode` on a project that already has an outline. | Tell the user the outline, research and draft will be regenerated; with their OK, repeat with `--confirm-reset`. |
560
562
  | `invalid_keyword` | The keyword is empty or longer than 200 characters. | Pass a plain search phrase. |
563
+ | `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`. |
564
+ | `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. |
561
565
  | `post_details_unavailable` | The draft was made before post details launched, so it has none to edit. | Pass the slug and description to the export directly. |
562
566
  | `invalid_post_details` | `post-details set` got something other than text for a field. | Pass plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`. |
563
567
  | `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 "..."`. |