@clickminded/coauthor-cli 0.0.40 → 0.0.42

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/README.md CHANGED
@@ -82,6 +82,8 @@ coauthor export wordpress <id> --yes --json # creates a WordPr
82
82
  coauthor credits <id> --json
83
83
  coauthor integrations list --json # WordPress sites and X accounts
84
84
  coauthor seo markets --country Mexico --language Spanish --json # Google search data coverage for a market
85
+ coauthor search-brief show <id> --json # SEO mode: target keyword and what ranks (limited rollout)
86
+ coauthor search-brief set-keyword <id> "email marketing" --json # target your own keyword (--confirm-reset after an outline)
85
87
  ```
86
88
 
87
89
  Run `coauthor --help` or `coauthor <command> --help` for every command and option. `--json` gives machine-readable output, `--wait` waits for long-running work, and JSON options such as `--data` and `--contract` accept `@file.json` (or `@-` for stdin).
package/dist/commands.js CHANGED
@@ -47,6 +47,8 @@ export async function runCommand(input, context) {
47
47
  return runPostDetailsCommand(action, input, context.client);
48
48
  if (scope === 'seo')
49
49
  return runSeoCommand(action, input, context.client);
50
+ if (scope === 'search-brief')
51
+ return runSearchBriefCommand(action, input, context.client);
50
52
  if (scope === 'workflow')
51
53
  return runWorkflowCommand(action, input, context);
52
54
  if (scope === 'credits')
@@ -273,6 +275,12 @@ async function runProjectCommand(action, input, client) {
273
275
  const profile = getString(input.values, 'profile');
274
276
  if (profile)
275
277
  body.profile_id = profile;
278
+ const keyword = getString(input.values, 'keyword');
279
+ if (keyword !== undefined) {
280
+ if (!keyword.trim())
281
+ throw new Error('--keyword needs a search phrase, e.g. --keyword "email marketing for small business"');
282
+ body.keyword = keyword;
283
+ }
276
284
  const rawContract = getString(input.values, 'contract');
277
285
  if (rawContract !== undefined) {
278
286
  if (!rawContract.trim())
@@ -725,6 +733,46 @@ async function runPostDetailsCommand(action, input, client) {
725
733
  }
726
734
  throw new Error('Usage: coauthor post-details <show|set> <projectId>');
727
735
  }
736
+ function searchBriefMessage(data) {
737
+ const brief = data?.search_brief;
738
+ if (!brief)
739
+ return undefined;
740
+ const target = brief.target;
741
+ if (target && target.decision === 'search_play' && typeof target.keyword === 'string') {
742
+ const facts = [
743
+ typeof target.monthly_volume === 'number' ? `${target.monthly_volume}/mo` : null,
744
+ typeof target.difficulty === 'number' ? `difficulty ${target.difficulty}` : null,
745
+ typeof target.market === 'string' ? target.market : null,
746
+ ].filter(Boolean);
747
+ return `Targeting "${target.keyword}"${facts.length ? ` (${facts.join(', ')})` : ''}.`;
748
+ }
749
+ if (brief.status === 'not_checked')
750
+ 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`.';
751
+ if (typeof target?.explanation === 'string' && target.explanation)
752
+ return target.explanation;
753
+ return typeof brief.status === 'string' ? `Search targeting: ${brief.status}.` : undefined;
754
+ }
755
+ // SEO mode (limited rollout): the keyword this post targets and the research behind it.
756
+ async function runSearchBriefCommand(action, input, client) {
757
+ const projectId = requireProjectId(input);
758
+ const path = `projects/${encodeURIComponent(projectId)}/search-brief`;
759
+ if (!action || action === 'show') {
760
+ const data = await client.request({ path });
761
+ return { ok: true, message: searchBriefMessage(data), data };
762
+ }
763
+ if (action === 'set-keyword') {
764
+ const keyword = getString(input.values, 'keyword') ?? input.positionals.slice(1).join(' ');
765
+ if (!keyword.trim())
766
+ throw new Error('Usage: coauthor search-brief set-keyword <project-id> "<keyword>" [--confirm-reset]');
767
+ const data = await client.request({
768
+ method: 'POST',
769
+ path,
770
+ body: { keyword: keyword.trim(), confirm_reset: input.values['confirm-reset'] === true },
771
+ });
772
+ return { ok: true, message: searchBriefMessage(data), data };
773
+ }
774
+ throw new Error('Usage: coauthor search-brief <show|set-keyword> <project-id>');
775
+ }
728
776
  // Revise by instruction: CoAuthor's editor proposes the change, and the
