@clickminded/coauthor-cli 0.0.60 → 0.0.62
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 +1 -0
- package/dist/commands.js +103 -2
- package/dist/parser.js +1 -1
- package/package.json +1 -1
- package/skills/coauthor/SKILL.md +2 -1
- package/skills/coauthor/references/seo-content-plan.md +12 -0
- package/skills/cursor/coauthor-cli.mdc +14 -1
package/README.md
CHANGED
|
@@ -94,6 +94,7 @@ coauthor seo-plan write <item-id> --json # open a project
|
|
|
94
94
|
coauthor seo-plan dismiss <item-id> --json # hide an idea (--undo brings it back)
|
|
95
95
|
coauthor seo-plan done <item-id> --json # mark an idea done, e.g. after improving the page (--undo clears it)
|
|
96
96
|
coauthor seo-plan monthly-check on|off --json # switch the plan's monthly rank check (uses credits; the first check is free)
|
|
97
|
+
coauthor seo-plan results --json # where each published post ranks after the last monthly check, and which posts have no live address yet
|
|
97
98
|
```
|
|
98
99
|
|
|
99
100
|
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
|
@@ -2235,6 +2235,7 @@ const SEO_PLAN_USAGE = [
|
|
|
2235
2235
|
' coauthor seo-plan dismiss <item-id> [--undo] [--json]',
|
|
2236
2236
|
' coauthor seo-plan done <item-id> [--undo] [--json]',
|
|
2237
2237
|
' coauthor seo-plan monthly-check on|off [--profile <profile-id>] [--json]',
|
|
2238
|
+
' coauthor seo-plan results [--profile <profile-id>] [--json]',
|
|
2238
2239
|
].join('\n');
|
|
2239
2240
|
function planRecord(value) {
|
|
2240
2241
|
return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
|
|
@@ -2350,6 +2351,98 @@ function seoPlanShowMessage(data, kind) {
|
|
|
2350
2351
|
}
|
|
2351
2352
|
return lines.join('\n');
|
|
2352
2353
|
}
|
|
2354
|
+
// ─── seo-plan results ────────────────────────────────────────────────────────
|
|
2355
|
+
const RESULT_ROWS_SHOWN = 5;
|
|
2356
|
+
function resultChange(row, depth) {
|
|
2357
|
+
const position = typeof row.position === 'number' ? row.position : null;
|
|
2358
|
+
const previous = typeof row.previous_position === 'number' ? row.previous_position : null;
|
|
2359
|
+
switch (row.movement) {
|
|
2360
|
+
case 'not_found': return typeof row.ranking_url === 'string' && row.ranking_url ? 'other page ranks' : `not in top ${depth}`;
|
|
2361
|
+
case 'pending': return 'checked next time';
|
|
2362
|
+
case 'new': return 'new';
|
|
2363
|
+
case 'up': {
|
|
2364
|
+
if (position === null)
|
|
2365
|
+
return 'up';
|
|
2366
|
+
return previous === null ? `now in top ${depth}` : `up ${Math.max(1, previous - position)}`;
|
|
2367
|
+
}
|
|
2368
|
+
case 'down': return position !== null && previous !== null ? `down ${Math.max(1, position - previous)}` : 'down';
|
|
2369
|
+
default: return 'steady';
|
|
2370
|
+
}
|
|
2371
|
+
}
|
|
2372
|
+
function seoPlanCheckReason(check) {
|
|
2373
|
+
if (!check || check.status === 'queued' || check.status === 'running')
|
|
2374
|
+
return null;
|
|
2375
|
+
const code = planString(check, 'error_code');
|
|
2376
|
+
const parts = [];
|
|
2377
|
+
if (check.status === 'skipped') {
|
|
2378
|
+
parts.push(code === 'insufficient_credits' ? 'The last check was skipped because the account did not have enough credits.' : code === 'no_site' ? 'The last check was skipped because the profile has no website.' : 'The last check was skipped.');
|
|
2379
|
+
}
|
|
2380
|
+
else if (check.status === 'failed') {
|
|
2381
|
+
parts.push(code === 'credits_exhausted' ? 'The last check did not finish because credits ran out.' : 'The last check did not finish.');
|
|
2382
|
+
}
|
|
2383
|
+
else if (check.partial === true) {
|
|
2384
|
+
parts.push(planString(check, 'partial_reason') === 'credits_exhausted' ? 'The last check stopped early because credits ran out.' : 'The last check stopped early, so some posts were not checked.');
|
|
2385
|
+
}
|
|
2386
|
+
if (check.status === 'succeeded' && check.plan_refresh_skipped === 'stale')
|
|
2387
|
+
parts.push('The plan\'s chances were not refreshed because the plan needs updating (`coauthor seo-plan generate`).');
|
|
2388
|
+
else if (check.status === 'succeeded' && check.plan_refresh_skipped === 'failed')
|
|
2389
|
+
parts.push('The plan\'s chances were not refreshed because the last plan update did not finish.');
|
|
2390
|
+
return parts.length > 0 ? parts.join(' ') : null;
|
|
2391
|
+
}
|
|
2392
|
+
function seoPlanResultsMessage(data) {
|
|
2393
|
+
const view = planRecord(data);
|
|
2394
|
+
const monthly = view.monthly_check === null || view.monthly_check === undefined ? null : planRecord(view.monthly_check);
|
|
2395
|
+
if (!view.plan)
|
|
2396
|
+
return 'No SEO content plan for this profile yet, so there is nothing to track. Make one with `coauthor seo-plan generate --wait`.';
|
|
2397
|
+
if (!monthly)
|
|
2398
|
+
return 'Monthly checks are not switched on for this account yet, so there are no results to show.';
|
|
2399
|
+
const lines = [];
|
|
2400
|
+
const last = planString(monthly, 'last_check_at');
|
|
2401
|
+
const next = planString(monthly, 'next_check_at');
|
|
2402
|
+
if (last)
|
|
2403
|
+
lines.push(`Last checked ${last.slice(0, 10)}${monthly.enabled === true ? (next ? `; next check ${next.slice(0, 10)}` : '') : '; the monthly check is off (`coauthor seo-plan monthly-check on` turns it on)'}.`);
|
|
2404
|
+
else if (monthly.enabled !== true)
|
|
2405
|
+
lines.push('The monthly check is off. Turn it on with `coauthor seo-plan monthly-check on`.');
|
|
2406
|
+
else
|
|
2407
|
+
lines.push(`The first check has not run yet${next ? `; it runs on ${next.slice(0, 10)}` : ''}${monthly.first_check_free === true ? ' and is free' : ''}.`);
|
|
2408
|
+
const lastCheck = view.last_check === null || view.last_check === undefined ? null : planRecord(view.last_check);
|
|
2409
|
+
const depth = lastCheck && typeof lastCheck.depth === 'number' ? lastCheck.depth : 30;
|
|
2410
|
+
const rows = Array.isArray(view.results) ? view.results.map(planRecord) : [];
|
|
2411
|
+
if (rows.length > 0) {
|
|
2412
|
+
const onPageOne = rows.filter((row) => typeof row.position === 'number' && row.position <= 10).length; // pending rows have no position, so they only count as tracked
|
|
2413
|
+
const up = rows.filter((row) => row.movement === 'up').length;
|
|
2414
|
+
const down = rows.filter((row) => row.movement === 'down').length;
|
|
2415
|
+
lines.push([
|
|
2416
|
+
onPageOne > 0 ? `${onPageOne} ${onPageOne === 1 ? 'post' : 'posts'} on page one` : null,
|
|
2417
|
+
up > 0 ? `${up} moved up` : null,
|
|
2418
|
+
down > 0 ? `${down} moved down` : null,
|
|
2419
|
+
`${rows.length} tracked`,
|
|
2420
|
+
].filter(Boolean).join(' · '), '');
|
|
2421
|
+
for (const row of rows) {
|
|
2422
|
+
const position = typeof row.position === 'number' ? `#${row.position}` : '--';
|
|
2423
|
+
lines.push(` ${position.padEnd(4)} ${resultChange(row, depth).padEnd(16)} ${planString(row, 'title') ?? 'Untitled'} [search: ${planString(row, 'keyword') ?? ''}]`);
|
|
2424
|
+
lines.push(` ${planString(row, 'tracked_url') ?? ''} (project ${planString(row, 'project_id') ?? ''})`);
|
|
2425
|
+
const otherPage = planString(row, 'ranking_url');
|
|
2426
|
+
if (row.movement === 'not_found' && otherPage)
|
|
2427
|
+
lines.push(` another page of the site ranks for this search instead: ${otherPage}`);
|
|
2428
|
+
}
|
|
2429
|
+
}
|
|
2430
|
+
else {
|
|
2431
|
+
lines.push('No posts are tracked yet. A post is tracked once it has a target search and a live address.');
|
|
2432
|
+
}
|
|
2433
|
+
const missing = Array.isArray(view.missing_urls) ? view.missing_urls.map(planRecord) : [];
|
|
2434
|
+
if (missing.length > 0) {
|
|
2435
|
+
lines.push('', `${missing.length} ${missing.length === 1 ? 'post has' : 'posts have'} no live address yet, so ${missing.length === 1 ? 'it is' : 'they are'} not tracked. Set one with \`coauthor post-details set <project-id> --live-url <url>\`:`);
|
|
2436
|
+
for (const row of missing.slice(0, RESULT_ROWS_SHOWN))
|
|
2437
|
+
lines.push(` ${planString(row, 'project_id') ?? ''} ${planString(row, 'title') ?? 'Untitled'} [search: ${planString(row, 'keyword') ?? ''}]`);
|
|
2438
|
+
if (missing.length > RESULT_ROWS_SHOWN)
|
|
2439
|
+
lines.push(` and ${missing.length - RESULT_ROWS_SHOWN} more (see --json data.missing_urls).`);
|
|
2440
|
+
}
|
|
2441
|
+
const reason = seoPlanCheckReason(lastCheck);
|
|
2442
|
+
if (reason)
|
|
2443
|
+
lines.push('', reason);
|
|
2444
|
+
return lines.join('\n');
|
|
2445
|
+
}
|
|
2353
2446
|
function seoPlanWaitFailure(status) {
|
|
2354
2447
|
const code = planString(status, 'error_code');
|
|
2355
2448
|
const message = planString(status, 'error_message') ?? 'The plan run failed.';
|
|
@@ -2391,8 +2484,14 @@ async function waitForSeoPlan(client, profileId, started) {
|
|
|
2391
2484
|
};
|
|
2392
2485
|
}
|
|
2393
2486
|
async function runSeoPlanCommand(action, input, client) {
|
|
2394
|
-
if (!action || !['show', 'generate', 'write', 'dismiss', 'done', 'monthly-check'].includes(action))
|
|
2487
|
+
if (!action || !['show', 'generate', 'write', 'dismiss', 'done', 'monthly-check', 'results'].includes(action))
|
|
2395
2488
|
throw new Error(SEO_PLAN_USAGE);
|
|
2489
|
+
if (action === 'results') {
|
|
2490
|
+
const profileId = await resolveProfileOption(input, client);
|
|
2491
|
+
// `limit=1`: the results do not depend on the ideas, so ask for the smallest list.
|
|
2492
|
+
const data = await client.request({ path: `profiles/${encodeURIComponent(profileId)}/seo-plan?limit=1` });
|
|
2493
|
+
return { ok: true, message: seoPlanResultsMessage(data), messageIncludesData: true, data };
|
|
2494
|
+
}
|
|
2396
2495
|
if (action === 'show') {
|
|
2397
2496
|
const kind = (getString(input.values, 'kind') ?? 'post').trim().toLowerCase().replace(/-/g, '_');
|
|
2398
2497
|
if (!SEO_PLAN_KINDS.includes(kind)) {
|
|
@@ -3327,7 +3426,7 @@ export function helpResult(command = []) {
|
|
|
3327
3426
|
' profile list|show|update (update: --interactive-widgets on|off)',
|
|
3328
3427
|
' widgets list|status|build|build-all|use-image|edit|delete (interactives, beta)',
|
|
3329
3428
|
' site status|reindex [--profile <profile-id>] (limited rollout)',
|
|
3330
|
-
' seo-plan show|generate|write|dismiss|done|monthly-check (limited rollout)',
|
|
3429
|
+
' seo-plan show|generate|write|dismiss|done|monthly-check|results (limited rollout)',
|
|
3331
3430
|
' source list|add|remove',
|
|
3332
3431
|
' integrations list',
|
|
3333
3432
|
' log add|show',
|
|
@@ -3466,6 +3565,7 @@ function commandHelp(command) {
|
|
|
3466
3565
|
' coauthor seo-plan dismiss <item-id> [--undo] [--json]',
|
|
3467
3566
|
' coauthor seo-plan done <item-id> [--undo] [--json]',
|
|
3468
3567
|
' coauthor seo-plan monthly-check on|off [--profile <profile-id>] [--json]',
|
|
3568
|
+
' coauthor seo-plan results [--profile <profile-id>] [--json]',
|
|
3469
3569
|
'',
|
|
3470
3570
|
'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.',
|
|
3471
3571
|
'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.',
|
|
@@ -3474,6 +3574,7 @@ function commandHelp(command) {
|
|
|
3474
3574
|
'dismiss hides an idea from the plan; --undo brings it back.',
|
|
3475
3575
|
'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
3576
|
'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.',
|
|
3577
|
+
'results prints where each tracked post ranked at the last monthly check (position, change since the check before, live address; a post no check has read yet reads "checked next time"; when another page of the site ranks instead it prints that page), the published or submitted posts that have a target search but no live address yet, and why the last check did less than a full job. --json returns data.results, data.missing_urls, data.last_check and data.monthly_check. Without monthly checks switched on for the account there are no results. A post is tracked once it has a target search and a live address: set one with `coauthor post-details set <project-id> --live-url <url>`.',
|
|
3477
3578
|
'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.',
|
|
3478
3579
|
].join('\n'),
|
|
3479
3580
|
integrations: [
|
package/dist/parser.js
CHANGED
|
@@ -190,7 +190,7 @@ function commandLength(positionals) {
|
|
|
190
190
|
if (first === 'site')
|
|
191
191
|
return second && ['status', 'reindex'].includes(second) ? 2 : 1;
|
|
192
192
|
if (first === 'seo-plan')
|
|
193
|
-
return second && ['show', 'generate', 'write', 'dismiss', 'done', 'monthly-check'].includes(second) ? 2 : 1;
|
|
193
|
+
return second && ['show', 'generate', 'write', 'dismiss', 'done', 'monthly-check', 'results'].includes(second) ? 2 : 1;
|
|
194
194
|
if (first === 'integrations')
|
|
195
195
|
return second === 'list' ? 2 : 1;
|
|
196
196
|
if (first === 'source')
|
package/package.json
CHANGED
package/skills/coauthor/SKILL.md
CHANGED
|
@@ -71,6 +71,7 @@ When the user wants to know what to write about for a business site, or asks for
|
|
|
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
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.
|
|
74
|
+
- `coauthor seo-plan results --json` reads the last monthly check: where each tracked post ranks on Google (`data.results`: `position`, `previous_position`, `movement`, `ranking_url`), the published or submitted posts that have no live address yet (`data.missing_urls`), and how the check went (`data.last_check`). Posts without a live address are not tracked; set one with `coauthor post-details set <id> --live-url <url>`.
|
|
74
75
|
|
|
75
76
|
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.
|
|
76
77
|
|
|
@@ -80,4 +81,4 @@ Details, item fields, and what each kind means: `references/seo-content-plan.md`
|
|
|
80
81
|
|
|
81
82
|
## Not in the CLI yet
|
|
82
83
|
|
|
83
|
-
Creating writer profiles or editing a profile's voice and contexts (only the interactives switch can be set from the CLI), PDFs over about 3.3 MB, adding more images than CoAuthor planned,
|
|
84
|
+
Creating writer profiles or editing a profile's voice and contexts (only the interactives switch can be set from the CLI), PDFs over about 3.3 MB, adding more images than CoAuthor planned, correcting an SEO content plan's competitor list, and turning the monthly SEO report email off (Settings, then Email). Point the user to the CoAuthor web app at https://tools.clickminded.com/coauthor for these instead of improvising.
|
|
@@ -28,6 +28,7 @@ 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
30
|
coauthor seo-plan monthly-check on|off [--profile <id>] --json
|
|
31
|
+
coauthor seo-plan results [--profile <id>] --json
|
|
31
32
|
```
|
|
32
33
|
|
|
33
34
|
- 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.
|
|
@@ -83,6 +84,17 @@ Once a month CoAuthor looks up where each published post (one with a target sear
|
|
|
83
84
|
|
|
84
85
|
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
86
|
|
|
87
|
+
### Results
|
|
88
|
+
|
|
89
|
+
`coauthor seo-plan results [--profile <id>] --json` shows what the last monthly check found; the human output is a short list. The same fields come back from `show` (`data.results`, `data.missing_urls`, `data.last_check`, `data.monthly_check`).
|
|
90
|
+
|
|
91
|
+
- `data.results` has one row per tracked post (a live address and a target search), best news first (moved up, then page one by position, then the rest, then posts no check has read yet): `project_id`, `title`, `keyword`, `tracked_url`, `position`, `previous_position`, `movement`, `ranking_url` and `checked_at`. `position` is Google's organic position; page one means 10 or better. It is `null` when the post's address is not within the top results the check looked at (`data.last_check.depth`, 30 by default), and `movement` is then `not_found`; if `ranking_url` is set, another page of the same site ranks for that search instead, which is worth telling the user. `movement` is `up` or `down` only for a move of 3 places or more, or a move onto or off page one; `same` is steady; `new` means the first reading of that search and address, so there is nothing to compare with yet; `pending` means the post went live after the last check and has no reading yet (`position` and `checked_at` are `null`; the next check reads it).
|
|
92
|
+
- `data.missing_urls` lists published or submitted posts that have a target search but no live address (`project_id`, `title`, `keyword`); drafts are left out. They are not tracked until you set one with `coauthor post-details set <project-id> --live-url <url>`; the next check picks it up.
|
|
93
|
+
- `data.last_check` is `{status, finished_at, partial, partial_reason, plan_refresh_skipped, error_code, credits_charged, free, depth}`. `partial` means the check stopped early (for example credits ran out); `plan_refresh_skipped` (`stale` or `failed`) means the plan's own chances were not refreshed because the plan needs updating, so run `coauthor seo-plan generate`. `status` `skipped` with `error_code` `insufficient_credits` means the account had too few credits and nothing was spent.
|
|
94
|
+
- Everything is empty or `null` while monthly checks are not switched on for the account, and before the first check has run.
|
|
95
|
+
|
|
96
|
+
When you report results, lead with what moved up and what reached page one, then name any posts without a live address. Do not call a `same` post a failure: one monthly reading is noisy.
|
|
97
|
+
|
|
86
98
|
## What to tell the user
|
|
87
99
|
|
|
88
100
|
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.
|
|
@@ -73,6 +73,7 @@ When the user wants to know what to write about for a business site, or asks for
|
|
|
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
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.
|
|
76
|
+
- `coauthor seo-plan results --json` reads the last monthly check: where each tracked post ranks on Google (`data.results`: `position`, `previous_position`, `movement`, `ranking_url`), the published or submitted posts that have no live address yet (`data.missing_urls`), and how the check went (`data.last_check`). Posts without a live address are not tracked; set one with `coauthor post-details set <id> --live-url <url>`.
|
|
76
77
|
|
|
77
78
|
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.
|
|
78
79
|
|
|
@@ -82,7 +83,7 @@ Details, item fields, and what each kind means: `references/seo-content-plan.md`
|
|
|
82
83
|
|
|
83
84
|
## Not in the CLI yet
|
|
84
85
|
|
|
85
|
-
Creating writer profiles or editing a profile's voice and contexts (only the interactives switch can be set from the CLI), PDFs over about 3.3 MB, adding more images than CoAuthor planned,
|
|
86
|
+
Creating writer profiles or editing a profile's voice and contexts (only the interactives switch can be set from the CLI), PDFs over about 3.3 MB, adding more images than CoAuthor planned, correcting an SEO content plan's competitor list, and turning the monthly SEO report email off (Settings, then Email). Point the user to the CoAuthor web app at https://tools.clickminded.com/coauthor for these instead of improvising.
|
|
86
87
|
|
|
87
88
|
# Reference sections
|
|
88
89
|
|
|
@@ -613,6 +614,7 @@ coauthor seo-plan write <item-id> --json
|
|
|
613
614
|
coauthor seo-plan dismiss <item-id> [--undo] --json
|
|
614
615
|
coauthor seo-plan done <item-id> [--undo] --json
|
|
615
616
|
coauthor seo-plan monthly-check on|off [--profile <id>] --json
|
|
617
|
+
coauthor seo-plan results [--profile <id>] --json
|
|
616
618
|
```
|
|
617
619
|
|
|
618
620
|
- 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.
|
|
@@ -668,6 +670,17 @@ Once a month CoAuthor looks up where each published post (one with a target sear
|
|
|
668
670
|
|
|
669
671
|
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
672
|
|
|
673
|
+
#### Results
|
|
674
|
+
|
|
675
|
+
`coauthor seo-plan results [--profile <id>] --json` shows what the last monthly check found; the human output is a short list. The same fields come back from `show` (`data.results`, `data.missing_urls`, `data.last_check`, `data.monthly_check`).
|
|
676
|
+
|
|
677
|
+
- `data.results` has one row per tracked post (a live address and a target search), best news first (moved up, then page one by position, then the rest, then posts no check has read yet): `project_id`, `title`, `keyword`, `tracked_url`, `position`, `previous_position`, `movement`, `ranking_url` and `checked_at`. `position` is Google's organic position; page one means 10 or better. It is `null` when the post's address is not within the top results the check looked at (`data.last_check.depth`, 30 by default), and `movement` is then `not_found`; if `ranking_url` is set, another page of the same site ranks for that search instead, which is worth telling the user. `movement` is `up` or `down` only for a move of 3 places or more, or a move onto or off page one; `same` is steady; `new` means the first reading of that search and address, so there is nothing to compare with yet; `pending` means the post went live after the last check and has no reading yet (`position` and `checked_at` are `null`; the next check reads it).
|
|
678
|
+
- `data.missing_urls` lists published or submitted posts that have a target search but no live address (`project_id`, `title`, `keyword`); drafts are left out. They are not tracked until you set one with `coauthor post-details set <project-id> --live-url <url>`; the next check picks it up.
|
|
679
|
+
- `data.last_check` is `{status, finished_at, partial, partial_reason, plan_refresh_skipped, error_code, credits_charged, free, depth}`. `partial` means the check stopped early (for example credits ran out); `plan_refresh_skipped` (`stale` or `failed`) means the plan's own chances were not refreshed because the plan needs updating, so run `coauthor seo-plan generate`. `status` `skipped` with `error_code` `insufficient_credits` means the account had too few credits and nothing was spent.
|
|
680
|
+
- Everything is empty or `null` while monthly checks are not switched on for the account, and before the first check has run.
|
|
681
|
+
|
|
682
|
+
When you report results, lead with what moved up and what reached page one, then name any posts without a live address. Do not call a `same` post a failure: one monthly reading is noisy.
|
|
683
|
+
|
|
671
684
|
### What to tell the user
|
|
672
685
|
|
|
673
686
|
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.
|