@clickminded/coauthor-cli 0.0.89 → 0.0.91
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 +5 -1
- package/dist/commands.d.ts +3 -0
- package/dist/commands.js +362 -1
- package/dist/parser.d.ts +2 -0
- package/dist/parser.js +16 -0
- package/package.json +1 -1
- package/skills/coauthor/SKILL.md +4 -4
- package/skills/coauthor/references/credits-and-plans.md +1 -0
- package/skills/coauthor/references/images-and-social.md +22 -0
- package/skills/coauthor/references/publishing-and-export.md +5 -1
- package/skills/coauthor/references/repurposing.md +1 -1
- package/skills/coauthor/references/seo-content-plan.md +1 -1
- package/skills/coauthor/references/troubleshooting.md +14 -1
- package/skills/cursor/coauthor-cli.mdc +48 -8
package/README.md
CHANGED
|
@@ -77,6 +77,9 @@ coauthor widgets list <id> --json # interactives (b
|
|
|
77
77
|
coauthor widgets build-all <id> --wait --json # spends credits: show the placeholders to the user first
|
|
78
78
|
coauthor repurpose generate <id> --format all --json # X thread and post, LinkedIn, Facebook, email newsletter
|
|
79
79
|
coauthor repurpose download <id> --out ./social # copy-ready files plus the article
|
|
80
|
+
coauthor social accounts --json # connected social accounts (connect them in the web app: Settings → Publishing)
|
|
81
|
+
coauthor social preview <id> --format linkedin --variant <variation id> --account linkedin --json # what would be posted, the link check and the credits
|
|
82
|
+
coauthor social list <id> --json # the project's scheduled and published social posts
|
|
80
83
|
coauthor share <id> --json # public read-only link
|
|
81
84
|
coauthor post-details show <id> --json # SEO title, meta description, slug, excerpt
|
|
82
85
|
coauthor post-details set <id> --seo-title "..." --json # exports use these as defaults
|
|
@@ -102,11 +105,12 @@ Run `coauthor --help` or `coauthor <command> --help` for every command and optio
|
|
|
102
105
|
|
|
103
106
|
## Live actions
|
|
104
107
|
|
|
105
|
-
Publishing an X thread and exporting to WordPress are real side effects. They need a login with publish permission and an explicit `--yes`:
|
|
108
|
+
Publishing an X thread, posting to social accounts and exporting to WordPress are real side effects. They need a login with publish permission and an explicit `--yes`:
|
|
106
109
|
|
|
107
110
|
```sh
|
|
108
111
|
coauthor auth login --with-publish
|
|
109
112
|
coauthor publish thread <id> --yes --json
|
|
113
|
+
coauthor social post <id> --format linkedin --variant <variation id> --account linkedin --at 2026-11-20T09:00:00-05:00 --yes --json # or --now; --link <url> fills {{POST_URL}}; --wait follows it
|
|
110
114
|
coauthor export wordpress <id> --yes --json
|
|
111
115
|
```
|
|
112
116
|
|
package/dist/commands.d.ts
CHANGED
|
@@ -24,6 +24,8 @@ export declare function draftCompletionMessage(base: string, status: JsonValue):
|
|
|
24
24
|
export declare function seoPlanAiSearchLines(value: unknown): string[];
|
|
25
25
|
/** "AI search mentions since 2026-11-18: Google AI answers 482 (up 12), ChatGPT 37 (down 3)." Null without a comparison. */
|
|
26
26
|
export declare function seoPlanAiTrendLine(value: unknown): string | null;
|
|
27
|
+
type SocialRecord = Record<string, JsonValue>;
|
|
28
|
+
export declare function describeSocialPost(post: SocialRecord): string;
|
|
27
29
|
/**
|
|
28
30
|
* `--cta save,follow,custom:Join the webinar` -> the web app's cta_variants
|
|
29
31
|
* list (at most 4 endings, at most one custom).
|
|
@@ -31,3 +33,4 @@ export declare function seoPlanAiTrendLine(value: unknown): string | null;
|
|
|
31
33
|
export declare function parseSlideshowCtaOption(raw: string): JsonValue[];
|
|
32
34
|
export declare function creditsExhaustedPauseResult(projectId: string, target: 'research' | 'draft', message: string, data: JsonValue): CommandResult;
|
|
33
35
|
export declare function helpResult(command?: string[]): CommandResult;
|
|
36
|
+
export {};
|
package/dist/commands.js
CHANGED
|
@@ -8,7 +8,7 @@ import { basename, dirname, join, resolve } from 'node:path';
|
|
|
8
8
|
import { fileURLToPath } from 'node:url';
|
|
9
9
|
import { AgentHttpError, AgentRequestError, normalizeBaseUrl } from './client.js';
|
|
10
10
|
import { clearConfig, loadConfig, saveConfig } from './config.js';
|
|
11
|
-
import { getBoolean, getString, parseJsonOption, readJsonOptionText } from './parser.js';
|
|
11
|
+
import { getBoolean, getString, getStringList, parseJsonOption, readJsonOptionText } from './parser.js';
|
|
12
12
|
export async function runCommand(input, context) {
|
|
13
13
|
const [scope, action] = input.command;
|
|
14
14
|
if (!scope)
|
|
@@ -57,6 +57,8 @@ export async function runCommand(input, context) {
|
|
|
57
57
|
return runSearchBriefCommand(action, input, context.client);
|
|
58
58
|
if (scope === 'workflow')
|
|
59
59
|
return runWorkflowCommand(action, input, context);
|
|
60
|
+
if (scope === 'social')
|
|
61
|
+
return runSocialCommand(action, input, context.client);
|
|
60
62
|
if (scope === 'credits')
|
|
61
63
|
return runCreditsCommand(input, context.client);
|
|
62
64
|
if (scope === 'share')
|
|
@@ -3018,6 +3020,343 @@ async function runLogCommand(action, input, client) {
|
|
|
3018
3020
|
}
|
|
3019
3021
|
throw new Error('Usage: coauthor log <add|show> <projectId>');
|
|
3020
3022
|
}
|
|
3023
|
+
// ── Social posting ─────────────────────────────────────────────────────────────────────────────────
|
|
3024
|
+
// Posts a repurposed format to the user's connected social accounts (connected in the web app, Settings →
|
|
3025
|
+
// Publishing). Posting and retrying are recorded operations keyed by the Idempotency-Key, so a rerun with the same
|
|
3026
|
+
// --idempotency-key replays instead of posting twice. TikTok posts stay in the web app (tiktok_web_only).
|
|
3027
|
+
const SOCIAL_FORMATS = ['x-thread', 'x-post', 'linkedin', 'facebook', 'slideshow', 'video'];
|
|
3028
|
+
const SOCIAL_LINK_FORMATS = ['x-thread', 'x-post', 'linkedin', 'facebook'];
|
|
3029
|
+
const SOCIAL_MEDIA_FORMATS = ['slideshow', 'video'];
|
|
3030
|
+
const SOCIAL_VARIANT_REQUIRED = ['x-post', 'linkedin', 'facebook', 'video'];
|
|
3031
|
+
const SOCIAL_SETTLED_STATUSES = new Set(['published', 'partial', 'failed', 'cancelled']);
|
|
3032
|
+
const SOCIAL_PLATFORM_LABELS = { twitter: 'X', linkedin: 'LinkedIn', facebook: 'Facebook', instagram: 'Instagram', youtube: 'YouTube', tiktok: 'TikTok' };
|
|
3033
|
+
const ISO_TIME_WITH_OFFSET = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})$/i;
|
|
3034
|
+
const SOCIAL_POST_USAGE = 'Usage: coauthor social post <project-id> --format <x-thread|x-post|linkedin|facebook|slideshow|video> [--variant <id>] --account <id|platform|@username> (--now | --at <ISO time>) [--link <url>] [--caption "..."] [--youtube-title "..."] [--timezone <zone>] --yes [--idempotency-key <key>] [--wait] [--json]';
|
|
3035
|
+
const SOCIAL_PREVIEW_USAGE = 'Usage: coauthor social preview <project-id> --format <x-thread|x-post|linkedin|facebook|slideshow|video> [--variant <id>] [--account <id|platform|@username>] [--caption "..."] [--youtube-title "..."] [--json]';
|
|
3036
|
+
function socialRecord(value) {
|
|
3037
|
+
return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
|
|
3038
|
+
}
|
|
3039
|
+
function socialList(value) {
|
|
3040
|
+
return Array.isArray(value) ? value.map((entry) => socialRecord(entry)).filter((entry) => entry !== null) : [];
|
|
3041
|
+
}
|
|
3042
|
+
function socialFormatOption(input, usage) {
|
|
3043
|
+
const raw = getString(input.values, 'format')?.trim().toLowerCase();
|
|
3044
|
+
if (!raw)
|
|
3045
|
+
throw new Error(usage);
|
|
3046
|
+
const format = raw === 'carousel' ? 'slideshow' : raw === 'thread' ? 'x-thread' : raw.replace(/_/g, '-');
|
|
3047
|
+
if (!SOCIAL_FORMATS.includes(format))
|
|
3048
|
+
throw new Error(`--format must be one of: ${SOCIAL_FORMATS.join(', ')} (email newsletters are not posted to social accounts).`);
|
|
3049
|
+
return format;
|
|
3050
|
+
}
|
|
3051
|
+
function socialTimeOption(raw, flag) {
|
|
3052
|
+
const value = raw.trim();
|
|
3053
|
+
const parsed = new Date(value);
|
|
3054
|
+
if (!ISO_TIME_WITH_OFFSET.test(value) || Number.isNaN(parsed.getTime())) {
|
|
3055
|
+
throw new Error(`${flag} needs an ISO time with a timezone offset, for example 2026-11-20T09:00:00-05:00 or 2026-11-20T14:00:00Z.`);
|
|
3056
|
+
}
|
|
3057
|
+
return parsed.toISOString();
|
|
3058
|
+
}
|
|
3059
|
+
function localTimezone() {
|
|
3060
|
+
try {
|
|
3061
|
+
return Intl.DateTimeFormat().resolvedOptions().timeZone || null;
|
|
3062
|
+
}
|
|
3063
|
+
catch {
|
|
3064
|
+
return null;
|
|
3065
|
+
}
|
|
3066
|
+
}
|
|
3067
|
+
function socialMediaOptions(input, format) {
|
|
3068
|
+
const caption = getString(input.values, 'caption');
|
|
3069
|
+
const youtubeTitle = getString(input.values, 'youtube-title');
|
|
3070
|
+
if (caption !== undefined && !SOCIAL_MEDIA_FORMATS.includes(format)) {
|
|
3071
|
+
throw new Error('--caption only applies to --format slideshow or video. Text formats post their saved text; edit it with coauthor repurpose save.');
|
|
3072
|
+
}
|
|
3073
|
+
if (youtubeTitle !== undefined && format !== 'video')
|
|
3074
|
+
throw new Error('--youtube-title only applies to --format video.');
|
|
3075
|
+
return {
|
|
3076
|
+
...(caption !== undefined ? { caption } : {}),
|
|
3077
|
+
...(youtubeTitle !== undefined ? { youtube_title: youtubeTitle } : {}),
|
|
3078
|
+
};
|
|
3079
|
+
}
|
|
3080
|
+
function socialAccountLabel(account) {
|
|
3081
|
+
const platform = SOCIAL_PLATFORM_LABELS[String(account.platform)] ?? String(account.platform);
|
|
3082
|
+
const name = typeof account.username === 'string' && account.username
|
|
3083
|
+
? `@${account.username.replace(/^@/, '')}`
|
|
3084
|
+
: typeof account.display_name === 'string' && account.display_name ? account.display_name : null;
|
|
3085
|
+
return name ? `${platform} ${name}` : platform;
|
|
3086
|
+
}
|
|
3087
|
+
/** A post that is still being sent or published, or a scheduled post that is due now, is not settled yet. */
|
|
3088
|
+
function socialPostIsSettled(post, nowMs = Date.now()) {
|
|
3089
|
+
const status = String(post.status);
|
|
3090
|
+
if (SOCIAL_SETTLED_STATUSES.has(status))
|
|
3091
|
+
return true;
|
|
3092
|
+
if (status === 'scheduled') {
|
|
3093
|
+
const due = Date.parse(String(post.scheduled_for));
|
|
3094
|
+
return !Number.isFinite(due) || due > nowMs + 60_000;
|
|
3095
|
+
}
|
|
3096
|
+
return false;
|
|
3097
|
+
}
|
|
3098
|
+
export function describeSocialPost(post) {
|
|
3099
|
+
const targets = socialList(post.targets).map(socialAccountLabel).join(', ') || 'no accounts';
|
|
3100
|
+
const results = socialList(post.results);
|
|
3101
|
+
const status = String(post.status);
|
|
3102
|
+
const lastError = typeof post.last_error === 'string' && post.last_error ? post.last_error : null;
|
|
3103
|
+
let line;
|
|
3104
|
+
if (status === 'scheduled')
|
|
3105
|
+
line = `Scheduled for ${post.scheduled_for} to ${targets}. ${post.estimated_credits} credits when it posts.`;
|
|
3106
|
+
else if (status === 'scheduling')
|
|
3107
|
+
line = `Sending to the social platforms (${targets}).${lastError ? ` ${lastError}` : ''}`;
|
|
3108
|
+
else if (status === 'publishing')
|
|
3109
|
+
line = `Publishing to ${targets}.`;
|
|
3110
|
+
else if (status === 'published') {
|
|
3111
|
+
const urls = results.map((result) => result.url).filter((url) => typeof url === 'string' && url.length > 0);
|
|
3112
|
+
line = `Published to ${targets}. ${post.credits_charged} credits charged.${urls.length ? ` Live: ${urls.join(', ')}` : ''}`;
|
|
3113
|
+
}
|
|
3114
|
+
else if (status === 'partial') {
|
|
3115
|
+
const failed = results.filter((result) => result.status === 'failed').map((result) => `${SOCIAL_PLATFORM_LABELS[String(result.platform)] ?? result.platform}: ${result.error ?? 'failed'}`);
|
|
3116
|
+
line = `Published to some accounts (${post.credits_charged} credits charged). Failed: ${failed.join('; ') || lastError || 'see data.post.results'}.`;
|
|
3117
|
+
}
|
|
3118
|
+
else if (status === 'failed')
|
|
3119
|
+
line = `Failed: ${lastError ?? 'see data.post.results'}. Nothing was charged.`;
|
|
3120
|
+
else if (status === 'cancelled')
|
|
3121
|
+
line = 'Cancelled. Nothing was charged.';
|
|
3122
|
+
else
|
|
3123
|
+
line = `Status ${status}.`;
|
|
3124
|
+
return `${line} Post id: ${post.id}.`;
|
|
3125
|
+
}
|
|
3126
|
+
function socialPostResult(projectId, post, data) {
|
|
3127
|
+
const status = String(post.status);
|
|
3128
|
+
const retry = `coauthor social retry ${projectId} ${post.id} --yes --wait`;
|
|
3129
|
+
if (status === 'failed') {
|
|
3130
|
+
return { ok: false, status: 'social_post_failed', code: 'social_post_failed', exitCode: 1, message: `${describeSocialPost(post)}\nAfter fixing the cause, retry with: ${retry}`, data };
|
|
3131
|
+
}
|
|
3132
|
+
if (status === 'partial')
|
|
3133
|
+
return { ok: true, status: 'partial', message: `${describeSocialPost(post)}\nRetry the failed accounts with: ${retry}`, data };
|
|
3134
|
+
return { ok: true, message: describeSocialPost(post), data };
|
|
3135
|
+
}
|
|
3136
|
+
async function waitForSocialPost(client, projectId, first) {
|
|
3137
|
+
const path = `projects/${encodeURIComponent(projectId)}/social/posts/${encodeURIComponent(String(first.id))}`;
|
|
3138
|
+
const deadline = Date.now() + waitTimeoutMs(9 * 60_000);
|
|
3139
|
+
let latest = first;
|
|
3140
|
+
while (!socialPostIsSettled(latest)) {
|
|
3141
|
+
if (Date.now() >= deadline)
|
|
3142
|
+
return { post: latest, settled: false };
|
|
3143
|
+
await sleep(Math.max(0, Math.min(waitPollMs(), deadline - Date.now())));
|
|
3144
|
+
latest = socialRecord(getResponseValue(await client.request({ path }), 'post')) ?? latest;
|
|
3145
|
+
}
|
|
3146
|
+
return { post: latest, settled: true };
|
|
3147
|
+
}
|
|
3148
|
+
async function settleSocialPost(client, projectId, post, data, wait) {
|
|
3149
|
+
const resume = `coauthor social status ${projectId} ${post.id} --wait`;
|
|
3150
|
+
if (!wait) {
|
|
3151
|
+
const result = socialPostResult(projectId, post, data);
|
|
3152
|
+
return socialPostIsSettled(post) ? result : { ...result, message: `${result.message}\nFollow it with: ${resume}` };
|
|
3153
|
+
}
|
|
3154
|
+
const waited = await waitForSocialPost(client, projectId, post);
|
|
3155
|
+
const latestData = socialRecord(data) ? { ...data, post: waited.post } : { post: waited.post };
|
|
3156
|
+
if (!waited.settled) {
|
|
3157
|
+
return {
|
|
3158
|
+
ok: true,
|
|
3159
|
+
status: 'still_running',
|
|
3160
|
+
exitCode: 2,
|
|
3161
|
+
message: `${describeSocialPost(waited.post)}\nStill waiting for the social platforms. Keep waiting with: ${resume}`,
|
|
3162
|
+
resume_command: resume,
|
|
3163
|
+
data: latestData,
|
|
3164
|
+
};
|
|
3165
|
+
}
|
|
3166
|
+
return socialPostResult(projectId, waited.post, latestData);
|
|
3167
|
+
}
|
|
3168
|
+
/** Handles a recorded post or retry: replays, failures recorded under the key, and work still in progress. */
|
|
3169
|
+
async function socialOperationResult(client, projectId, data, idempotencyKey, wait) {
|
|
3170
|
+
const operation = socialRecord(getResponseValue(data, 'operation'));
|
|
3171
|
+
const replayed = getResponseValue(data, 'replayed') === true;
|
|
3172
|
+
const keyLine = `Operation key: ${idempotencyKey} (coauthor operation status ${idempotencyKey} --json).`;
|
|
3173
|
+
if (operation?.status === 'failed') {
|
|
3174
|
+
return {
|
|
3175
|
+
ok: false,
|
|
3176
|
+
status: 'operation_failed',
|
|
3177
|
+
code: 'operation_failed',
|
|
3178
|
+
exitCode: 1,
|
|
3179
|
+
message: `The request recorded under this key failed: ${operation.error_message ?? 'unknown error'}. Fix the cause, then run the command again without --idempotency-key.\n${keyLine}`,
|
|
3180
|
+
idempotency_key: idempotencyKey,
|
|
3181
|
+
data,
|
|
3182
|
+
};
|
|
3183
|
+
}
|
|
3184
|
+
const post = socialRecord(getResponseValue(data, 'post'));
|
|
3185
|
+
if (!post) {
|
|
3186
|
+
const resume = `coauthor operation status ${idempotencyKey} --json`;
|
|
3187
|
+
return { ok: true, status: 'still_running', exitCode: 2, message: `The request with this key is still being processed. Check it with: ${resume}`, resume_command: resume, idempotency_key: idempotencyKey, data };
|
|
3188
|
+
}
|
|
3189
|
+
const linkSaved = socialRecord(operation?.result ?? null)?.link_saved;
|
|
3190
|
+
const lead = [
|
|
3191
|
+
replayed ? 'Replayed the recorded request (nothing was sent twice).' : null,
|
|
3192
|
+
typeof linkSaved === 'string' ? `Saved ${linkSaved} as the Destination URL.` : null,
|
|
3193
|
+
].filter(Boolean).join(' ');
|
|
3194
|
+
const result = await settleSocialPost(client, projectId, post, data, wait);
|
|
3195
|
+
return { ...result, message: [lead, result.message, keyLine].filter(Boolean).join('\n'), idempotency_key: idempotencyKey };
|
|
3196
|
+
}
|
|
3197
|
+
function socialAccountsMessage(data) {
|
|
3198
|
+
const accounts = socialList(getResponseValue(data, 'accounts'));
|
|
3199
|
+
const connectUrl = getResponseString(data, 'connect_url') ?? 'the CoAuthor web app';
|
|
3200
|
+
if (accounts.length === 0)
|
|
3201
|
+
return `No social accounts are connected. The user connects them in CoAuthor under Settings → Publishing: ${connectUrl}`;
|
|
3202
|
+
const limit = getResponseValue(data, 'limit');
|
|
3203
|
+
const lines = accounts.map((account) => {
|
|
3204
|
+
const notes = [
|
|
3205
|
+
account.status === 'needs_reconnect' ? 'needs reconnecting in the web app' : null,
|
|
3206
|
+
account.cli_posting === false ? 'post from the web app' : null,
|
|
3207
|
+
].filter(Boolean);
|
|
3208
|
+
return `- ${socialAccountLabel(account)}: ${account.id}${notes.length ? ` (${notes.join('; ')})` : ''}`;
|
|
3209
|
+
});
|
|
3210
|
+
return [
|
|
3211
|
+
'Connected accounts:',
|
|
3212
|
+
...lines,
|
|
3213
|
+
`${getResponseValue(data, 'used')} of ${typeof limit === 'number' ? limit : 'unlimited'} connected. Connect or reconnect accounts in the web app: ${connectUrl}`,
|
|
3214
|
+
].join('\n');
|
|
3215
|
+
}
|
|
3216
|
+
function socialPreviewMessage(projectId, data) {
|
|
3217
|
+
const format = getResponseString(data, 'format') ?? '';
|
|
3218
|
+
const variant = getResponseString(data, 'variant');
|
|
3219
|
+
const lines = [`Preview of the ${format} post${variant ? ` (variant ${variant})` : ''}. The content is in data.content.`];
|
|
3220
|
+
if (getResponseValue(data, 'needs_post_link') === true) {
|
|
3221
|
+
const suggested = getResponseString(data, 'suggested_destination_url');
|
|
3222
|
+
lines.push(`The text still has {{POST_URL}}: pass --link <article url> to social post${suggested ? ` (the post's live address is ${suggested})` : ''}.`);
|
|
3223
|
+
}
|
|
3224
|
+
const accounts = socialList(getResponseValue(data, 'accounts'));
|
|
3225
|
+
lines.push(accounts.length
|
|
3226
|
+
? `Accounts it can go to: ${accounts.map((account) => `${socialAccountLabel(account)} ${account.id} (${account.credits} credits${account.cli_posting === false ? ', web app only' : ''}${account.status === 'needs_reconnect' ? ', needs reconnecting' : ''})`).join('; ')}.`
|
|
3227
|
+
: `No connected account can take this format. Connect one in the web app: ${getResponseString(data, 'connect_url') ?? 'Settings → Publishing'}`);
|
|
3228
|
+
const credits = socialRecord(getResponseValue(data, 'credits'));
|
|
3229
|
+
const selected = socialList(getResponseValue(data, 'selected_accounts'));
|
|
3230
|
+
if (selected.length) {
|
|
3231
|
+
const issues = socialList(getResponseValue(data, 'issues')).map((issue) => String(issue.message));
|
|
3232
|
+
lines.push(issues.length ? `Not ready: ${[...new Set(issues)].join(' ')}` : `Ready to post to ${selected.map(socialAccountLabel).join(', ')}.`);
|
|
3233
|
+
lines.push(`Costs ${credits?.estimated} credits when it posts${typeof credits?.remaining === 'number' ? ` (${credits.remaining} left)` : ''}.`);
|
|
3234
|
+
if (!issues.length) {
|
|
3235
|
+
const accountFlags = selected.map((account) => `--account ${account.id}`).join(' ');
|
|
3236
|
+
lines.push(`Post with the user's OK: coauthor social post ${projectId} --format ${format}${variant ? ` --variant ${variant}` : ''} ${accountFlags} --now --yes --wait (or --at <ISO time> instead of --now).`);
|
|
3237
|
+
}
|
|
3238
|
+
}
|
|
3239
|
+
else if (credits?.hint) {
|
|
3240
|
+
lines.push(String(credits.hint));
|
|
3241
|
+
}
|
|
3242
|
+
return lines.join('\n');
|
|
3243
|
+
}
|
|
3244
|
+
function socialListMessage(data) {
|
|
3245
|
+
const posts = socialList(getResponseValue(data, 'posts'));
|
|
3246
|
+
if (posts.length === 0)
|
|
3247
|
+
return 'No social posts in this project yet.';
|
|
3248
|
+
return posts.map((post) => `- ${post.source_format} ${post.status}: ${describeSocialPost(post)}`).join('\n');
|
|
3249
|
+
}
|
|
3250
|
+
async function runSocialCommand(action, input, client) {
|
|
3251
|
+
if (!action)
|
|
3252
|
+
return helpResult(['social']);
|
|
3253
|
+
if (action === 'accounts') {
|
|
3254
|
+
const data = await client.request({ path: 'social/accounts' });
|
|
3255
|
+
return { ok: true, message: socialAccountsMessage(data), data };
|
|
3256
|
+
}
|
|
3257
|
+
const projectId = requireProjectId(input);
|
|
3258
|
+
const base = `projects/${encodeURIComponent(projectId)}/social`;
|
|
3259
|
+
const wait = getBoolean(input.values, 'wait');
|
|
3260
|
+
if (action === 'preview') {
|
|
3261
|
+
const format = socialFormatOption(input, SOCIAL_PREVIEW_USAGE);
|
|
3262
|
+
const media = socialMediaOptions(input, format);
|
|
3263
|
+
if (getString(input.values, 'link') !== undefined) {
|
|
3264
|
+
throw new Error('--link belongs to coauthor social post (it saves the link as the Destination URL, then posts). preview shows the saved link; data.needs_post_link says whether one is still missing.');
|
|
3265
|
+
}
|
|
3266
|
+
const params = new URLSearchParams({ format });
|
|
3267
|
+
const variant = getString(input.values, 'variant')?.trim();
|
|
3268
|
+
if (variant)
|
|
3269
|
+
params.set('variant', variant);
|
|
3270
|
+
for (const account of getStringList(input.values, 'account'))
|
|
3271
|
+
params.append('account', account);
|
|
3272
|
+
if (typeof media.caption === 'string')
|
|
3273
|
+
params.set('caption', media.caption);
|
|
3274
|
+
if (typeof media.youtube_title === 'string')
|
|
3275
|
+
params.set('youtube_title', media.youtube_title);
|
|
3276
|
+
const data = await client.request({ path: `${base}/preview?${params.toString()}` });
|
|
3277
|
+
return { ok: true, message: socialPreviewMessage(projectId, data), data };
|
|
3278
|
+
}
|
|
3279
|
+
if (action === 'post') {
|
|
3280
|
+
const format = socialFormatOption(input, SOCIAL_POST_USAGE);
|
|
3281
|
+
const accounts = getStringList(input.values, 'account');
|
|
3282
|
+
if (accounts.length === 0)
|
|
3283
|
+
throw new Error(`--account is required: an account id, a platform (x, linkedin, ...) or an @username from coauthor social accounts. ${SOCIAL_POST_USAGE}`);
|
|
3284
|
+
const now = getBoolean(input.values, 'now');
|
|
3285
|
+
const at = getString(input.values, 'at');
|
|
3286
|
+
if (now === (at !== undefined))
|
|
3287
|
+
throw new Error('Pass --now to post now, or --at <ISO time> to schedule it (one of the two).');
|
|
3288
|
+
const variant = getString(input.values, 'variant')?.trim();
|
|
3289
|
+
if (!variant && SOCIAL_VARIANT_REQUIRED.includes(format)) {
|
|
3290
|
+
throw new Error(`--variant <id> picks which ${format} ${format === 'video' ? 'render' : 'variation'} to post. Find the ids with coauthor repurpose show ${projectId} --format ${format} --json (${format === 'video' ? 'renders[].variant_id of a finished render' : 'copy.variations[].id'}).`);
|
|
3291
|
+
}
|
|
3292
|
+
const link = getString(input.values, 'link')?.trim();
|
|
3293
|
+
if (link !== undefined) {
|
|
3294
|
+
if (!SOCIAL_LINK_FORMATS.includes(format))
|
|
3295
|
+
throw new Error('--link only applies to --format x-thread, x-post, linkedin or facebook.');
|
|
3296
|
+
if (!/^https?:\/\/\S+$/i.test(link))
|
|
3297
|
+
throw new Error('--link must be a full http or https address.');
|
|
3298
|
+
}
|
|
3299
|
+
const media = socialMediaOptions(input, format);
|
|
3300
|
+
const scheduledFor = at !== undefined ? socialTimeOption(at, '--at') : null;
|
|
3301
|
+
if (!getBoolean(input.values, 'yes')) {
|
|
3302
|
+
throw new Error(`social post publishes to ${accounts.join(', ')} ${now ? 'right away' : `at ${scheduledFor}`}. Show the user the preview (coauthor social preview ${projectId} --format ${format}${variant ? ` --variant ${variant}` : ''}) and get their OK, then add --yes.`);
|
|
3303
|
+
}
|
|
3304
|
+
const timezone = getString(input.values, 'timezone')?.trim() || localTimezone();
|
|
3305
|
+
const body = {
|
|
3306
|
+
format,
|
|
3307
|
+
accounts,
|
|
3308
|
+
...(variant ? { variant } : {}),
|
|
3309
|
+
...(now ? { publish_now: true } : { scheduled_for: scheduledFor }),
|
|
3310
|
+
...(timezone ? { timezone } : {}),
|
|
3311
|
+
...(link ? { link } : {}),
|
|
3312
|
+
...media,
|
|
3313
|
+
};
|
|
3314
|
+
const idempotencyKey = getString(input.values, 'idempotency-key')?.trim() || randomUUID();
|
|
3315
|
+
const data = await client.request({ method: 'POST', path: `${base}/posts`, body, idempotencyKey });
|
|
3316
|
+
return socialOperationResult(client, projectId, data, idempotencyKey, wait);
|
|
3317
|
+
}
|
|
3318
|
+
if (action === 'list') {
|
|
3319
|
+
const data = await client.request({ path: `${base}/posts` });
|
|
3320
|
+
return { ok: true, message: socialListMessage(data), data };
|
|
3321
|
+
}
|
|
3322
|
+
const postId = input.positionals[1];
|
|
3323
|
+
if (!postId || !['status', 'reschedule', 'cancel', 'retry'].includes(action)) {
|
|
3324
|
+
if (['status', 'reschedule', 'cancel', 'retry'].includes(action))
|
|
3325
|
+
throw new Error(`Usage: coauthor social ${action} <project-id> <post-id> (post ids are in coauthor social list ${projectId} --json)`);
|
|
3326
|
+
throw new Error(`Unknown command: social ${action}. Run \`coauthor social --help\`.`);
|
|
3327
|
+
}
|
|
3328
|
+
const postPath = `${base}/posts/${encodeURIComponent(postId)}`;
|
|
3329
|
+
if (action === 'status') {
|
|
3330
|
+
const data = await client.request({ path: postPath });
|
|
3331
|
+
const post = socialRecord(getResponseValue(data, 'post'));
|
|
3332
|
+
if (!post)
|
|
3333
|
+
return { ok: true, data };
|
|
3334
|
+
return settleSocialPost(client, projectId, post, data, wait);
|
|
3335
|
+
}
|
|
3336
|
+
if (action === 'reschedule') {
|
|
3337
|
+
const at = getString(input.values, 'at');
|
|
3338
|
+
if (!at)
|
|
3339
|
+
throw new Error(`Usage: coauthor social reschedule ${projectId} ${postId} --at <ISO time> [--timezone <zone>]`);
|
|
3340
|
+
const timezone = getString(input.values, 'timezone')?.trim() || localTimezone();
|
|
3341
|
+
const data = await client.request({ method: 'PATCH', path: postPath, body: { scheduled_for: socialTimeOption(at, '--at'), ...(timezone ? { timezone } : {}) } });
|
|
3342
|
+
const post = socialRecord(getResponseValue(data, 'post'));
|
|
3343
|
+
return { ok: true, message: post ? describeSocialPost(post) : undefined, data };
|
|
3344
|
+
}
|
|
3345
|
+
if (action === 'cancel') {
|
|
3346
|
+
if (!getBoolean(input.values, 'yes'))
|
|
3347
|
+
throw new Error(`social cancel stops a post that has not gone out. Add --yes to cancel ${postId}.`);
|
|
3348
|
+
const data = await client.request({ method: 'POST', path: `${postPath}/cancel` });
|
|
3349
|
+
const post = socialRecord(getResponseValue(data, 'post'));
|
|
3350
|
+
const already = getResponseValue(data, 'already_cancelled') === true;
|
|
3351
|
+
return { ok: true, message: post ? `${already ? 'Already cancelled. ' : ''}${describeSocialPost(post)}` : undefined, data };
|
|
3352
|
+
}
|
|
3353
|
+
// retry
|
|
3354
|
+
if (!getBoolean(input.values, 'yes'))
|
|
3355
|
+
throw new Error(`social retry publishes ${postId} again to the accounts that failed. Get the user's OK, then add --yes.`);
|
|
3356
|
+
const idempotencyKey = getString(input.values, 'idempotency-key')?.trim() || randomUUID();
|
|
3357
|
+
const data = await client.request({ method: 'POST', path: `${postPath}/retry`, idempotencyKey });
|
|
3358
|
+
return socialOperationResult(client, projectId, data, idempotencyKey, wait);
|
|
3359
|
+
}
|
|
3021
3360
|
const REPURPOSE_FORMATS = ['x-thread', 'x-post', 'linkedin', 'facebook', 'email', 'slideshow', 'video'];
|
|
3022
3361
|
const REPURPOSE_GENERATABLE = ['x-thread', 'x-post', 'linkedin', 'facebook', 'email'];
|
|
3023
3362
|
const SLIDESHOW_FORMAT_ALIASES = ['slideshow', 'carousel'];
|
|
@@ -3766,6 +4105,7 @@ export function helpResult(command = []) {
|
|
|
3766
4105
|
' image list|status|show|generate|edit|metadata|replace',
|
|
3767
4106
|
' thread list|show|create|generate|save',
|
|
3768
4107
|
' slideshow show|save',
|
|
4108
|
+
' social accounts|preview|post|list|status|reschedule|cancel|retry (post to connected social accounts)',
|
|
3769
4109
|
' publish thread (supports --idempotency-key)',
|
|
3770
4110
|
' export list|wordpress (supports --idempotency-key)',
|
|
3771
4111
|
' operation list|show|status (publish, export and image generate/edit)',
|
|
@@ -3938,6 +4278,27 @@ function commandHelp(command) {
|
|
|
3938
4278
|
'download --format slideshow renders 1080x1350 PNGs on the server into <out>/slideshow/<cta>/slide-NN.png (--variant picks one CTA); --format all includes them once every image is ready.',
|
|
3939
4279
|
'Publish an X thread with coauthor publish thread.',
|
|
3940
4280
|
].join('\n'),
|
|
4281
|
+
social: [
|
|
4282
|
+
'Usage: coauthor social accounts [--json]',
|
|
4283
|
+
' coauthor social preview <project-id> --format <format> [--variant <id>] [--account <id|platform|@username>]... [--caption "..."] [--youtube-title "..."] [--json]',
|
|
4284
|
+
' coauthor social post <project-id> --format <format> [--variant <id>] --account <id|platform|@username>... (--now | --at <ISO time>) [--link <url>] [--caption "..."] [--youtube-title "..."] [--timezone <zone>] --yes [--idempotency-key <key>] [--wait] [--json]',
|
|
4285
|
+
' coauthor social list <project-id> [--json]',
|
|
4286
|
+
' coauthor social status <project-id> <post-id> [--wait] [--json]',
|
|
4287
|
+
' coauthor social reschedule <project-id> <post-id> --at <ISO time> [--timezone <zone>] [--json]',
|
|
4288
|
+
' coauthor social cancel <project-id> <post-id> --yes [--json]',
|
|
4289
|
+
' coauthor social retry <project-id> <post-id> --yes [--idempotency-key <key>] [--wait] [--json]',
|
|
4290
|
+
'',
|
|
4291
|
+
'Posts a repurposed format (x-thread, x-post, linkedin, facebook, slideshow, video) to the user\'s connected social accounts, now or at a set time.',
|
|
4292
|
+
'accounts lists the connected accounts and the plan\'s limit. Connecting or reconnecting an account needs a browser sign-in with the platform, so the user does it in the web app (Settings → Publishing). TikTok posts are made in the web app too (tiktok_web_only).',
|
|
4293
|
+
'--account takes an account id, a platform (x, linkedin, facebook, instagram, youtube) when one account of it is connected, or an @username. Repeat it, or comma-separate, to post to several (up to 10).',
|
|
4294
|
+
'--variant picks the variation (x-post, linkedin, facebook: copy.variations[].id from repurpose show), the slideshow ending (default: the first) or the finished video render (renders[].variant_id).',
|
|
4295
|
+
'preview shows exactly what would be posted, whether the text still needs the article link (needs_post_link), and the credit cost per account. With --account it runs the same checks as post.',
|
|
4296
|
+
'post needs --yes and a login with publish permission (coauthor auth login --with-publish). --at takes an ISO time with an offset (2026-11-20T09:00:00-05:00), at least a minute ahead and up to a year. --link saves the article link as the format\'s Destination URL (filling {{POST_URL}}) before posting. --caption and --youtube-title apply to slideshow and video.',
|
|
4297
|
+
'Credits: 10 per account when the post goes out; X costs 20 per post plus 10 per reply in a thread. Cancelled and failed posts cost nothing.',
|
|
4298
|
+
'--wait follows the post: a --now post until it is published (or fails), a scheduled post until the platforms confirm the schedule. It stops after 9 minutes with still_running (exit 2) and a status command to resume. A failed post exits 1.',
|
|
4299
|
+
'post and retry print an operation key; rerun with --idempotency-key <key> to replay instead of posting twice. reschedule moves a scheduled post; cancel stops one that has not gone out (nothing is charged); retry publishes again to the accounts that failed.',
|
|
4300
|
+
'Errors: social_posting_unavailable, social_account_not_connected, social_account_needs_reconnect, account_ambiguous, tiktok_web_only, post_link_required, source_not_ready, invalid_schedule, insufficient_credits, social_post_rejected, social_unavailable, not_editable, not_cancellable, not_retryable.',
|
|
4301
|
+
].join('\n'),
|
|
3941
4302
|
brief: [
|
|
3942
4303
|
'Usage: coauthor brief review <project-id> [--json]',
|
|
3943
4304
|
' coauthor brief answer <project-id> --data @answers.json [--force] [--json]',
|
package/dist/parser.d.ts
CHANGED
|
@@ -30,6 +30,8 @@ export declare function optionTakesValue(flag: string): boolean;
|
|
|
30
30
|
export declare function parseCliArgs(argv: string[]): ParsedCommand;
|
|
31
31
|
export declare function getString(values: ParsedCommand['values'], name: string): string | undefined;
|
|
32
32
|
export declare function requireString(values: ParsedCommand['values'], name: string): string;
|
|
33
|
+
/** Every value of a repeatable option (`--account a --account b`), comma-separated lists split. */
|
|
34
|
+
export declare function getStringList(values: ParsedCommand['values'], name: string): string[];
|
|
33
35
|
export declare function getBoolean(values: ParsedCommand['values'], name: string): boolean;
|
|
34
36
|
export declare function readJsonOptionText(values: ParsedCommand['values'], name?: string): string | undefined;
|
|
35
37
|
export declare function parseJsonOption(values: ParsedCommand['values'], name?: string): Record<string, JsonValue>;
|
package/dist/parser.js
CHANGED
|
@@ -98,6 +98,14 @@ const OPTIONS = {
|
|
|
98
98
|
file: { type: 'string' },
|
|
99
99
|
url: { type: 'string' },
|
|
100
100
|
artifact: { type: 'string' },
|
|
101
|
+
// social: --account can repeat (or take a comma-separated list)
|
|
102
|
+
account: { type: 'string', multiple: true },
|
|
103
|
+
at: { type: 'string' },
|
|
104
|
+
now: { type: 'boolean', default: false },
|
|
105
|
+
link: { type: 'string' },
|
|
106
|
+
caption: { type: 'string' },
|
|
107
|
+
'youtube-title': { type: 'string' },
|
|
108
|
+
timezone: { type: 'string' },
|
|
101
109
|
};
|
|
102
110
|
/** True when `--name` (or its short alias) consumes the next argv entry as its value. */
|
|
103
111
|
export function optionTakesValue(flag) {
|
|
@@ -142,6 +150,12 @@ export function requireString(values, name) {
|
|
|
142
150
|
throw new Error(`Missing required option --${name}`);
|
|
143
151
|
return value;
|
|
144
152
|
}
|
|
153
|
+
/** Every value of a repeatable option (`--account a --account b`), comma-separated lists split. */
|
|
154
|
+
export function getStringList(values, name) {
|
|
155
|
+
const value = values[name];
|
|
156
|
+
const list = Array.isArray(value) ? value : typeof value === 'string' ? [value] : [];
|
|
157
|
+
return list.flatMap((entry) => entry.split(',')).map((entry) => entry.trim()).filter(Boolean);
|
|
158
|
+
}
|
|
145
159
|
export function getBoolean(values, name) {
|
|
146
160
|
return values[name] === true;
|
|
147
161
|
}
|
|
@@ -210,6 +224,8 @@ function commandLength(positionals) {
|
|
|
210
224
|
return second && ['list', 'show', 'generate', 'save', 'download', 'status', 'render'].includes(second) ? 2 : 1;
|
|
211
225
|
if (first === 'draft' && second === 'revision')
|
|
212
226
|
return positionals[2] && ['show', 'apply', 'discard'].includes(positionals[2]) ? 3 : 2;
|
|
227
|
+
if (first === 'social')
|
|
228
|
+
return second && ['accounts', 'preview', 'post', 'list', 'status', 'reschedule', 'cancel', 'retry'].includes(second) ? 2 : 1;
|
|
213
229
|
if (first === 'credits')
|
|
214
230
|
return 1;
|
|
215
231
|
if (first === 'post-details')
|
package/package.json
CHANGED
package/skills/coauthor/SKILL.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: coauthor
|
|
3
|
-
description: Research, outline, draft, illustrate, revise, and export long-form articles with CoAuthor (ClickMinded's AI writing app) through the `coauthor` CLI. Use when the user wants to write, draft, research, or edit a blog post, article, guide, or newsletter piece with CoAuthor; review a CoAuthor brief, outline, or research plan; revise or polish a CoAuthor draft; generate article images or an X thread; make an SEO content plan (which posts to write to rank on Google) and write its ideas; check CoAuthor credits; get a share link; or send a draft to WordPress. Not for git "Co-authored-by" commit trailers.
|
|
3
|
+
description: Research, outline, draft, illustrate, revise, and export long-form articles with CoAuthor (ClickMinded's AI writing app) through the `coauthor` CLI. Use when the user wants to write, draft, research, or edit a blog post, article, guide, or newsletter piece with CoAuthor; review a CoAuthor brief, outline, or research plan; revise or polish a CoAuthor draft; generate article images or an X thread; post or schedule the repurposed social posts to the user's connected accounts; make an SEO content plan (which posts to write to rank on Google) and write its ideas; check CoAuthor credits; get a share link; or send a draft to WordPress. Not for git "Co-authored-by" commit trailers.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# CoAuthor
|
|
@@ -19,7 +19,7 @@ You drive it with the `coauthor` CLI. CoAuthor does the writing. **You are the u
|
|
|
19
19
|
|
|
20
20
|
- Always pass `--json` and read fields from the output. Failures arrive on stderr as JSON with `code`, `http_status`, and `details`.
|
|
21
21
|
- Keep each foreground command under your shell's time limit (Claude Code: 10 minutes). Prefix waiting commands with `COAUTHOR_CLI_WAIT_TIMEOUT_MS=540000`. If a command returns `timed_out` or `still_running`, run the resume or show command it gives you. Never start the same step twice.
|
|
22
|
-
- Get the user's explicit yes before anything public or live: `share` (creates a public link), `export … --yes`, `publish … --yes`. Also before building or editing interactives (`widgets build`, `build-all`, `edit`, `delete`): they spend credits, and edit and delete change published posts.
|
|
22
|
+
- Get the user's explicit yes before anything public or live: `share` (creates a public link), `export … --yes`, `publish … --yes`, `social post … --yes` and `social retry … --yes`. Also before building or editing interactives (`widgets build`, `build-all`, `edit`, `delete`): they spend credits, and edit and delete change published posts.
|
|
23
23
|
- Every blocked or paused status says what to do next. Follow it instead of retrying (see "When something stops").
|
|
24
24
|
- Once a draft exists, do not save, generate, or approve the brief, outline, or research plan unless the user wants to restart the piece: that marks the draft stale. Edit the draft instead.
|
|
25
25
|
- Never send markdown to `draft save`.
|
|
@@ -39,7 +39,7 @@ Typical timing: brief and outline under a minute; research and draft 3–10 minu
|
|
|
39
39
|
6. **Quality pass.** CoAuthor already checks each new draft against the brief and for consistency, and fixes what it can: must-include items (and every figure they give, plus sentences claiming the post has no data the brief supplies), non-negotiables, tables vs their sections, "see the table" references, unsourced "most readers" claims, FAQ answers that defer, links (cut-short or malformed URLs, dead pages, citations that open a page about something else), and sentences that cite a research source: figures that are not in that source, a report edition that differs from the one cited ("the 2027 report" linked to the 2026 page), and up to 15 rules or figures checked against the source text (contradicted ones are corrected from the source when it can; the rest are reported). Whatever is still open is in `quality_check.unresolved` of `coauthor draft status <id> --json` (and `post-details show`), and the completion message says how many. Fix those first. Then `coauthor draft get <id> --format markdown --json` and read `data.markdown` in full. Check it against the brief's must-include, must-avoid, and non-negotiables. Look for: notes about the research process ("the retrieved sources do not…"), invented "checked <date>" lines, numbered lists that restart at 1, garbled `*`, `_`, or code spans, literal `[ ]` in checklists, the same caveat repeated across sections, claims without a source or cited to a page that doesn't support them, contradictions, and a messy Sources list (generic titles like "Google", duplicate entries). Fix them in step 8.
|
|
40
40
|
7. **Images.** `coauthor image generate <id> --all --wait --json` generates every planned image and waits for them (one image: `coauthor image generate <id> --placeholder-id <placeholder id> --json`, using the `id` UUID from `image list`). CoAuthor decides how many images a draft gets, sometimes only the featured image; the CLI can't add more, so tell the user if they expected several. Open each image and check it does not state numbers or claims the article does not make, and that its alt text matches what is visible (CoAuthor writes alt text from the finished image; fix it with `image metadata` only when it is wrong). See `references/images-and-social.md`. If the draft has interactive placeholders (beta), show them to the user and get a yes before building: `references/interactive-widgets.md`.
|
|
41
41
|
8. **Edits.** For prose changes: `coauthor draft revise <id> --instruction "..." --wait --json` (be specific: name the section and give a number, such as "cut the intro to under 60 words"), review each group's `before_markdown` and `after_markdown`, then `coauthor draft revision apply <id> <revision-id> --json` (optionally `--accept` or `--reject` with ids copied from `data.groups[].id`) or `coauthor draft revision discard <id> <revision-id> --json`. For exact text you already have, edit the document JSON and `draft save`. See `references/editing-drafts.md`.
|
|
42
|
-
9. **Deliver.** Give the user the final markdown (or `--format html`), the decision log (`coauthor log show <id> --json`: what you approved, what you asked CoAuthor to change, what you assumed), and the credits used (`coauthor credits <id> --json`). The user also sees the log in the project's workspace in the web app. With their yes: share link or WordPress export (`references/publishing-and-export.md`). For social posts and an email newsletter, `coauthor repurpose generate <id> --format all --json`, review `data.copy`, and `coauthor repurpose download <id> --out <dir>` (`references/repurposing.md`).
|
|
42
|
+
9. **Deliver.** Give the user the final markdown (or `--format html`), the decision log (`coauthor log show <id> --json`: what you approved, what you asked CoAuthor to change, what you assumed), and the credits used (`coauthor credits <id> --json`). The user also sees the log in the project's workspace in the web app. With their yes: share link or WordPress export (`references/publishing-and-export.md`). For social posts and an email newsletter, `coauthor repurpose generate <id> --format all --json`, review `data.copy`, and `coauthor repurpose download <id> --out <dir>` (`references/repurposing.md`). To post them to the user's connected accounts, now or scheduled: `coauthor social preview`, then with their yes `coauthor social post` (`references/images-and-social.md`, Post to social accounts).
|
|
43
43
|
|
|
44
44
|
## When something stops
|
|
45
45
|
|
|
@@ -81,4 +81,4 @@ Details, item fields, and what each kind means: `references/seo-content-plan.md`
|
|
|
81
81
|
|
|
82
82
|
## Not in the CLI yet
|
|
83
83
|
|
|
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,
|
|
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, turning the monthly SEO report email off (Settings, then Email), connecting or reconnecting social accounts (Settings, then Publishing: it needs a sign-in with each platform), and posting to TikTok (from the project's preview in the web app). Point the user to the CoAuthor web app at https://tools.clickminded.com/coauthor for these instead of improvising.
|
|
@@ -9,6 +9,7 @@ Rough costs, to set expectations before starting:
|
|
|
9
9
|
- A complete article (brief through draft) is typically about 300 credits.
|
|
10
10
|
- Images and extra rework rounds (regenerating, many revisions) drive cost more than word count does.
|
|
11
11
|
- Adding the repurposed formats in the web app (social posts, newsletter, slideshow) adds roughly 100–150 more.
|
|
12
|
+
- Posting to social accounts (`coauthor social post`): 10 credits per account when the post goes out; X costs 20 per post plus 10 per reply. Failed and cancelled posts cost nothing.
|
|
12
13
|
- An SEO content plan (`coauthor seo-plan generate`): the first plan an account makes is free. Later plans are about 420 credits (most plans 300–500) and need 500 remaining to start. See `references/seo-content-plan.md`.
|
|
13
14
|
|
|
14
15
|
Tell the user the expected cost before large or repeated work, and report credits used at the end.
|
|
@@ -27,6 +27,28 @@ Images cost credits each time they are generated or edited, so check the brief a
|
|
|
27
27
|
3. To edit, save the complete post list: `coauthor thread save <id> --data @thread.json --json` with `{"posts":[...]}`. Include `"destination_url"` to change the link, and `"selected_social_account_id"` to choose the X account (it is kept when you leave it out).
|
|
28
28
|
4. Publishing posts to X immediately and publicly. It needs the user's explicit yes and a token with publish permission (`coauthor auth login --with-publish`): `coauthor publish thread <id> --yes --json`.
|
|
29
29
|
|
|
30
|
+
## Post to social accounts
|
|
31
|
+
|
|
32
|
+
CoAuthor posts the repurposed formats (`x-thread`, `x-post`, `linkedin`, `facebook`, `slideshow`, `video`; see `references/repurposing.md`) to the user's connected social accounts, now or at a set time. Email newsletters are not posted.
|
|
33
|
+
|
|
34
|
+
1. **Accounts.** `coauthor social accounts --json` lists the connected accounts (`data.accounts`: `id`, `platform`, `label`, `username`, `status`, `cli_posting`), how many the plan allows (`used`, `limit`), and which formats go to each platform. X is `twitter` in the data. Connecting or reconnecting an account needs a sign-in with the platform in a browser, so the user does it in the web app (Settings → Publishing, `data.connect_url`); you can't connect one from the CLI. A `status` of `needs_reconnect` means the user reconnects it there before you post to it.
|
|
35
|
+
2. **Pick the variation.** X posts, LinkedIn and Facebook have several variations: take the `id` from `coauthor repurpose show <id> --format <format> --json` (`data.copy.variations[].id`) and pass it as `--variant`. A slideshow posts its first ending unless `--variant <cta id>` picks another; a video needs `--variant` set to a finished render's `variant_id`. An X thread has no variations.
|
|
36
|
+
3. **Preview.** `coauthor social preview <id> --format linkedin --variant <variation id> --account linkedin --json` shows exactly what would be posted (`data.content`), the accounts it can go to with the credits for each (`data.accounts`), and, with `--account`, the same checks the post runs (`data.ready`, `data.issues`) and the cost (`data.credits.estimated`, `data.credits.remaining`). `--account` takes an account id, a platform (`x`, `linkedin`, `facebook`, `instagram`, `youtube`) when only one account of it is connected, or an `@username`; repeat it to post to several accounts at once. Slideshows and videos take `--caption "..."` (the default caption is the first LinkedIn variation, else Facebook, else the title) and videos to YouTube `--youtube-title "..."`.
|
|
37
|
+
4. **The article link.** When the text still holds `{{POST_URL}}`, `data.needs_post_link` is true and the post is refused with `post_link_required`. `data.suggested_destination_url` is the post's live address from post details, when known. Pass the link to the post with `--link <url>`: it is saved as that format's Destination URL (the same field `repurpose save` sets with `destination_url`), then the post goes out with it. Confirm the link with the user if it isn't the live address.
|
|
38
|
+
5. **Post, with the user's yes.** Show the user the preview text, the accounts, the time and the cost, and get an explicit OK. Then: `coauthor social post <id> --format linkedin --variant <variation id> --account linkedin --at 2026-11-20T09:00:00-05:00 --yes --json`, or `--now` instead of `--at` to post right away. `--at` is an ISO time with an offset, at least a minute ahead and up to a year; `--timezone <zone>` records the user's time zone (the CLI sends this machine's by default). It needs a login with publish permission (`coauthor auth login --with-publish`).
|
|
39
|
+
- `--wait` follows the post: a `--now` post until it is published or fails, a scheduled post until the platforms confirm the schedule. After 9 minutes it returns `still_running` (exit code 2); keep following with `coauthor social status <id> <post-id> --wait --json`.
|
|
40
|
+
- Each post prints an operation key (`idempotency_key`). After a timeout or network error, don't post again: check `coauthor social list <id> --json` or `coauthor operation status <key> --json`, or rerun with `--idempotency-key <key>`, which replays the recorded request instead of posting twice.
|
|
41
|
+
6. **Follow up.** `coauthor social list <id> --json` shows the project's posts (`data.posts`: `id`, `status`, `scheduled_for`, `targets`, `results` with each account's live `url` or `error`, `credits_charged`). Statuses: `scheduling` (being sent to the platforms), `scheduled`, `publishing`, `published`, `partial` (some accounts failed), `failed`, `cancelled`. `coauthor social status <id> <post-id> --json` reads one.
|
|
42
|
+
- Move a scheduled post: `coauthor social reschedule <id> <post-id> --at <ISO time> --json` (only `scheduled` posts, `not_editable` otherwise).
|
|
43
|
+
- Cancel one that hasn't gone out: `coauthor social cancel <id> <post-id> --yes --json`. Nothing is charged.
|
|
44
|
+
- Publish again to the accounts that failed (`failed` or `partial`), after fixing the cause and with the user's OK: `coauthor social retry <id> <post-id> --yes --wait --json`.
|
|
45
|
+
|
|
46
|
+
Credits are charged per account when the post goes out: 10 per account, and X costs 20 per post plus 10 for each reply in a thread or X post. Failed and cancelled posts cost nothing.
|
|
47
|
+
|
|
48
|
+
**TikTok** posts are made in the web app. TikTok requires the user to see its posting screen for every post (who can see it, comments, duets and stitches, the brand-content disclosure, and its consent line), which the CLI cannot show, so the CLI refuses TikTok accounts with `tiktok_web_only` and points to the project in the web app.
|
|
49
|
+
|
|
50
|
+
`coauthor publish thread` (above) posts a thread through the older X connection listed in `coauthor integrations list`; accounts connected under Settings → Publishing go through `social post`.
|
|
51
|
+
|
|
30
52
|
## Other formats
|
|
31
53
|
|
|
32
54
|
X posts, LinkedIn, Facebook, and email newsletter versions: see `references/repurposing.md`. Carousel slideshows and short vertical videos: same file, under Slideshow and Video.
|
|
@@ -64,6 +64,10 @@ Export creates a **draft post** in the user's WordPress site (it is not publishe
|
|
|
64
64
|
|
|
65
65
|
See `references/images-and-social.md`. Publishing a thread posts immediately and needs the user's yes.
|
|
66
66
|
|
|
67
|
+
## Social accounts
|
|
68
|
+
|
|
69
|
+
To post or schedule the repurposed posts, slideshows and videos to the user's connected accounts: `coauthor social preview`, then `coauthor social post … --yes` (`references/images-and-social.md`, Post to social accounts).
|
|
70
|
+
|
|
67
71
|
## If a live action's result is unclear
|
|
68
72
|
|
|
69
|
-
After a network error or an unclear result on an export or
|
|
73
|
+
After a network error or an unclear result on an export, publish or social post, do not run it again straight away. Every export and publish prints its `idempotency_key`; check `coauthor operation status <idempotency_key> --json` (or `coauthor operation list --json`) first. To retry safely, pass the same key back with `--idempotency-key <key>`, so CoAuthor won't run it twice.
|
|
@@ -77,4 +77,4 @@ To fix one panel before rendering: `coauthor image list <id> --artifact video --
|
|
|
77
77
|
|
|
78
78
|
Hand the user the folder, or paste from `data.copy`.
|
|
79
79
|
|
|
80
|
-
|
|
80
|
+
The X thread, X posts, LinkedIn, Facebook, slideshows and videos can be posted or scheduled to the user's connected social accounts with `coauthor social post` after the user's explicit OK (`references/images-and-social.md`, Post to social accounts). Email newsletters are copy-and-paste.
|
|
@@ -90,7 +90,7 @@ Some plans tag ideas whose searches are ones where Google AI answers cite a comp
|
|
|
90
90
|
- `ai_search_volume`: DataForSEO's estimate of monthly AI searches behind the idea's matching searches.
|
|
91
91
|
- `questions`: on United States / English plans, up to 3 ChatGPT questions about the idea whose answers cite a competitor (`question`, `competitor`). Empty elsewhere.
|
|
92
92
|
|
|
93
|
-
An AI gap idea went through the same checks as every other idea; the tag explains why it matters, it does not mean the idea is more likely to rank. The human output of `show` prefixes it with `[AI gap]` and names the competitors. When you write one, `seo-plan write` puts its questions into the post's brief
|
|
93
|
+
An AI gap idea went through the same checks as every other idea; the tag explains why it matters, it does not mean the idea is more likely to rank. The human output of `show` prefixes it with `[AI gap]` and names the competitors. When you write one, `seo-plan write` puts its questions into the post's brief. The outline checks that its sections cover what those answers need, without adding a FAQ or question headings.
|
|
94
94
|
|
|
95
95
|
`ai_search_update_available` (top level of `show --json`) is `true` for a full plan made before AI search ideas went live on 2026-11-18. That plan has no `ai_visibility` and no AI gap ideas. Running `coauthor seo-plan generate` updates it and adds them, using the user's credits (`estimate_credits`). Mention it once when it is `true`, and do not update the plan without the user's go-ahead. It turns `false` after an update, and it is always `false` for previews and stale plans.
|
|
96
96
|
|
|
@@ -87,8 +87,21 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
87
87
|
| `not_writable` | `seo-plan write` on an item that isn't a `post` idea (improve, page idea, left out, covered). | Only `post` items are written. Improve and page ideas are tasks on the user's site. |
|
|
88
88
|
| `plan_item_not_found` | `seo-plan write`, `dismiss` or `done` with an unknown item id (`done` also rejects left-out and not-checked items). | Take the `id` from `seo-plan show --json`. |
|
|
89
89
|
| `operation_in_progress` | A `seo-plan generate` with the same `--idempotency-key` is still being processed. | Wait a moment and check `coauthor seo-plan show`. |
|
|
90
|
+
| `social_posting_unavailable` | Posting to social accounts isn't switched on for this account yet. | Hand the user the copy from `repurpose show` to post themselves. |
|
|
91
|
+
| `social_account_not_connected` | An `--account` value matches no connected account (`details.accounts` lists them). | Use an `id` from `coauthor social accounts --json`. If the account isn't there, the user connects it in the web app (`details.connect_url`, Settings → Publishing). |
|
|
92
|
+
| `social_account_needs_reconnect` | The platform signed the account out. | The user reconnects it in the web app (`details.connect_url`), then post again. |
|
|
93
|
+
| `account_ambiguous` | A platform or username matches several connected accounts (`details.matches`). | Pass the account `id` instead. |
|
|
94
|
+
| `tiktok_web_only` | TikTok posts need TikTok's posting screen shown to the user, which only the web app shows. | Give the user `details.web_url` to post it from the project's preview in the web app. |
|
|
95
|
+
| `post_link_required` | The text still holds `{{POST_URL}}` and the format has no Destination URL. | Rerun `social post` with `--link <article url>` (`details.suggested_destination_url` is the live address when known; confirm it with the user if not). |
|
|
96
|
+
| `source_not_ready` | The format hasn't been generated, the variation id is wrong, the slideshow has no slides, or the video has no finished render. | Run `details.next_command` for the ids, or generate/render the format first (`references/repurposing.md`). |
|
|
97
|
+
| `invalid_schedule` | `--at` is in the past, less than a minute ahead, more than a year ahead, or both `--now` and `--at` were sent. | Pick a valid time, or post with `--now`. |
|
|
98
|
+
| `social_post_rejected` | A social platform refused the post (the message says why, for example text too long). Nothing was created or charged. | Fix the text with `repurpose save` (or the caption) and post again. |
|
|
99
|
+
| `social_unavailable` | The social platforms couldn't be reached. | Try again in a few minutes. Check `coauthor social list` before posting again. |
|
|
100
|
+
| `social_post_failed` | A post failed on the platforms (`details` or `data.post.results` give each account's error). Nothing was charged for those accounts. | Tell the user. After the cause is fixed (often a reconnect), `coauthor social retry <id> <post-id> --yes --wait`. |
|
|
101
|
+
| `not_editable`, `not_cancellable`, `not_retryable` | `social reschedule` on a post that isn't `scheduled`, `social cancel` on one that already went out, or `social retry` on one that didn't fail. | Check `coauthor social status <id> <post-id> --json`. |
|
|
102
|
+
| `operation_failed` | A `social post` or `social retry` rerun with an `--idempotency-key` whose recorded request failed. | Fix the cause (the message has it), then run the command again without the key. |
|
|
90
103
|
| `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
|
|
91
|
-
| `request_timeout`, `network_error` | No answer from CoAuthor in time, or the connection failed. | For reads, retry. For exports, publishes, and image generate/edit, check `coauthor operation status <idempotency_key>` before retrying. |
|
|
104
|
+
| `request_timeout`, `network_error` | No answer from CoAuthor in time, or the connection failed. | For reads, retry. For exports, publishes, social posts, and image generate/edit, check `coauthor operation status <idempotency_key>` before retrying. |
|
|
92
105
|
|
|
93
106
|
## Sign-in
|
|
94
107
|
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: Research, outline, draft, illustrate, revise, and export long-form articles with CoAuthor (ClickMinded's AI writing app) through the `coauthor` CLI. Use when the user wants to write, draft, research, or edit a blog post, article, guide, or newsletter piece with CoAuthor; review a CoAuthor brief, outline, or research plan; revise or polish a CoAuthor draft; generate article images or an X thread; make an SEO content plan (which posts to write to rank on Google) and write its ideas; check CoAuthor credits; get a share link; or send a draft to WordPress. Not for git "Co-authored-by" commit trailers.
|
|
2
|
+
description: Research, outline, draft, illustrate, revise, and export long-form articles with CoAuthor (ClickMinded's AI writing app) through the `coauthor` CLI. Use when the user wants to write, draft, research, or edit a blog post, article, guide, or newsletter piece with CoAuthor; review a CoAuthor brief, outline, or research plan; revise or polish a CoAuthor draft; generate article images or an X thread; post or schedule the repurposed social posts to the user's connected accounts; make an SEO content plan (which posts to write to rank on Google) and write its ideas; check CoAuthor credits; get a share link; or send a draft to WordPress. Not for git "Co-authored-by" commit trailers.
|
|
3
3
|
alwaysApply: false
|
|
4
4
|
---
|
|
5
5
|
|
|
@@ -21,7 +21,7 @@ You drive it with the `coauthor` CLI. CoAuthor does the writing. **You are the u
|
|
|
21
21
|
|
|
22
22
|
- Always pass `--json` and read fields from the output. Failures arrive on stderr as JSON with `code`, `http_status`, and `details`.
|
|
23
23
|
- Keep each foreground command under your shell's time limit (Claude Code: 10 minutes). Prefix waiting commands with `COAUTHOR_CLI_WAIT_TIMEOUT_MS=540000`. If a command returns `timed_out` or `still_running`, run the resume or show command it gives you. Never start the same step twice.
|
|
24
|
-
- Get the user's explicit yes before anything public or live: `share` (creates a public link), `export … --yes`, `publish … --yes`. Also before building or editing interactives (`widgets build`, `build-all`, `edit`, `delete`): they spend credits, and edit and delete change published posts.
|
|
24
|
+
- Get the user's explicit yes before anything public or live: `share` (creates a public link), `export … --yes`, `publish … --yes`, `social post … --yes` and `social retry … --yes`. Also before building or editing interactives (`widgets build`, `build-all`, `edit`, `delete`): they spend credits, and edit and delete change published posts.
|
|
25
25
|
- Every blocked or paused status says what to do next. Follow it instead of retrying (see "When something stops").
|
|
26
26
|
- Once a draft exists, do not save, generate, or approve the brief, outline, or research plan unless the user wants to restart the piece: that marks the draft stale. Edit the draft instead.
|
|
27
27
|
- Never send markdown to `draft save`.
|
|
@@ -41,7 +41,7 @@ Typical timing: brief and outline under a minute; research and draft 3–10 minu
|
|
|
41
41
|
6. **Quality pass.** CoAuthor already checks each new draft against the brief and for consistency, and fixes what it can: must-include items (and every figure they give, plus sentences claiming the post has no data the brief supplies), non-negotiables, tables vs their sections, "see the table" references, unsourced "most readers" claims, FAQ answers that defer, links (cut-short or malformed URLs, dead pages, citations that open a page about something else), and sentences that cite a research source: figures that are not in that source, a report edition that differs from the one cited ("the 2027 report" linked to the 2026 page), and up to 15 rules or figures checked against the source text (contradicted ones are corrected from the source when it can; the rest are reported). Whatever is still open is in `quality_check.unresolved` of `coauthor draft status <id> --json` (and `post-details show`), and the completion message says how many. Fix those first. Then `coauthor draft get <id> --format markdown --json` and read `data.markdown` in full. Check it against the brief's must-include, must-avoid, and non-negotiables. Look for: notes about the research process ("the retrieved sources do not…"), invented "checked <date>" lines, numbered lists that restart at 1, garbled `*`, `_`, or code spans, literal `[ ]` in checklists, the same caveat repeated across sections, claims without a source or cited to a page that doesn't support them, contradictions, and a messy Sources list (generic titles like "Google", duplicate entries). Fix them in step 8.
|
|
42
42
|
7. **Images.** `coauthor image generate <id> --all --wait --json` generates every planned image and waits for them (one image: `coauthor image generate <id> --placeholder-id <placeholder id> --json`, using the `id` UUID from `image list`). CoAuthor decides how many images a draft gets, sometimes only the featured image; the CLI can't add more, so tell the user if they expected several. Open each image and check it does not state numbers or claims the article does not make, and that its alt text matches what is visible (CoAuthor writes alt text from the finished image; fix it with `image metadata` only when it is wrong). See `references/images-and-social.md`. If the draft has interactive placeholders (beta), show them to the user and get a yes before building: `references/interactive-widgets.md`.
|
|
43
43
|
8. **Edits.** For prose changes: `coauthor draft revise <id> --instruction "..." --wait --json` (be specific: name the section and give a number, such as "cut the intro to under 60 words"), review each group's `before_markdown` and `after_markdown`, then `coauthor draft revision apply <id> <revision-id> --json` (optionally `--accept` or `--reject` with ids copied from `data.groups[].id`) or `coauthor draft revision discard <id> <revision-id> --json`. For exact text you already have, edit the document JSON and `draft save`. See `references/editing-drafts.md`.
|
|
44
|
-
9. **Deliver.** Give the user the final markdown (or `--format html`), the decision log (`coauthor log show <id> --json`: what you approved, what you asked CoAuthor to change, what you assumed), and the credits used (`coauthor credits <id> --json`). The user also sees the log in the project's workspace in the web app. With their yes: share link or WordPress export (`references/publishing-and-export.md`). For social posts and an email newsletter, `coauthor repurpose generate <id> --format all --json`, review `data.copy`, and `coauthor repurpose download <id> --out <dir>` (`references/repurposing.md`).
|
|
44
|
+
9. **Deliver.** Give the user the final markdown (or `--format html`), the decision log (`coauthor log show <id> --json`: what you approved, what you asked CoAuthor to change, what you assumed), and the credits used (`coauthor credits <id> --json`). The user also sees the log in the project's workspace in the web app. With their yes: share link or WordPress export (`references/publishing-and-export.md`). For social posts and an email newsletter, `coauthor repurpose generate <id> --format all --json`, review `data.copy`, and `coauthor repurpose download <id> --out <dir>` (`references/repurposing.md`). To post them to the user's connected accounts, now or scheduled: `coauthor social preview`, then with their yes `coauthor social post` (`references/images-and-social.md`, Post to social accounts).
|
|
45
45
|
|
|
46
46
|
## When something stops
|
|
47
47
|
|
|
@@ -83,7 +83,7 @@ Details, item fields, and what each kind means: `references/seo-content-plan.md`
|
|
|
83
83
|
|
|
84
84
|
## Not in the CLI yet
|
|
85
85
|
|
|
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,
|
|
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, turning the monthly SEO report email off (Settings, then Email), connecting or reconnecting social accounts (Settings, then Publishing: it needs a sign-in with each platform), and posting to TikTok (from the project's preview in the web app). Point the user to the CoAuthor web app at https://tools.clickminded.com/coauthor for these instead of improvising.
|
|
87
87
|
|
|
88
88
|
# Reference sections
|
|
89
89
|
|
|
@@ -280,6 +280,7 @@ Rough costs, to set expectations before starting:
|
|
|
280
280
|
- A complete article (brief through draft) is typically about 300 credits.
|
|
281
281
|
- Images and extra rework rounds (regenerating, many revisions) drive cost more than word count does.
|
|
282
282
|
- Adding the repurposed formats in the web app (social posts, newsletter, slideshow) adds roughly 100–150 more.
|
|
283
|
+
- Posting to social accounts (`coauthor social post`): 10 credits per account when the post goes out; X costs 20 per post plus 10 per reply. Failed and cancelled posts cost nothing.
|
|
283
284
|
- An SEO content plan (`coauthor seo-plan generate`): the first plan an account makes is free. Later plans are about 420 credits (most plans 300–500) and need 500 remaining to start. See `references/seo-content-plan.md`.
|
|
284
285
|
|
|
285
286
|
Tell the user the expected cost before large or repeated work, and report credits used at the end.
|
|
@@ -396,6 +397,28 @@ Images cost credits each time they are generated or edited, so check the brief a
|
|
|
396
397
|
3. To edit, save the complete post list: `coauthor thread save <id> --data @thread.json --json` with `{"posts":[...]}`. Include `"destination_url"` to change the link, and `"selected_social_account_id"` to choose the X account (it is kept when you leave it out).
|
|
397
398
|
4. Publishing posts to X immediately and publicly. It needs the user's explicit yes and a token with publish permission (`coauthor auth login --with-publish`): `coauthor publish thread <id> --yes --json`.
|
|
398
399
|
|
|
400
|
+
### Post to social accounts
|
|
401
|
+
|
|
402
|
+
CoAuthor posts the repurposed formats (`x-thread`, `x-post`, `linkedin`, `facebook`, `slideshow`, `video`; see `references/repurposing.md`) to the user's connected social accounts, now or at a set time. Email newsletters are not posted.
|
|
403
|
+
|
|
404
|
+
1. **Accounts.** `coauthor social accounts --json` lists the connected accounts (`data.accounts`: `id`, `platform`, `label`, `username`, `status`, `cli_posting`), how many the plan allows (`used`, `limit`), and which formats go to each platform. X is `twitter` in the data. Connecting or reconnecting an account needs a sign-in with the platform in a browser, so the user does it in the web app (Settings → Publishing, `data.connect_url`); you can't connect one from the CLI. A `status` of `needs_reconnect` means the user reconnects it there before you post to it.
|
|
405
|
+
2. **Pick the variation.** X posts, LinkedIn and Facebook have several variations: take the `id` from `coauthor repurpose show <id> --format <format> --json` (`data.copy.variations[].id`) and pass it as `--variant`. A slideshow posts its first ending unless `--variant <cta id>` picks another; a video needs `--variant` set to a finished render's `variant_id`. An X thread has no variations.
|
|
406
|
+
3. **Preview.** `coauthor social preview <id> --format linkedin --variant <variation id> --account linkedin --json` shows exactly what would be posted (`data.content`), the accounts it can go to with the credits for each (`data.accounts`), and, with `--account`, the same checks the post runs (`data.ready`, `data.issues`) and the cost (`data.credits.estimated`, `data.credits.remaining`). `--account` takes an account id, a platform (`x`, `linkedin`, `facebook`, `instagram`, `youtube`) when only one account of it is connected, or an `@username`; repeat it to post to several accounts at once. Slideshows and videos take `--caption "..."` (the default caption is the first LinkedIn variation, else Facebook, else the title) and videos to YouTube `--youtube-title "..."`.
|
|
407
|
+
4. **The article link.** When the text still holds `{{POST_URL}}`, `data.needs_post_link` is true and the post is refused with `post_link_required`. `data.suggested_destination_url` is the post's live address from post details, when known. Pass the link to the post with `--link <url>`: it is saved as that format's Destination URL (the same field `repurpose save` sets with `destination_url`), then the post goes out with it. Confirm the link with the user if it isn't the live address.
|
|
408
|
+
5. **Post, with the user's yes.** Show the user the preview text, the accounts, the time and the cost, and get an explicit OK. Then: `coauthor social post <id> --format linkedin --variant <variation id> --account linkedin --at 2026-11-20T09:00:00-05:00 --yes --json`, or `--now` instead of `--at` to post right away. `--at` is an ISO time with an offset, at least a minute ahead and up to a year; `--timezone <zone>` records the user's time zone (the CLI sends this machine's by default). It needs a login with publish permission (`coauthor auth login --with-publish`).
|
|
409
|
+
- `--wait` follows the post: a `--now` post until it is published or fails, a scheduled post until the platforms confirm the schedule. After 9 minutes it returns `still_running` (exit code 2); keep following with `coauthor social status <id> <post-id> --wait --json`.
|
|
410
|
+
- Each post prints an operation key (`idempotency_key`). After a timeout or network error, don't post again: check `coauthor social list <id> --json` or `coauthor operation status <key> --json`, or rerun with `--idempotency-key <key>`, which replays the recorded request instead of posting twice.
|
|
411
|
+
6. **Follow up.** `coauthor social list <id> --json` shows the project's posts (`data.posts`: `id`, `status`, `scheduled_for`, `targets`, `results` with each account's live `url` or `error`, `credits_charged`). Statuses: `scheduling` (being sent to the platforms), `scheduled`, `publishing`, `published`, `partial` (some accounts failed), `failed`, `cancelled`. `coauthor social status <id> <post-id> --json` reads one.
|
|
412
|
+
- Move a scheduled post: `coauthor social reschedule <id> <post-id> --at <ISO time> --json` (only `scheduled` posts, `not_editable` otherwise).
|
|
413
|
+
- Cancel one that hasn't gone out: `coauthor social cancel <id> <post-id> --yes --json`. Nothing is charged.
|
|
414
|
+
- Publish again to the accounts that failed (`failed` or `partial`), after fixing the cause and with the user's OK: `coauthor social retry <id> <post-id> --yes --wait --json`.
|
|
415
|
+
|
|
416
|
+
Credits are charged per account when the post goes out: 10 per account, and X costs 20 per post plus 10 for each reply in a thread or X post. Failed and cancelled posts cost nothing.
|
|
417
|
+
|
|
418
|
+
**TikTok** posts are made in the web app. TikTok requires the user to see its posting screen for every post (who can see it, comments, duets and stitches, the brand-content disclosure, and its consent line), which the CLI cannot show, so the CLI refuses TikTok accounts with `tiktok_web_only` and points to the project in the web app.
|
|
419
|
+
|
|
420
|
+
`coauthor publish thread` (above) posts a thread through the older X connection listed in `coauthor integrations list`; accounts connected under Settings → Publishing go through `social post`.
|
|
421
|
+
|
|
399
422
|
### Other formats
|
|
400
423
|
|
|
401
424
|
X posts, LinkedIn, Facebook, and email newsletter versions: see `references/repurposing.md`. Carousel slideshows and short vertical videos: same file, under Slideshow and Video.
|
|
@@ -514,9 +537,13 @@ Export creates a **draft post** in the user's WordPress site (it is not publishe
|
|
|
514
537
|
|
|
515
538
|
See `references/images-and-social.md`. Publishing a thread posts immediately and needs the user's yes.
|
|
516
539
|
|
|
540
|
+
### Social accounts
|
|
541
|
+
|
|
542
|
+
To post or schedule the repurposed posts, slideshows and videos to the user's connected accounts: `coauthor social preview`, then `coauthor social post … --yes` (`references/images-and-social.md`, Post to social accounts).
|
|
543
|
+
|
|
517
544
|
### If a live action's result is unclear
|
|
518
545
|
|
|
519
|
-
After a network error or an unclear result on an export or
|
|
546
|
+
After a network error or an unclear result on an export, publish or social post, do not run it again straight away. Every export and publish prints its `idempotency_key`; check `coauthor operation status <idempotency_key> --json` (or `coauthor operation list --json`) first. To retry safely, pass the same key back with `--idempotency-key <key>`, so CoAuthor won't run it twice.
|
|
520
547
|
|
|
521
548
|
## references/repurposing.md
|
|
522
549
|
|
|
@@ -599,7 +626,7 @@ To fix one panel before rendering: `coauthor image list <id> --artifact video --
|
|
|
599
626
|
|
|
600
627
|
Hand the user the folder, or paste from `data.copy`.
|
|
601
628
|
|
|
602
|
-
|
|
629
|
+
The X thread, X posts, LinkedIn, Facebook, slideshows and videos can be posted or scheduled to the user's connected social accounts with `coauthor social post` after the user's explicit OK (`references/images-and-social.md`, Post to social accounts). Email newsletters are copy-and-paste.
|
|
603
630
|
|
|
604
631
|
## references/seo-content-plan.md
|
|
605
632
|
|
|
@@ -695,7 +722,7 @@ Some plans tag ideas whose searches are ones where Google AI answers cite a comp
|
|
|
695
722
|
- `ai_search_volume`: DataForSEO's estimate of monthly AI searches behind the idea's matching searches.
|
|
696
723
|
- `questions`: on United States / English plans, up to 3 ChatGPT questions about the idea whose answers cite a competitor (`question`, `competitor`). Empty elsewhere.
|
|
697
724
|
|
|
698
|
-
An AI gap idea went through the same checks as every other idea; the tag explains why it matters, it does not mean the idea is more likely to rank. The human output of `show` prefixes it with `[AI gap]` and names the competitors. When you write one, `seo-plan write` puts its questions into the post's brief
|
|
725
|
+
An AI gap idea went through the same checks as every other idea; the tag explains why it matters, it does not mean the idea is more likely to rank. The human output of `show` prefixes it with `[AI gap]` and names the competitors. When you write one, `seo-plan write` puts its questions into the post's brief. The outline checks that its sections cover what those answers need, without adding a FAQ or question headings.
|
|
699
726
|
|
|
700
727
|
`ai_search_update_available` (top level of `show --json`) is `true` for a full plan made before AI search ideas went live on 2026-11-18. That plan has no `ai_visibility` and no AI gap ideas. Running `coauthor seo-plan generate` updates it and adds them, using the user's credits (`estimate_credits`). Mention it once when it is `true`, and do not update the plan without the user's go-ahead. It turns `false` after an update, and it is always `false` for previews and stale plans.
|
|
701
728
|
|
|
@@ -834,8 +861,21 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
834
861
|
| `not_writable` | `seo-plan write` on an item that isn't a `post` idea (improve, page idea, left out, covered). | Only `post` items are written. Improve and page ideas are tasks on the user's site. |
|
|
835
862
|
| `plan_item_not_found` | `seo-plan write`, `dismiss` or `done` with an unknown item id (`done` also rejects left-out and not-checked items). | Take the `id` from `seo-plan show --json`. |
|
|
836
863
|
| `operation_in_progress` | A `seo-plan generate` with the same `--idempotency-key` is still being processed. | Wait a moment and check `coauthor seo-plan show`. |
|
|
864
|
+
| `social_posting_unavailable` | Posting to social accounts isn't switched on for this account yet. | Hand the user the copy from `repurpose show` to post themselves. |
|
|
865
|
+
| `social_account_not_connected` | An `--account` value matches no connected account (`details.accounts` lists them). | Use an `id` from `coauthor social accounts --json`. If the account isn't there, the user connects it in the web app (`details.connect_url`, Settings → Publishing). |
|
|
866
|
+
| `social_account_needs_reconnect` | The platform signed the account out. | The user reconnects it in the web app (`details.connect_url`), then post again. |
|
|
867
|
+
| `account_ambiguous` | A platform or username matches several connected accounts (`details.matches`). | Pass the account `id` instead. |
|
|
868
|
+
| `tiktok_web_only` | TikTok posts need TikTok's posting screen shown to the user, which only the web app shows. | Give the user `details.web_url` to post it from the project's preview in the web app. |
|
|
869
|
+
| `post_link_required` | The text still holds `{{POST_URL}}` and the format has no Destination URL. | Rerun `social post` with `--link <article url>` (`details.suggested_destination_url` is the live address when known; confirm it with the user if not). |
|
|
870
|
+
| `source_not_ready` | The format hasn't been generated, the variation id is wrong, the slideshow has no slides, or the video has no finished render. | Run `details.next_command` for the ids, or generate/render the format first (`references/repurposing.md`). |
|
|
871
|
+
| `invalid_schedule` | `--at` is in the past, less than a minute ahead, more than a year ahead, or both `--now` and `--at` were sent. | Pick a valid time, or post with `--now`. |
|
|
872
|
+
| `social_post_rejected` | A social platform refused the post (the message says why, for example text too long). Nothing was created or charged. | Fix the text with `repurpose save` (or the caption) and post again. |
|
|
873
|
+
| `social_unavailable` | The social platforms couldn't be reached. | Try again in a few minutes. Check `coauthor social list` before posting again. |
|
|
874
|
+
| `social_post_failed` | A post failed on the platforms (`details` or `data.post.results` give each account's error). Nothing was charged for those accounts. | Tell the user. After the cause is fixed (often a reconnect), `coauthor social retry <id> <post-id> --yes --wait`. |
|
|
875
|
+
| `not_editable`, `not_cancellable`, `not_retryable` | `social reschedule` on a post that isn't `scheduled`, `social cancel` on one that already went out, or `social retry` on one that didn't fail. | Check `coauthor social status <id> <post-id> --json`. |
|
|
876
|
+
| `operation_failed` | A `social post` or `social retry` rerun with an `--idempotency-key` whose recorded request failed. | Fix the cause (the message has it), then run the command again without the key. |
|
|
837
877
|
| `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
|
|
838
|
-
| `request_timeout`, `network_error` | No answer from CoAuthor in time, or the connection failed. | For reads, retry. For exports, publishes, and image generate/edit, check `coauthor operation status <idempotency_key>` before retrying. |
|
|
878
|
+
| `request_timeout`, `network_error` | No answer from CoAuthor in time, or the connection failed. | For reads, retry. For exports, publishes, social posts, and image generate/edit, check `coauthor operation status <idempotency_key>` before retrying. |
|
|
839
879
|
|
|
840
880
|
### Sign-in
|
|
841
881
|
|