@clickminded/coauthor-cli 0.0.58 → 0.0.60
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 +2 -0
- package/dist/commands.js +53 -4
- package/dist/parser.js +3 -1
- package/package.json +1 -1
- package/skills/coauthor/SKILL.md +1 -0
- package/skills/coauthor/references/publishing-and-export.md +4 -0
- package/skills/coauthor/references/seo-content-plan.md +9 -0
- package/skills/coauthor/references/troubleshooting.md +1 -1
- package/skills/cursor/coauthor-cli.mdc +15 -1
package/README.md
CHANGED
|
@@ -80,6 +80,7 @@ coauthor repurpose download <id> --out ./social # copy-ready files
|
|
|
80
80
|
coauthor share <id> --json # public read-only link
|
|
81
81
|
coauthor post-details show <id> --json # SEO title, meta description, slug, excerpt
|
|
82
82
|
coauthor post-details set <id> --seo-title "..." --json # exports use these as defaults
|
|
83
|
+
coauthor post-details set <id> --live-url https://example.com/post/ # where the post is live (--clear-live-url removes it)
|
|
83
84
|
coauthor draft get <id> --format markdown --frontmatter --json # markdown with YAML frontmatter
|
|
84
85
|
coauthor export wordpress <id> --yes --json # creates a WordPress draft post (--slug to override)
|
|
85
86
|
coauthor credits <id> --json
|
|
@@ -92,6 +93,7 @@ coauthor seo-plan show --kind post --json # strategy, Do ne
|
|
|
92
93
|
coauthor seo-plan write <item-id> --json # open a project for a post idea, then continue with workflow run
|
|
93
94
|
coauthor seo-plan dismiss <item-id> --json # hide an idea (--undo brings it back)
|
|
94
95
|
coauthor seo-plan done <item-id> --json # mark an idea done, e.g. after improving the page (--undo clears it)
|
|
96
|
+
coauthor seo-plan monthly-check on|off --json # switch the plan's monthly rank check (uses credits; the first check is free)
|
|
95
97
|
```
|
|
96
98
|
|
|
97
99
|
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
|
@@ -754,8 +754,22 @@ async function runPostDetailsCommand(action, input, client) {
|
|
|
754
754
|
if (value !== undefined)
|
|
755
755
|
body[field] = value.trim() ? value : null;
|
|
756
756
|
}
|
|
757
|
+
// The live URL is not an SEO field: the server stores it outside user_edited_fields and keeps it
|
|
758
|
+
// across regeneration and exports. --clear-live-url removes it (auto-detection then leaves the post alone).
|
|
759
|
+
const liveUrl = getString(input.values, 'live-url')?.trim();
|
|
760
|
+
const clearLiveUrl = getBoolean(input.values, 'clear-live-url');
|
|
761
|
+
if (clearLiveUrl && liveUrl)
|
|
762
|
+
throw new Error('Pass either --live-url <url> or --clear-live-url, not both.');
|
|
763
|
+
if (liveUrl) {
|
|
764
|
+
if (!/^https?:\/\/\S+$/i.test(liveUrl))
|
|
765
|
+
throw new Error('--live-url needs a full address starting with http:// or https://.');
|
|
766
|
+
body.published_url = liveUrl;
|
|
767
|
+
}
|
|
768
|
+
else if (clearLiveUrl) {
|
|
769
|
+
body.published_url = null;
|
|
770
|
+
}
|
|
757
771
|
if (Object.keys(body).length === 0) {
|
|
758
|
-
throw new Error('Usage: coauthor post-details set <projectId> [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."]');
|
|
772
|
+
throw new Error('Usage: coauthor post-details set <projectId> [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."] [--live-url <url> | --clear-live-url]');
|
|
759
773
|
}
|
|
760
774
|
return { ok: true, data: await client.request({ method: 'PATCH', path, body }) };
|
|
761
775
|
}
|
|
@@ -2220,6 +2234,7 @@ const SEO_PLAN_USAGE = [
|
|
|
2220
2234
|
' coauthor seo-plan write <item-id> [--json]',
|
|
2221
2235
|
' coauthor seo-plan dismiss <item-id> [--undo] [--json]',
|
|
2222
2236
|
' coauthor seo-plan done <item-id> [--undo] [--json]',
|
|
2237
|
+
' coauthor seo-plan monthly-check on|off [--profile <profile-id>] [--json]',
|
|
2223
2238
|
].join('\n');
|
|
2224
2239
|
function planRecord(value) {
|
|
2225
2240
|
return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
|
|
@@ -2289,6 +2304,17 @@ function seoPlanShowMessage(data, kind) {
|
|
|
2289
2304
|
}
|
|
2290
2305
|
if (view.stale === true)
|
|
2291
2306
|
lines.push('The profile\'s website or market changed since this plan was made. `coauthor seo-plan generate` updates it.');
|
|
2307
|
+
const monthly = view.monthly_check === null || view.monthly_check === undefined ? null : planRecord(view.monthly_check);
|
|
2308
|
+
if (monthly) {
|
|
2309
|
+
if (monthly.enabled === true) {
|
|
2310
|
+
const next = planString(monthly, 'next_check_at');
|
|
2311
|
+
const credits = typeof monthly.estimate_credits === 'number' ? monthly.estimate_credits : null;
|
|
2312
|
+
lines.push(`Monthly check: on${credits ? `, about ${credits} credits a month${monthly.first_check_free === true ? ' (the first check is free)' : ''}` : ''}${next ? `, next on ${next.slice(0, 10)}` : ''}. Turn it off with \`coauthor seo-plan monthly-check off\`.`);
|
|
2313
|
+
}
|
|
2314
|
+
else {
|
|
2315
|
+
lines.push('Monthly check: off. Turn it on with `coauthor seo-plan monthly-check on`.');
|
|
2316
|
+
}
|
|
2317
|
+
}
|
|
2292
2318
|
const strategy = planString(plan, 'strategy_line');
|
|
2293
2319
|
if (strategy)
|
|
2294
2320
|
lines.push(`Strategy: ${strategy}`);
|
|
@@ -2365,7 +2391,7 @@ async function waitForSeoPlan(client, profileId, started) {
|
|
|
2365
2391
|
};
|
|
2366
2392
|
}
|
|
2367
2393
|
async function runSeoPlanCommand(action, input, client) {
|
|
2368
|
-
if (!action || !['show', 'generate', 'write', 'dismiss', 'done'].includes(action))
|
|
2394
|
+
if (!action || !['show', 'generate', 'write', 'dismiss', 'done', 'monthly-check'].includes(action))
|
|
2369
2395
|
throw new Error(SEO_PLAN_USAGE);
|
|
2370
2396
|
if (action === 'show') {
|
|
2371
2397
|
const kind = (getString(input.values, 'kind') ?? 'post').trim().toLowerCase().replace(/-/g, '_');
|
|
@@ -2428,6 +2454,26 @@ async function runSeoPlanCommand(action, input, client) {
|
|
|
2428
2454
|
const result = await waitForSeoPlan(client, profileId, started);
|
|
2429
2455
|
return { ...result, idempotency_key: idempotencyKey };
|
|
2430
2456
|
}
|
|
2457
|
+
if (action === 'monthly-check') {
|
|
2458
|
+
const choice = input.positionals[0]?.trim().toLowerCase();
|
|
2459
|
+
if (choice !== 'on' && choice !== 'off')
|
|
2460
|
+
throw new Error('Usage: coauthor seo-plan monthly-check on|off [--profile <profile-id>]');
|
|
2461
|
+
const profileId = await resolveProfileOption(input, client);
|
|
2462
|
+
const data = await client.request({
|
|
2463
|
+
method: 'PATCH',
|
|
2464
|
+
path: `profiles/${encodeURIComponent(profileId)}/seo-plan/monthly-check`,
|
|
2465
|
+
body: { enabled: choice === 'on' },
|
|
2466
|
+
});
|
|
2467
|
+
const nextCheck = getResponseString(data, 'next_check_at');
|
|
2468
|
+
return {
|
|
2469
|
+
ok: true,
|
|
2470
|
+
message: choice === 'on'
|
|
2471
|
+
? `Monthly check is on${nextCheck ? `; the next one runs on ${nextCheck.slice(0, 10)}` : ''}. It uses credits (your first check is free). Turn it off with \`coauthor seo-plan monthly-check off\`.`
|
|
2472
|
+
: 'Monthly check is off. Rankings and chances stop updating until you turn it on again with `coauthor seo-plan monthly-check on`.',
|
|
2473
|
+
messageIncludesData: true,
|
|
2474
|
+
data,
|
|
2475
|
+
};
|
|
2476
|
+
}
|
|
2431
2477
|
const itemId = input.positionals[0];
|
|
2432
2478
|
if (action === 'write') {
|
|
2433
2479
|
if (!itemId)
|
|
@@ -3281,7 +3327,7 @@ export function helpResult(command = []) {
|
|
|
3281
3327
|
' profile list|show|update (update: --interactive-widgets on|off)',
|
|
3282
3328
|
' widgets list|status|build|build-all|use-image|edit|delete (interactives, beta)',
|
|
3283
3329
|
' site status|reindex [--profile <profile-id>] (limited rollout)',
|
|
3284
|
-
' seo-plan show|generate|write|dismiss|done (limited rollout)',
|
|
3330
|
+
' seo-plan show|generate|write|dismiss|done|monthly-check (limited rollout)',
|
|
3285
3331
|
' source list|add|remove',
|
|
3286
3332
|
' integrations list',
|
|
3287
3333
|
' log add|show',
|
|
@@ -3419,6 +3465,7 @@ function commandHelp(command) {
|
|
|
3419
3465
|
' coauthor seo-plan write <item-id> [--json]',
|
|
3420
3466
|
' coauthor seo-plan dismiss <item-id> [--undo] [--json]',
|
|
3421
3467
|
' coauthor seo-plan done <item-id> [--undo] [--json]',
|
|
3468
|
+
' coauthor seo-plan monthly-check on|off [--profile <profile-id>] [--json]',
|
|
3422
3469
|
'',
|
|
3423
3470
|
'SEO content plan (limited rollout): a business-wide keyword plan for a writer profile, built from live search data and the profile\'s website. Without --profile it uses the default profile.',
|
|
3424
3471
|
'show prints the strategy, the Do next moves, counts per kind, and the ideas of one kind (default post). Kinds: post (written post ideas), improve (existing pages to improve), page (page ideas, not blog posts), left_out (searches skipped, with a reason), covered, not_checked.',
|
|
@@ -3426,6 +3473,7 @@ function commandHelp(command) {
|
|
|
3426
3473
|
'write <item-id> opens a project for a post idea, already set up from the plan, and prints its id and the start prompt. Continue with the normal project flow. Writing the same idea again returns the same project.',
|
|
3427
3474
|
'dismiss hides an idea from the plan; --undo brings it back.',
|
|
3428
3475
|
'done marks an idea as done (for example after you improved the page); --undo clears the mark. A done idea stays in the plan and stays done when the plan is updated.',
|
|
3476
|
+
'monthly-check on|off switches the plan\'s monthly check (free). Once a month it re-checks where each published post ranks on Google, refreshes the plan\'s ranking data and chances, and uses credits (the first check is free). show prints its state: enabled, next_check_at and about how many credits a month. It is absent while monthly checks are not switched on for the account. Turning it on picks the next date at least 25 days after the last check.',
|
|
3429
3477
|
'Errors: not_enabled, profile_not_found, profile_archived, site_required, site_indexing, market_confirmation_needed, market_not_supported, insufficient_credits, plan_running, worker_unavailable, plan_stale, plan_updated, not_writable, plan_item_not_found.',
|
|
3430
3478
|
].join('\n'),
|
|
3431
3479
|
integrations: [
|
|
@@ -3558,10 +3606,11 @@ function commandHelp(command) {
|
|
|
3558
3606
|
].join('\n'),
|
|
3559
3607
|
'post-details': [
|
|
3560
3608
|
'Usage: coauthor post-details show <project-id> [--json]',
|
|
3561
|
-
' coauthor post-details set <project-id> [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."] [--json]',
|
|
3609
|
+
' coauthor post-details set <project-id> [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."] [--live-url <url> | --clear-live-url] [--json]',
|
|
3562
3610
|
'',
|
|
3563
3611
|
'Post details are the SEO title, meta description, slug and excerpt CoAuthor writes after a draft. Exports use them as defaults.',
|
|
3564
3612
|
'set changes only the fields you pass; an empty value clears a field. Edited fields are kept when the draft is regenerated.',
|
|
3613
|
+
'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.',
|
|
3565
3614
|
'Posts drafted before post details launched have none (show returns post_details: null; set returns post_details_unavailable).',
|
|
3566
3615
|
'SEO posts also return seo: the target keyword, market, SEO research credits and a checklist computed from the current draft (pass, warn, fail or skip per check).',
|
|
3567
3616
|
].join('\n'),
|
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
|
+
'live-url': { type: 'string' },
|
|
58
|
+
'clear-live-url': { type: 'boolean', default: false },
|
|
57
59
|
keyword: { type: 'string' },
|
|
58
60
|
seo: { type: 'string' },
|
|
59
61
|
'confirm-reset': { type: 'boolean', default: false },
|
|
@@ -188,7 +190,7 @@ function commandLength(positionals) {
|
|
|
188
190
|
if (first === 'site')
|
|
189
191
|
return second && ['status', 'reindex'].includes(second) ? 2 : 1;
|
|
190
192
|
if (first === 'seo-plan')
|
|
191
|
-
return second && ['show', 'generate', 'write', 'dismiss', 'done'].includes(second) ? 2 : 1;
|
|
193
|
+
return second && ['show', 'generate', 'write', 'dismiss', 'done', 'monthly-check'].includes(second) ? 2 : 1;
|
|
192
194
|
if (first === 'integrations')
|
|
193
195
|
return second === 'list' ? 2 : 1;
|
|
194
196
|
if (first === 'source')
|
package/package.json
CHANGED
package/skills/coauthor/SKILL.md
CHANGED
|
@@ -70,6 +70,7 @@ When the user wants to know what to write about for a business site, or asks for
|
|
|
70
70
|
- `coauthor seo-plan write <item-id> --json` opens a project for a `post` idea, already set up from the plan; continue with `workflow run <project-id> --target outline` as usual. Only `post` items are writable: `improve` items are edits to a page the site already has, and `page` items are site tasks.
|
|
71
71
|
- `coauthor seo-plan dismiss <item-id> [--undo] --json` hides an idea the user rules out.
|
|
72
72
|
- `coauthor seo-plan done <item-id> [--undo] --json` marks an idea done (usually an `improve` page the user has updated). Items carry `done_at`; a done idea stays done when the plan is updated.
|
|
73
|
+
- `coauthor seo-plan monthly-check on|off --json` switches the plan's monthly check, which re-checks where each published post ranks on Google and refreshes the plan's chances. It uses credits (about 30 a month; the first check is free). `show` returns `data.monthly_check` (`enabled`, `next_check_at`, `estimate_credits`), or `null` while it is not switched on for the account.
|
|
73
74
|
|
|
74
75
|
Details, item fields, and what each kind means: `references/seo-content-plan.md`. If a command answers `not_enabled`, the account is outside the rollout; carry on without a plan.
|
|
75
76
|
|
|
@@ -20,10 +20,14 @@ After a draft, CoAuthor writes the post's SEO title, meta description, slug, and
|
|
|
20
20
|
```sh
|
|
21
21
|
coauthor post-details show <id> --json # data.post_details (null for drafts made before post details launched)
|
|
22
22
|
coauthor post-details set <id> --seo-title "..." --description "..." --slug "..." --excerpt "..." --json
|
|
23
|
+
coauthor post-details set <id> --live-url https://example.com/my-post/ --json # where the post is live
|
|
24
|
+
coauthor post-details set <id> --clear-live-url --json
|
|
23
25
|
```
|
|
24
26
|
|
|
25
27
|
`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.
|
|
26
28
|
|
|
29
|
+
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.
|
|
30
|
+
|
|
27
31
|
For SEO posts on a profile with a website, `post_details.incoming_link_suggestions` lists existing pages on the user's site that could link to the new post: `{status, suggestions: [{url, title, anchor, sentence}]}`. `status` is `ready`, `none`, or `index_not_ready` (the site was still being indexed when the draft was written; links appear on the next post). It is read-only. After the post is published, offer the user the sentences to add on those pages, linking the anchor text to the new post's URL. It is `null` for other posts.
|
|
28
32
|
|
|
29
33
|
For SEO posts, `post-details show` also returns `seo`: the target `keyword`, its `market`, `seo_research_credits`, and a `checks` list computed from the current draft and title. Each check has an `id`, a `status` (`pass`, `warn`, `fail`, or `skip` when there is nothing to measure) and a plain `detail`. The ids are `keyword_in_title`, `keyword_in_intro` (first 100 words), `secondary_in_h2`, `table_stakes`, `angle_section`, `questions_answered`, `internal_link`, `outbound_sources` and `length`. A `fail` on the title is worth fixing before publishing: edit it with `project rename`. A `warn` on `keyword_in_intro` is fine when the keyword wouldn't read naturally in the opening, so don't force it in. `secondary_in_h2` and `questions_answered` are optional: they report `pass` or `skip`, never `warn`. `seo` is `null` for other posts.
|
|
@@ -27,6 +27,7 @@ coauthor seo-plan show [--profile <id>] [--kind post|improve|page|left_out|cover
|
|
|
27
27
|
coauthor seo-plan write <item-id> --json
|
|
28
28
|
coauthor seo-plan dismiss <item-id> [--undo] --json
|
|
29
29
|
coauthor seo-plan done <item-id> [--undo] --json
|
|
30
|
+
coauthor seo-plan monthly-check on|off [--profile <id>] --json
|
|
30
31
|
```
|
|
31
32
|
|
|
32
33
|
- Without `--profile` the default profile is used. Run `coauthor profile list --json` first when the user has several profiles and the request names a site or brand.
|
|
@@ -74,6 +75,14 @@ Errors: `plan_stale` (the profile's website or market changed; run `generate` to
|
|
|
74
75
|
|
|
75
76
|
`coauthor seo-plan done <item-id> --json` marks an idea as done and returns `data.item_id` and `data.done_at`. `--undo` clears the mark (`done_at` is `null`). Use it for an `improve` item once the user says the page has been updated, or for any other idea they have finished outside CoAuthor. Do not mark ideas done on your own judgment. Done ideas stay in `show` with a non-null `done_at` (the human output marks them `(done)`), and they stay done when the plan is updated with `generate`. Only `post`, `improve`, `covered` and `page` items can be marked; other ids answer `plan_item_not_found`.
|
|
76
77
|
|
|
78
|
+
## Monthly check
|
|
79
|
+
|
|
80
|
+
Once a month CoAuthor looks up where each published post (one with a target search and a live URL) ranks on Google, refreshes the plan's ranking data and the chance of its top ideas, and records the result. It uses credits, about 30 a month, and the account's first check is free. It is on by default for a plan.
|
|
81
|
+
|
|
82
|
+
`coauthor seo-plan monthly-check on|off [--profile <id>] --json` switches it for that profile's plan and returns `data.enabled` and `data.next_check_at` (`null` when off). Turning it on picks the next date at least 25 days after the last check, so switching does not buy an early check. `show` returns `data.monthly_check` with `enabled`, `next_check_at`, `last_check_at`, `estimate_credits` and `first_check_free`; it is `null` while monthly checks are not switched on for the account, and then there is nothing to switch. Do not turn it off on your own judgment: it is what keeps the plan's rankings and chances current. Errors: `not_enabled`, `profile_not_found`, `plan_not_found` (make the plan first), `invalid_input`.
|
|
83
|
+
|
|
84
|
+
Posts are only tracked once their live URL is known: set it with `coauthor post-details set <id> --live-url <url>` (see `references/publishing-and-export.md`).
|
|
85
|
+
|
|
77
86
|
## What to tell the user
|
|
78
87
|
|
|
79
88
|
Summarize rather than dump: the `strategy_line`, the Do next moves with their `chance` and why, and the counts. Offer to write the first one or two posts. Mention `improve` items separately, because they are quick wins on pages that already rank.
|
|
@@ -50,7 +50,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
50
50
|
| `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`. |
|
|
51
51
|
| `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. |
|
|
52
52
|
| `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. |
|
|
53
|
-
| `invalid_post_details` | `post-details set` got something other than text for a field. | Pass plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`. |
|
|
53
|
+
| `invalid_post_details` | `post-details set` got something other than text for a field, or a live URL that is not an `http` or `https` address. | Pass plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`, and a full address with `--live-url`. |
|
|
54
54
|
| `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 "..."`. |
|
|
55
55
|
| `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
|
|
56
56
|
| `not_a_panel` | `image replace` on an article image. | Only slideshow and video panels can be replaced from the CLI. |
|
|
@@ -72,6 +72,7 @@ When the user wants to know what to write about for a business site, or asks for
|
|
|
72
72
|
- `coauthor seo-plan write <item-id> --json` opens a project for a `post` idea, already set up from the plan; continue with `workflow run <project-id> --target outline` as usual. Only `post` items are writable: `improve` items are edits to a page the site already has, and `page` items are site tasks.
|
|
73
73
|
- `coauthor seo-plan dismiss <item-id> [--undo] --json` hides an idea the user rules out.
|
|
74
74
|
- `coauthor seo-plan done <item-id> [--undo] --json` marks an idea done (usually an `improve` page the user has updated). Items carry `done_at`; a done idea stays done when the plan is updated.
|
|
75
|
+
- `coauthor seo-plan monthly-check on|off --json` switches the plan's monthly check, which re-checks where each published post ranks on Google and refreshes the plan's chances. It uses credits (about 30 a month; the first check is free). `show` returns `data.monthly_check` (`enabled`, `next_check_at`, `estimate_credits`), or `null` while it is not switched on for the account.
|
|
75
76
|
|
|
76
77
|
Details, item fields, and what each kind means: `references/seo-content-plan.md`. If a command answers `not_enabled`, the account is outside the rollout; carry on without a plan.
|
|
77
78
|
|
|
@@ -458,10 +459,14 @@ After a draft, CoAuthor writes the post's SEO title, meta description, slug, and
|
|
|
458
459
|
```sh
|
|
459
460
|
coauthor post-details show <id> --json # data.post_details (null for drafts made before post details launched)
|
|
460
461
|
coauthor post-details set <id> --seo-title "..." --description "..." --slug "..." --excerpt "..." --json
|
|
462
|
+
coauthor post-details set <id> --live-url https://example.com/my-post/ --json # where the post is live
|
|
463
|
+
coauthor post-details set <id> --clear-live-url --json
|
|
461
464
|
```
|
|
462
465
|
|
|
463
466
|
`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.
|
|
464
467
|
|
|
468
|
+
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.
|
|
469
|
+
|
|
465
470
|
For SEO posts on a profile with a website, `post_details.incoming_link_suggestions` lists existing pages on the user's site that could link to the new post: `{status, suggestions: [{url, title, anchor, sentence}]}`. `status` is `ready`, `none`, or `index_not_ready` (the site was still being indexed when the draft was written; links appear on the next post). It is read-only. After the post is published, offer the user the sentences to add on those pages, linking the anchor text to the new post's URL. It is `null` for other posts.
|
|
466
471
|
|
|
467
472
|
For SEO posts, `post-details show` also returns `seo`: the target `keyword`, its `market`, `seo_research_credits`, and a `checks` list computed from the current draft and title. Each check has an `id`, a `status` (`pass`, `warn`, `fail`, or `skip` when there is nothing to measure) and a plain `detail`. The ids are `keyword_in_title`, `keyword_in_intro` (first 100 words), `secondary_in_h2`, `table_stakes`, `angle_section`, `questions_answered`, `internal_link`, `outbound_sources` and `length`. A `fail` on the title is worth fixing before publishing: edit it with `project rename`. A `warn` on `keyword_in_intro` is fine when the keyword wouldn't read naturally in the opening, so don't force it in. `secondary_in_h2` and `questions_answered` are optional: they report `pass` or `skip`, never `warn`. `seo` is `null` for other posts.
|
|
@@ -607,6 +612,7 @@ coauthor seo-plan show [--profile <id>] [--kind post|improve|page|left_out|cover
|
|
|
607
612
|
coauthor seo-plan write <item-id> --json
|
|
608
613
|
coauthor seo-plan dismiss <item-id> [--undo] --json
|
|
609
614
|
coauthor seo-plan done <item-id> [--undo] --json
|
|
615
|
+
coauthor seo-plan monthly-check on|off [--profile <id>] --json
|
|
610
616
|
```
|
|
611
617
|
|
|
612
618
|
- Without `--profile` the default profile is used. Run `coauthor profile list --json` first when the user has several profiles and the request names a site or brand.
|
|
@@ -654,6 +660,14 @@ Errors: `plan_stale` (the profile's website or market changed; run `generate` to
|
|
|
654
660
|
|
|
655
661
|
`coauthor seo-plan done <item-id> --json` marks an idea as done and returns `data.item_id` and `data.done_at`. `--undo` clears the mark (`done_at` is `null`). Use it for an `improve` item once the user says the page has been updated, or for any other idea they have finished outside CoAuthor. Do not mark ideas done on your own judgment. Done ideas stay in `show` with a non-null `done_at` (the human output marks them `(done)`), and they stay done when the plan is updated with `generate`. Only `post`, `improve`, `covered` and `page` items can be marked; other ids answer `plan_item_not_found`.
|
|
656
662
|
|
|
663
|
+
### Monthly check
|
|
664
|
+
|
|
665
|
+
Once a month CoAuthor looks up where each published post (one with a target search and a live URL) ranks on Google, refreshes the plan's ranking data and the chance of its top ideas, and records the result. It uses credits, about 30 a month, and the account's first check is free. It is on by default for a plan.
|
|
666
|
+
|
|
667
|
+
`coauthor seo-plan monthly-check on|off [--profile <id>] --json` switches it for that profile's plan and returns `data.enabled` and `data.next_check_at` (`null` when off). Turning it on picks the next date at least 25 days after the last check, so switching does not buy an early check. `show` returns `data.monthly_check` with `enabled`, `next_check_at`, `last_check_at`, `estimate_credits` and `first_check_free`; it is `null` while monthly checks are not switched on for the account, and then there is nothing to switch. Do not turn it off on your own judgment: it is what keeps the plan's rankings and chances current. Errors: `not_enabled`, `profile_not_found`, `plan_not_found` (make the plan first), `invalid_input`.
|
|
668
|
+
|
|
669
|
+
Posts are only tracked once their live URL is known: set it with `coauthor post-details set <id> --live-url <url>` (see `references/publishing-and-export.md`).
|
|
670
|
+
|
|
657
671
|
### What to tell the user
|
|
658
672
|
|
|
659
673
|
Summarize rather than dump: the `strategy_line`, the Do next moves with their `chance` and why, and the counts. Offer to write the first one or two posts. Mention `improve` items separately, because they are quick wins on pages that already rank.
|
|
@@ -712,7 +726,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
712
726
|
| `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`. |
|
|
713
727
|
| `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. |
|
|
714
728
|
| `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. |
|
|
715
|
-
| `invalid_post_details` | `post-details set` got something other than text for a field. | Pass plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`. |
|
|
729
|
+
| `invalid_post_details` | `post-details set` got something other than text for a field, or a live URL that is not an `http` or `https` address. | Pass plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`, and a full address with `--live-url`. |
|
|
716
730
|
| `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 "..."`. |
|
|
717
731
|
| `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
|
|
718
732
|
| `not_a_panel` | `image replace` on an article image. | Only slideshow and video panels can be replaced from the CLI. |
|