729
777
  // calling agent reviews the groups and applies or discards them.
730
778
  async function runDraftReviseCommand(projectId, input, context) {
@@ -2611,6 +2659,7 @@ export function helpResult(command = []) {
2611
2659
  ' draft get supports --format json|markdown|html|text (--frontmatter adds post details to markdown)',
2612
2660
  ' post-details show|set',
2613
2661
  ' seo markets [--country <country>] [--language <language>]',
2662
+ ' search-brief show|set-keyword (limited rollout)',
2614
2663
  ' workflow show|status|advance|run|rewind|approve|resume',
2615
2664
  ' workflow run/advance supports --briefing-mode auto|strict|off and --require-brief-review',
2616
2665
  ' image list|status|show|generate|edit|metadata|replace',
@@ -2648,10 +2697,11 @@ function commandHelp(command) {
2648
2697
  '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.',
2649
2698
  ].join('\n'),
2650
2699
  'project create': [
2651
- 'Usage: coauthor project create [--title <title>] [--topic <brief>] [--audience <audience>] [--contract <json>] [--profile <profile-id>] [--json]',
2700
+ 'Usage: coauthor project create [--title <title>] [--topic <brief>] [--audience <audience>] [--contract <json>] [--profile <profile-id>] [--keyword <search phrase>] [--json]',
2652
2701
  '',
2653
2702
  'Creates a project. When --topic or --audience is provided, CoAuthor seeds the saved contract so workflow briefing review can use that context.',
2654
2703
  '--contract accepts a JSON editorial contract object. Top-level --topic and --audience fill missing contract topic/audience fields.',
2704
+ '--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.',
2655
2705
  ].join('\n'),
2656
2706
  'workflow run': [
2657
2707
  'Usage: coauthor workflow run <project-id> --target <outline|research|draft> [--planning-model <id>] [--writing-model <id>] [--wait] [--briefing-mode auto|strict|off] [--json]',
@@ -2821,6 +2871,15 @@ function commandHelp(command) {
2821
2871
  'With both --country and --language it checks one market and explains anything that is not covered, with alternatives.',
2822
2872
  'Countries and languages accept names or codes ("Mexico" or "MX", "Spanish" or "es"). Markets are country-level.',
2823
2873
  ].join('\n'),
2874
+ 'search-brief': [
2875
+ 'Usage: coauthor search-brief show <project-id> [--json]',
2876
+ ' coauthor search-brief set-keyword <project-id> "<keyword>" [--confirm-reset] [--json]',
2877
+ '',
2878
+ 'SEO mode (limited rollout). show prints the keyword this post targets, its volume, difficulty and market, and what the ranking pages cover and miss.',
2879
+ 'set-keyword targets a keyword you choose; CoAuthor researches it (SEO research credits) and never replaces it automatically.',
2880
+ 'If an outline exists, set-keyword answers confirmation_required: changing the keyword regenerates the outline, research and draft. Repeat with --confirm-reset to proceed.',
2881
+ 'Accounts outside the rollout get feature_unavailable; projects created before SEO mode launched get seo_not_applicable.',
2882
+ ].join('\n'),
2824
2883
  'post-details': [
2825
2884
  'Usage: coauthor post-details show <project-id> [--json]',
2826
2885
  ' coauthor post-details set <project-id> [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."] [--json]',
package/dist/parser.js CHANGED
@@ -54,6 +54,8 @@ const OPTIONS = {
54
54
  'connection-id': { type: 'string' },
55
55
  excerpt: { type: 'string' },
56
56
  'seo-title': { type: 'string' },
57
+ keyword: { type: 'string' },
58
+ 'confirm-reset': { type: 'boolean', default: false },
57
59
  frontmatter: { type: 'boolean', default: false },
58
60
  country: { type: 'string' },
59
61
  language: { type: 'string' },
@@ -197,6 +199,8 @@ function commandLength(positionals) {
197
199
  return second && ['show', 'set'].includes(second) ? 2 : 1;
198
200
  if (first === 'seo')
199
201
  return second === 'markets' ? 2 : 1;
202
+ if (first === 'search-brief')
203
+ return second && ['show', 'set-keyword'].includes(second) ? 2 : 1;
200
204
  if (['contract', 'outline', 'research-plan', 'research', 'draft', 'image', 'thread', 'slideshow', 'publish', 'export', 'operation'].includes(first ?? ''))
201
205
  return second ? 2 : 1;
202
206
  return 1;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.40",
3
+ "version": "0.0.42",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -12,7 +12,7 @@ All fields are optional and omitted ones get defaults, but always include at lea
12
12
 
13
13
  ## Profiles and source documents
14
14
 
15
- - `coauthor profile list --json` shows the user's writer profiles: `is_default` marks the one new projects get without `--profile`, plus a `summary` and the `visual_style`. `coauthor profile show <profile id> --json` shows the voice, writer context, and business context in full. Pass `--profile <id>` to `project create`; the profile can't be changed later, so pick deliberately. Profiles are created and edited in the web app (`manage_url`).
15
+ - `coauthor profile list --json` shows the user's writer profiles: `is_default` marks the one new projects get without `--profile`, plus a `summary` and the `visual_style`. `coauthor profile show <profile id> --json` shows the voice, writer context, and business context in full, plus the profile's `website` and `search_country` (null until set in the web app; the search language follows the language each post is written in). Pass `--profile <id>` to `project create`; the profile can't be changed later, so pick deliberately. Profiles are created and edited in the web app (`manage_url`).
16
16
  - `coauthor source add <id> <file>` uploads a reference document CoAuthor's research reads (PDF up to about 3.3 MB through the CLI, .txt or .md up to 512 KB, 5 per project). `coauthor source list <id> --json` shows them; `coauthor source remove <id> <source id> --yes` deletes one.
17
17
  - Add sources before research runs. Adding or removing one after research marks the research and draft stale (the output says `research_invalidated`), so research has to run again.
18
18
 
@@ -20,6 +20,15 @@ All fields are optional and omitted ones get defaults, but always include at lea
20
20
 
21
21
  `coauthor seo markets --country <country> --language <language> --json` checks whether CoAuthor has Google search data for a country and language (names or codes both work). `data.support.tier` is `full` (search volume, keyword difficulty, and ranking checks), `limited` (CoAuthor can analyze what ranks, but not difficulty or existing rankings), `unsupported`, or `unknown_country`. `data.explanation.message` is a sentence you can give the user, and `data.explanation.alternatives` lists covered languages for that country and covered countries for that language. Use `--country` or `--language` alone to list one side; markets are country-level.
22
22
 
23
+ ## Search target (limited rollout)
24
+
25
+ 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.
26
+ - 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.
27
+ - `coauthor project create --keyword "<phrase>" ...` targets a keyword the user already chose; it is researched at outline time and never replaced automatically.
28
+ - `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
+ - `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`.
30
+ - `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.
31
+
23
32
  ## Writing a sharp brief
24
33
 
25
34
  - **Angle over topic.** "Google Business Profile descriptions" is a topic. "Most descriptions fail Google's rules in the first sentence; here is a 20-minute fix" is an angle. Push for the specific claim the piece will make.
@@ -30,6 +30,10 @@ 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 targeting (`search-brief`, `project create --keyword`) isn't enabled for this account yet, or search data is temporarily unavailable. | Continue without a target keyword; the post is written as usual. |
34
+ | `seo_not_applicable` | The project was created before SEO mode launched. | Create a new project with `--keyword`. |
35
+ | `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`. |
36
+ | `invalid_keyword` | The keyword is empty or longer than 200 characters. | Pass a plain search phrase. |
33
37
  | `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. |
34
38
  | `invalid_post_details` | `post-details set` got something other than text for a field. | Pass plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`. |
35
39
  | `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 "..."`. |
@@ -91,7 +91,7 @@ All fields are optional and omitted ones get defaults, but always include at lea
91
91
 
92
92
  ### Profiles and source documents
93
93
 
94
- - `coauthor profile list --json` shows the user's writer profiles: `is_default` marks the one new projects get without `--profile`, plus a `summary` and the `visual_style`. `coauthor profile show <profile id> --json` shows the voice, writer context, and business context in full. Pass `--profile <id>` to `project create`; the profile can't be changed later, so pick deliberately. Profiles are created and edited in the web app (`manage_url`).
94
+ - `coauthor profile list --json` shows the user's writer profiles: `is_default` marks the one new projects get without `--profile`, plus a `summary` and the `visual_style`. `coauthor profile show <profile id> --json` shows the voice, writer context, and business context in full, plus the profile's `website` and `search_country` (null until set in the web app; the search language follows the language each post is written in). Pass `--profile <id>` to `project create`; the profile can't be changed later, so pick deliberately. Profiles are created and edited in the web app (`manage_url`).
95
95
  - `coauthor source add <id> <file>` uploads a reference document CoAuthor's research reads (PDF up to about 3.3 MB through the CLI, .txt or .md up to 512 KB, 5 per project). `coauthor source list <id> --json` shows them; `coauthor source remove <id> <source id> --yes` deletes one.
96
96
  - Add sources before research runs. Adding or removing one after research marks the research and draft stale (the output says `research_invalidated`), so research has to run again.
97
97
 
@@ -99,6 +99,15 @@ All fields are optional and omitted ones get defaults, but always include at lea
99
99
 
100
100
  `coauthor seo markets --country <country> --language <language> --json` checks whether CoAuthor has Google search data for a country and language (names or codes both work). `data.support.tier` is `full` (search volume, keyword difficulty, and ranking checks), `limited` (CoAuthor can analyze what ranks, but not difficulty or existing rankings), `unsupported`, or `unknown_country`. `data.explanation.message` is a sentence you can give the user, and `data.explanation.alternatives` lists covered languages for that country and covered countries for that language. Use `--country` or `--language` alone to list one side; markets are country-level.
101
101
 
102
+ ### Search target (limited rollout)
103
+
104
+ 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.
105
+ - 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.
106
+ - `coauthor project create --keyword "<phrase>" ...` targets a keyword the user already chose; it is researched at outline time and never replaced automatically.
107
+ - `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
+ - `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`.
109
+ - `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.
110
+
102
111
  ### Writing a sharp brief
103
112
 
104
113
  - **Angle over topic.** "Google Business Profile descriptions" is a topic. "Most descriptions fail Google's rules in the first sentence; here is a 20-minute fix" is an angle. Push for the specific claim the piece will make.
@@ -535,6 +544,10 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
535
544
  | `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. |
536
545
  | `insufficient_scope` | The token can't publish. | `coauthor auth login --with-publish`. |
537
546
  | `wordpress_connection_required` | Several WordPress sites are connected. | Ask which one from `details.connections`, add `--connection-id`. |
547
+ | `feature_unavailable` | SEO targeting (`search-brief`, `project create --keyword`) isn't enabled for this account yet, or search data is temporarily unavailable. | Continue without a target keyword; the post is written as usual. |
548
+ | `seo_not_applicable` | The project was created before SEO mode launched. | Create a new project with `--keyword`. |
549
+ | `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`. |
550
+ | `invalid_keyword` | The keyword is empty or longer than 200 characters. | Pass a plain search phrase. |
538
551
  | `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. |
539
552
  | `invalid_post_details` | `post-details set` got something other than text for a field. | Pass plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`. |
540
553
  | `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 "..."`. |