@clickminded/coauthor-cli 0.0.31 → 0.0.33
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 -1
- package/dist/client.d.ts +23 -3
- package/dist/client.js +88 -15
- package/dist/commands.d.ts +7 -0
- package/dist/commands.js +447 -103
- package/dist/index.d.ts +12 -1
- package/dist/index.js +97 -59
- package/dist/output.d.ts +8 -0
- package/dist/output.js +28 -10
- package/dist/parser.d.ts +2 -0
- package/dist/parser.js +12 -0
- package/package.json +1 -1
- package/skills/coauthor/SKILL.md +1 -1
- package/skills/coauthor/references/images-and-social.md +2 -2
- package/skills/coauthor/references/publishing-and-export.md +1 -1
- package/skills/coauthor/references/repurposing.md +12 -2
- package/skills/coauthor/references/troubleshooting.md +2 -0
- package/skills/cursor/coauthor-cli.mdc +18 -6
package/dist/index.d.ts
CHANGED
|
@@ -1,2 +1,13 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
|
|
2
|
+
import { type JsonValue } from './client.js';
|
|
3
|
+
export type CliIo = {
|
|
4
|
+
stdout: (text: string) => void;
|
|
5
|
+
stderr: (text: string) => void;
|
|
6
|
+
};
|
|
7
|
+
export declare function main(argv?: string[], io?: CliIo): Promise<number>;
|
|
8
|
+
export declare function formatCliError(error: unknown, baseUrl: string, argv?: string[]): {
|
|
9
|
+
error: Error;
|
|
10
|
+
result?: JsonValue;
|
|
11
|
+
exitCode: number;
|
|
12
|
+
};
|
|
13
|
+
export declare function resolveProjectIdFromArgv(argv: string[]): string | undefined;
|
package/dist/index.js
CHANGED
|
@@ -1,21 +1,25 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
import { readFileSync, realpathSync } from 'node:fs';
|
|
3
3
|
import { fileURLToPath } from 'node:url';
|
|
4
|
-
import { AgentHttpError, AgentClient, normalizeBaseUrl } from './client.js';
|
|
4
|
+
import { AgentHttpError, AgentClient, AgentRequestError, normalizeBaseUrl } from './client.js';
|
|
5
5
|
import { DEFAULT_BASE_URL, resolveRuntimeConfig } from './config.js';
|
|
6
6
|
import { helpResult, runCommand } from './commands.js';
|
|
7
7
|
import { renderError, renderResult } from './output.js';
|
|
8
|
-
import { parseCliArgs } from './parser.js';
|
|
9
|
-
|
|
8
|
+
import { getString, optionTakesValue, parseCliArgs } from './parser.js';
|
|
9
|
+
const processIo = {
|
|
10
|
+
stdout: (text) => { process.stdout.write(text); },
|
|
11
|
+
stderr: (text) => { process.stderr.write(text); },
|
|
12
|
+
};
|
|
13
|
+
export async function main(argv = process.argv.slice(2), io = processIo) {
|
|
10
14
|
let resolvedBaseUrl = resolveBaseUrlFromArgv(argv);
|
|
11
15
|
try {
|
|
12
16
|
const parsed = parseCliArgs(argv);
|
|
13
17
|
if (parsed.globals.version || (parsed.command.length === 1 && parsed.command[0] === 'version')) {
|
|
14
|
-
|
|
18
|
+
io.stdout(parsed.globals.json ? `${JSON.stringify({ ok: true, version: cliVersion() })}\n` : `${cliVersion()}\n`);
|
|
15
19
|
return 0;
|
|
16
20
|
}
|
|
17
21
|
if (parsed.globals.help) {
|
|
18
|
-
|
|
22
|
+
io.stdout(renderResult(helpResult(parsed.command), parsed.globals.json));
|
|
19
23
|
return 0;
|
|
20
24
|
}
|
|
21
25
|
const runtimeConfig = await resolveRuntimeConfig({
|
|
@@ -29,51 +33,99 @@ export async function main(argv = process.argv.slice(2)) {
|
|
|
29
33
|
baseUrl: runtimeConfig.baseUrl,
|
|
30
34
|
token: runtimeConfig.token,
|
|
31
35
|
});
|
|
32
|
-
|
|
36
|
+
// Failures and pauses (ok: false) go to stderr whether they came from a
|
|
37
|
+
// thrown HTTP error or a --wait loop, so callers read one stream for them.
|
|
38
|
+
const output = renderResult(result, parsed.globals.json);
|
|
39
|
+
if (result.ok)
|
|
40
|
+
io.stdout(output);
|
|
41
|
+
else
|
|
42
|
+
io.stderr(output);
|
|
33
43
|
return result.exitCode ?? (result.ok ? 0 : 1);
|
|
34
44
|
}
|
|
35
45
|
catch (error) {
|
|
36
46
|
const wantsJson = argv.includes('--json');
|
|
37
47
|
const formatted = formatCliError(error, resolvedBaseUrl, argv);
|
|
38
|
-
|
|
48
|
+
io.stderr(wantsJson
|
|
49
|
+
? renderError(formatted.result ?? formatted.error, true)
|
|
50
|
+
: renderError(formatted.error, false));
|
|
39
51
|
return formatted.exitCode;
|
|
40
52
|
}
|
|
41
53
|
}
|
|
42
|
-
function formatCliError(error, baseUrl, argv = []) {
|
|
54
|
+
export function formatCliError(error, baseUrl, argv = []) {
|
|
43
55
|
if (error instanceof AgentHttpError) {
|
|
56
|
+
// Keep the server's error code and details (e.g. the current draft version
|
|
57
|
+
// on a 409) on every --json error so agents can recover without guessing.
|
|
58
|
+
const envelope = extractEnvelopeError(error.responseBody);
|
|
59
|
+
const errorFields = {
|
|
60
|
+
...(envelope?.code ? { code: envelope.code } : {}),
|
|
61
|
+
http_status: error.status,
|
|
62
|
+
...(envelope?.details !== undefined ? { details: envelope.details } : {}),
|
|
63
|
+
...(error.idempotencyKey ? { idempotency_key: error.idempotencyKey } : {}),
|
|
64
|
+
};
|
|
65
|
+
const operationHint = operationLookupHint(envelope?.details, error.idempotencyKey);
|
|
44
66
|
const entitlement = formatEntitlementResult(error.responseBody);
|
|
45
67
|
if (entitlement)
|
|
46
|
-
return { error: new Error(entitlement.message), result: entitlement, exitCode: 2 };
|
|
68
|
+
return { error: new Error(entitlement.message), result: { ...entitlement, ...errorFields }, exitCode: 2 };
|
|
47
69
|
const requiresKey = formatRequiresKeyResult(error.responseBody, baseUrl);
|
|
48
70
|
if (requiresKey)
|
|
49
|
-
return { error: new Error(requiresKey.message), result: requiresKey, exitCode: 2 };
|
|
71
|
+
return { error: new Error(requiresKey.message), result: { ...requiresKey, ...errorFields }, exitCode: 2 };
|
|
50
72
|
const serverMessage = extractErrorMessage(error.responseBody) ?? error.message;
|
|
51
73
|
const message = error.status === 401
|
|
52
74
|
? `${serverMessage}\nSign in with \`coauthor auth login\` (or set COAUTHOR_TOKEN).`
|
|
53
75
|
: serverMessage;
|
|
54
76
|
const researchBlock = formatResearchDraftBlock(message, argv);
|
|
55
77
|
if (researchBlock)
|
|
56
|
-
return { error: new Error(researchBlock.message), result: researchBlock, exitCode: 2 };
|
|
57
|
-
// Keep the server's error code and details (e.g. the current draft version
|
|
58
|
-
// on a 409) so agents can recover without guessing.
|
|
59
|
-
const envelope = extractEnvelopeError(error.responseBody);
|
|
78
|
+
return { error: new Error(researchBlock.message), result: { ...researchBlock, code: researchBlock.status, ...errorFields }, exitCode: 2 };
|
|
60
79
|
const current = currentDraftDetails(envelope?.details);
|
|
61
|
-
const humanMessage =
|
|
62
|
-
|
|
63
|
-
|
|
80
|
+
const humanMessage = [
|
|
81
|
+
current
|
|
82
|
+
? `${message}\nCurrent draft: version ${current.version_number ?? 'unknown'}${current.content_hash ? `, content_hash ${current.content_hash}` : ''}. Re-read it with \`${current.reread_command ?? 'coauthor draft get <project-id> --format json --json'}\` and save again.`
|
|
83
|
+
: message,
|
|
84
|
+
operationHint,
|
|
85
|
+
].filter(Boolean).join('\n');
|
|
64
86
|
return {
|
|
65
87
|
error: new Error(humanMessage),
|
|
66
88
|
result: {
|
|
67
89
|
ok: false,
|
|
68
90
|
error: humanMessage,
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
...(envelope?.details !== undefined ? { details: envelope.details } : {}),
|
|
91
|
+
code: envelope?.code ?? `http_${error.status}`,
|
|
92
|
+
...errorFields,
|
|
72
93
|
},
|
|
73
94
|
exitCode: 1,
|
|
74
95
|
};
|
|
75
96
|
}
|
|
76
|
-
|
|
97
|
+
if (error instanceof AgentRequestError) {
|
|
98
|
+
return {
|
|
99
|
+
error,
|
|
100
|
+
result: {
|
|
101
|
+
ok: false,
|
|
102
|
+
error: error.message,
|
|
103
|
+
code: error.code,
|
|
104
|
+
http_status: null,
|
|
105
|
+
...(error.idempotencyKey ? { idempotency_key: error.idempotencyKey } : {}),
|
|
106
|
+
},
|
|
107
|
+
exitCode: 1,
|
|
108
|
+
};
|
|
109
|
+
}
|
|
110
|
+
const normalized = error instanceof Error ? error : new Error(String(error));
|
|
111
|
+
return {
|
|
112
|
+
error: normalized,
|
|
113
|
+
result: { ok: false, error: normalized.message, code: isUsageMessage(normalized.message) ? 'usage_error' : 'cli_error', http_status: null },
|
|
114
|
+
exitCode: 1,
|
|
115
|
+
};
|
|
116
|
+
}
|
|
117
|
+
function isUsageMessage(message) {
|
|
118
|
+
return /^(Usage:|Unknown option|Unknown command|Missing |Unknown \w+ command)/.test(message) || /Run `coauthor [^`]*--help`/.test(message);
|
|
119
|
+
}
|
|
120
|
+
// Live actions (publish, export) are recorded as operations under the
|
|
121
|
+
// Idempotency-Key the CLI sent. Point at it so a caller can check the outcome
|
|
122
|
+
// instead of retrying blind.
|
|
123
|
+
function operationLookupHint(details, idempotencyKey) {
|
|
124
|
+
if (!idempotencyKey)
|
|
125
|
+
return null;
|
|
126
|
+
if (!details || typeof details !== 'object' || Array.isArray(details) || !('operation' in details))
|
|
127
|
+
return null;
|
|
128
|
+
return `Operation key: ${idempotencyKey} (check it with \`coauthor operation status ${idempotencyKey} --json\`; retry with --idempotency-key ${idempotencyKey} to replay safely).`;
|
|
77
129
|
}
|
|
78
130
|
function formatEntitlementResult(body) {
|
|
79
131
|
const envelopeError = extractEnvelopeError(body);
|
|
@@ -144,44 +196,30 @@ function formatResearchDraftBlock(message, argv) {
|
|
|
144
196
|
exitCode: 2,
|
|
145
197
|
};
|
|
146
198
|
}
|
|
147
|
-
function resolveProjectIdFromArgv(argv) {
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
return
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
'
|
|
158
|
-
'
|
|
159
|
-
|
|
160
|
-
'
|
|
161
|
-
|
|
162
|
-
'
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
'workflow',
|
|
172
|
-
'advance',
|
|
173
|
-
'rewind',
|
|
174
|
-
'approve',
|
|
175
|
-
'resume',
|
|
176
|
-
'image',
|
|
177
|
-
'thread',
|
|
178
|
-
'publish',
|
|
179
|
-
'export',
|
|
180
|
-
'operation',
|
|
181
|
-
'credits',
|
|
182
|
-
'skills',
|
|
183
|
-
]);
|
|
184
|
-
return argv.find((arg) => !arg.startsWith('-') && !commandWords.has(arg));
|
|
199
|
+
export function resolveProjectIdFromArgv(argv) {
|
|
200
|
+
try {
|
|
201
|
+
const parsed = parseCliArgs(argv);
|
|
202
|
+
return getString(parsed.values, 'project') ?? parsed.positionals[0];
|
|
203
|
+
}
|
|
204
|
+
catch {
|
|
205
|
+
// Unparseable argv: walk it, skipping the values of flags that take one.
|
|
206
|
+
}
|
|
207
|
+
const words = [];
|
|
208
|
+
for (let index = 0; index < argv.length; index += 1) {
|
|
209
|
+
const arg = argv[index] ?? '';
|
|
210
|
+
if (arg === '--project' && argv[index + 1])
|
|
211
|
+
return argv[index + 1];
|
|
212
|
+
if (arg.startsWith('--project='))
|
|
213
|
+
return arg.slice('--project='.length);
|
|
214
|
+
if (arg.startsWith('-')) {
|
|
215
|
+
if (optionTakesValue(arg))
|
|
216
|
+
index += 1;
|
|
217
|
+
continue;
|
|
218
|
+
}
|
|
219
|
+
words.push(arg);
|
|
220
|
+
}
|
|
221
|
+
const commandWords = new Set(['auth', 'login', 'status', 'logout', 'project', 'create', 'list', 'show', 'workspace', 'chat', 'contract', 'outline', 'research-plan', 'research', 'run', 'draft', 'generate', 'get', 'save', 'workflow', 'advance', 'rewind', 'approve', 'resume', 'image', 'thread', 'publish', 'export', 'operation', 'credits', 'skills']);
|
|
222
|
+
return words.find((word) => !commandWords.has(word));
|
|
185
223
|
}
|
|
186
224
|
function extractErrorMessage(body) {
|
|
187
225
|
if (!body || typeof body !== 'object' || Array.isArray(body) || !('error' in body))
|
package/dist/output.d.ts
CHANGED
|
@@ -7,6 +7,14 @@ export type CommandResult = {
|
|
|
7
7
|
exitCode?: number;
|
|
8
8
|
settings_url?: string;
|
|
9
9
|
resume_command?: string;
|
|
10
|
+
/** The Idempotency-Key sent with the command's live request; look it up with `coauthor operation status <key>`. */
|
|
11
|
+
idempotency_key?: string;
|
|
12
|
+
/** Set when `message` already shows everything in `data`, so plain output doesn't print it twice. Never rendered. */
|
|
13
|
+
messageIncludesData?: boolean;
|
|
10
14
|
};
|
|
11
15
|
export declare function renderResult(result: CommandResult, json: boolean): string;
|
|
12
16
|
export declare function renderError(error: unknown, json: boolean): string;
|
|
17
|
+
export declare function withErrorFields<T extends Record<string, unknown>>(value: T): T & {
|
|
18
|
+
code: unknown;
|
|
19
|
+
http_status: unknown;
|
|
20
|
+
};
|
package/dist/output.js
CHANGED
|
@@ -1,22 +1,40 @@
|
|
|
1
1
|
export function renderResult(result, json) {
|
|
2
|
+
const { messageIncludesData, ...printable } = result;
|
|
2
3
|
if (json)
|
|
3
|
-
return `${JSON.stringify(result, null, 2)}\n`;
|
|
4
|
+
return `${JSON.stringify(result.ok ? printable : withErrorFields(printable), null, 2)}\n`;
|
|
5
|
+
// Plain output used to stop at the message, hiding ids and clarification
|
|
6
|
+
// questions. Print the message, then the data behind it.
|
|
7
|
+
const parts = [];
|
|
4
8
|
if (result.message)
|
|
5
|
-
|
|
6
|
-
if (result.data
|
|
7
|
-
|
|
8
|
-
|
|
9
|
+
parts.push(result.message);
|
|
10
|
+
if (result.data !== undefined && result.data !== null && !(result.message && messageIncludesData)) {
|
|
11
|
+
parts.push(JSON.stringify(result.data, null, 2));
|
|
12
|
+
}
|
|
13
|
+
return parts.length > 0 ? `${parts.join('\n')}\n` : '';
|
|
9
14
|
}
|
|
10
15
|
export function renderError(error, json) {
|
|
11
16
|
if (json && error && typeof error === 'object' && !Array.isArray(error) && 'ok' in error) {
|
|
12
|
-
return `${JSON.stringify(error, null, 2)}\n`;
|
|
17
|
+
return `${JSON.stringify(withErrorFields(error), null, 2)}\n`;
|
|
13
18
|
}
|
|
19
|
+
const record = error && typeof error === 'object' && !Array.isArray(error) ? error : null;
|
|
14
20
|
const message = error instanceof Error
|
|
15
21
|
? error.message
|
|
16
|
-
:
|
|
17
|
-
?
|
|
18
|
-
:
|
|
22
|
+
: typeof record?.message === 'string'
|
|
23
|
+
? record.message
|
|
24
|
+
: typeof record?.error === 'string'
|
|
25
|
+
? record.error
|
|
26
|
+
: String(error);
|
|
19
27
|
if (json)
|
|
20
|
-
return `${JSON.stringify({ ok: false, error: message }, null, 2)}\n`;
|
|
28
|
+
return `${JSON.stringify({ ok: false, error: message, code: 'cli_error', http_status: null }, null, 2)}\n`;
|
|
21
29
|
return `Error: ${message}\n`;
|
|
22
30
|
}
|
|
31
|
+
// Every --json failure carries `code` and `http_status` (null when no HTTP
|
|
32
|
+
// response caused it: a pause seen while polling, a usage error, a timeout).
|
|
33
|
+
export function withErrorFields(value) {
|
|
34
|
+
const status = typeof value.status === 'string' ? value.status : undefined;
|
|
35
|
+
return {
|
|
36
|
+
...value,
|
|
37
|
+
code: value.code ?? status ?? 'failed',
|
|
38
|
+
http_status: value.http_status ?? null,
|
|
39
|
+
};
|
|
40
|
+
}
|
package/dist/parser.d.ts
CHANGED
|
@@ -25,6 +25,8 @@ export declare const commandInputSchema: z.ZodObject<{
|
|
|
25
25
|
}, z.core.$strip>;
|
|
26
26
|
values: z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
|
|
27
27
|
}, z.core.$strip>;
|
|
28
|
+
/** True when `--name` (or its short alias) consumes the next argv entry as its value. */
|
|
29
|
+
export declare function optionTakesValue(flag: string): boolean;
|
|
28
30
|
export declare function parseCliArgs(argv: string[]): ParsedCommand;
|
|
29
31
|
export declare function getString(values: ParsedCommand['values'], name: string): string | undefined;
|
|
30
32
|
export declare function requireString(values: ParsedCommand['values'], name: string): string;
|
package/dist/parser.js
CHANGED
|
@@ -76,7 +76,19 @@ const OPTIONS = {
|
|
|
76
76
|
apply: { type: 'boolean', default: false },
|
|
77
77
|
accept: { type: 'string' },
|
|
78
78
|
reject: { type: 'string' },
|
|
79
|
+
'idempotency-key': { type: 'string' },
|
|
79
80
|
};
|
|
81
|
+
/** True when `--name` (or its short alias) consumes the next argv entry as its value. */
|
|
82
|
+
export function optionTakesValue(flag) {
|
|
83
|
+
const name = flag.replace(/^--?/, '').split('=')[0] ?? '';
|
|
84
|
+
if (flag.includes('='))
|
|
85
|
+
return false;
|
|
86
|
+
const entries = Object.entries(OPTIONS);
|
|
87
|
+
const option = flag.startsWith('--')
|
|
88
|
+
? entries.find(([key]) => key === name)?.[1]
|
|
89
|
+
: entries.find(([, value]) => value.short === name)?.[1];
|
|
90
|
+
return option?.type === 'string';
|
|
91
|
+
}
|
|
80
92
|
export function parseCliArgs(argv) {
|
|
81
93
|
let parsed;
|
|
82
94
|
try {
|
package/package.json
CHANGED
package/skills/coauthor/SKILL.md
CHANGED
|
@@ -66,4 +66,4 @@ Everything else, including auth problems: `references/troubleshooting.md`. Credi
|
|
|
66
66
|
|
|
67
67
|
## Not in the CLI yet
|
|
68
68
|
|
|
69
|
-
Creating or editing writer profiles, PDFs over about 3.3 MB, adding more images than CoAuthor planned
|
|
69
|
+
Creating or editing writer profiles, PDFs over about 3.3 MB, and adding more images than CoAuthor planned. Point the user to the CoAuthor web app at https://tools.clickminded.com/coauthor for these instead of improvising.
|
|
@@ -6,7 +6,7 @@ Draft generation plans image placeholders, including a featured image (`is_featu
|
|
|
6
6
|
|
|
7
7
|
1. `coauthor image list <id> --json` returns `data.placeholders`. Each has an `id` (UUID), a `purpose`, an `image_type`, and the planned brief.
|
|
8
8
|
2. Generate them all and wait: `coauthor image generate <id> --all --wait --json`. It skips images that are already done, and reports `done`, `failed`, and `still_running` (check again with `coauthor image status <id> --json`). Each image takes about 20 seconds.
|
|
9
|
-
3. To generate one: `coauthor image generate <id> --placeholder-id <id UUID> --json` (the `id` UUID
|
|
9
|
+
3. To generate one: `coauthor image generate <id> --placeholder-id <id UUID> --json` (the `id` UUID or the descriptive `placeholder_id`; optional `--grounding-mode <mode>`, `--image-generation-model <id>`), then poll `coauthor image status <id> --json`.
|
|
10
10
|
4. Check every finished image (the URLs are in `image status` and in `draft get --format markdown`):
|
|
11
11
|
- Charts and tables must match the article's numbers, and must not state figures the article deliberately leaves open.
|
|
12
12
|
- Screens of real products (for example a Google or Meta interface) must not be presented as genuine.
|
|
@@ -25,4 +25,4 @@ Images cost credits each time they are generated or edited, so check the brief a
|
|
|
25
25
|
|
|
26
26
|
## Other formats
|
|
27
27
|
|
|
28
|
-
X posts, LinkedIn, Facebook, and email newsletter versions: see `references/repurposing.md`. Carousel slideshows and short videos
|
|
28
|
+
X posts, LinkedIn, Facebook, and email newsletter versions: see `references/repurposing.md`. Carousel slideshows and short vertical videos: same file, under Slideshow and Video.
|
|
@@ -34,4 +34,4 @@ See `references/images-and-social.md`. Publishing a thread posts immediately and
|
|
|
34
34
|
|
|
35
35
|
## If a live action's result is unclear
|
|
36
36
|
|
|
37
|
-
After a network error or an unclear result on an export or publish, do not run it again straight away.
|
|
37
|
+
After a network error or an unclear result on an export or publish, 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.
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# Repurposing: social posts
|
|
1
|
+
# Repurposing: social posts, an email newsletter, slideshows, and video
|
|
2
2
|
|
|
3
3
|
Once the draft is final, CoAuthor turns it into distribution copy in the project's voice.
|
|
4
4
|
|
|
@@ -10,7 +10,7 @@ Once the draft is final, CoAuthor turns it into distribution copy in the project
|
|
|
10
10
|
| Facebook post | `facebook` | Variations with alternate hooks |
|
|
11
11
|
| Email newsletter | `email` | Variations with subject line, preheader, and body |
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
Carousel slideshows and short vertical videos have their own steps, because their illustrated panels are generated as images first (see Slideshow and Video below).
|
|
14
14
|
|
|
15
15
|
## Generate
|
|
16
16
|
|
|
@@ -44,6 +44,16 @@ coauthor repurpose save <id> --format x-thread --data '{"posts":[...]}' --json
|
|
|
44
44
|
|
|
45
45
|
Add `"destination_url": "https://..."` to point the posts at the published article. Keep the `{{POST_URL}}` placeholder in stored text; it is replaced with the destination URL on copy.
|
|
46
46
|
|
|
47
|
+
## Slideshow
|
|
48
|
+
|
|
49
|
+
A carousel of 1080x1350 slides (for LinkedIn or Instagram) with illustrated panels and a closing call-to-action slide.
|
|
50
|
+
|
|
51
|
+
1. `coauthor repurpose generate <id> --format slideshow [--cta save,follow] --json` writes the slides and queues one image per panel. Up to 4 endings: `save`, `follow`, `comment`, `share`, `read_more`, plus one `custom:<text>`; the default is `save`. Panel images cost image credits, which is why slideshows are not part of `--format all`.
|
|
52
|
+
2. `coauthor repurpose status <id> --format slideshow --wait --json` waits until no panel is still generating. If some failed, retry them with `coauthor image generate` or in the web app.
|
|
53
|
+
3. `coauthor repurpose download <id> --format slideshow [--variant <cta>] --out <dir>` renders the PNGs on the server and saves them as `slideshow/<cta>/slide-NN.png`, one folder per ending. `panels_not_ready` (409) means images are still generating or failed. Rendering again with no changes returns the same files.
|
|
54
|
+
|
|
55
|
+
The server draws the slides with the Inter font, so line breaks can differ slightly from the web app's own PNG download.
|
|
56
|
+
|
|
47
57
|
## Video
|
|
48
58
|
|
|
49
59
|
A short vertical video (1080x1920) of the article's key points, with illustrated panels and a closing call to action.
|
|
@@ -30,6 +30,8 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
30
30
|
| `workflow_token_mismatch`, `conflict` | The project moved on since you read it (for example someone used the web app). | Re-read the state with `coauthor workflow status <id> --json` and continue from there. |
|
|
31
31
|
| `insufficient_scope` | The token can't publish. | `coauthor auth login --with-publish`. |
|
|
32
32
|
| `wordpress_connection_required` | Several WordPress sites are connected. | Ask which one from `details.connections`, add `--connection-id`. |
|
|
33
|
+
| `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
|
|
34
|
+
| `request_timeout`, `network_error` | No answer from CoAuthor in time, or the connection failed. | For reads, retry. For exports and publishes, check `coauthor operation status <idempotency_key>` before retrying. |
|
|
33
35
|
|
|
34
36
|
## Sign-in
|
|
35
37
|
|
|
@@ -68,7 +68,7 @@ Everything else, including auth problems: `references/troubleshooting.md`. Credi
|
|
|
68
68
|
|
|
69
69
|
## Not in the CLI yet
|
|
70
70
|
|
|
71
|
-
Creating or editing writer profiles, PDFs over about 3.3 MB, adding more images than CoAuthor planned
|
|
71
|
+
Creating or editing writer profiles, PDFs over about 3.3 MB, and adding more images than CoAuthor planned. Point the user to the CoAuthor web app at https://tools.clickminded.com/coauthor for these instead of improvising.
|
|
72
72
|
|
|
73
73
|
# Reference sections
|
|
74
74
|
|
|
@@ -335,7 +335,7 @@ Draft generation plans image placeholders, including a featured image (`is_featu
|
|
|
335
335
|
|
|
336
336
|
1. `coauthor image list <id> --json` returns `data.placeholders`. Each has an `id` (UUID), a `purpose`, an `image_type`, and the planned brief.
|
|
337
337
|
2. Generate them all and wait: `coauthor image generate <id> --all --wait --json`. It skips images that are already done, and reports `done`, `failed`, and `still_running` (check again with `coauthor image status <id> --json`). Each image takes about 20 seconds.
|
|
338
|
-
3. To generate one: `coauthor image generate <id> --placeholder-id <id UUID> --json` (the `id` UUID
|
|
338
|
+
3. To generate one: `coauthor image generate <id> --placeholder-id <id UUID> --json` (the `id` UUID or the descriptive `placeholder_id`; optional `--grounding-mode <mode>`, `--image-generation-model <id>`), then poll `coauthor image status <id> --json`.
|
|
339
339
|
4. Check every finished image (the URLs are in `image status` and in `draft get --format markdown`):
|
|
340
340
|
- Charts and tables must match the article's numbers, and must not state figures the article deliberately leaves open.
|
|
341
341
|
- Screens of real products (for example a Google or Meta interface) must not be presented as genuine.
|
|
@@ -354,7 +354,7 @@ Images cost credits each time they are generated or edited, so check the brief a
|
|
|
354
354
|
|
|
355
355
|
### Other formats
|
|
356
356
|
|
|
357
|
-
X posts, LinkedIn, Facebook, and email newsletter versions: see `references/repurposing.md`. Carousel slideshows and short videos
|
|
357
|
+
X posts, LinkedIn, Facebook, and email newsletter versions: see `references/repurposing.md`. Carousel slideshows and short vertical videos: same file, under Slideshow and Video.
|
|
358
358
|
|
|
359
359
|
## references/publishing-and-export.md
|
|
360
360
|
|
|
@@ -394,11 +394,11 @@ See `references/images-and-social.md`. Publishing a thread posts immediately and
|
|
|
394
394
|
|
|
395
395
|
### If a live action's result is unclear
|
|
396
396
|
|
|
397
|
-
After a network error or an unclear result on an export or publish, do not run it again straight away.
|
|
397
|
+
After a network error or an unclear result on an export or publish, 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.
|
|
398
398
|
|
|
399
399
|
## references/repurposing.md
|
|
400
400
|
|
|
401
|
-
## Repurposing: social posts
|
|
401
|
+
## Repurposing: social posts, an email newsletter, slideshows, and video
|
|
402
402
|
|
|
403
403
|
Once the draft is final, CoAuthor turns it into distribution copy in the project's voice.
|
|
404
404
|
|
|
@@ -410,7 +410,7 @@ Once the draft is final, CoAuthor turns it into distribution copy in the project
|
|
|
410
410
|
| Facebook post | `facebook` | Variations with alternate hooks |
|
|
411
411
|
| Email newsletter | `email` | Variations with subject line, preheader, and body |
|
|
412
412
|
|
|
413
|
-
|
|
413
|
+
Carousel slideshows and short vertical videos have their own steps, because their illustrated panels are generated as images first (see Slideshow and Video below).
|
|
414
414
|
|
|
415
415
|
### Generate
|
|
416
416
|
|
|
@@ -444,6 +444,16 @@ coauthor repurpose save <id> --format x-thread --data '{"posts":[...]}' --json
|
|
|
444
444
|
|
|
445
445
|
Add `"destination_url": "https://..."` to point the posts at the published article. Keep the `{{POST_URL}}` placeholder in stored text; it is replaced with the destination URL on copy.
|
|
446
446
|
|
|
447
|
+
### Slideshow
|
|
448
|
+
|
|
449
|
+
A carousel of 1080x1350 slides (for LinkedIn or Instagram) with illustrated panels and a closing call-to-action slide.
|
|
450
|
+
|
|
451
|
+
1. `coauthor repurpose generate <id> --format slideshow [--cta save,follow] --json` writes the slides and queues one image per panel. Up to 4 endings: `save`, `follow`, `comment`, `share`, `read_more`, plus one `custom:<text>`; the default is `save`. Panel images cost image credits, which is why slideshows are not part of `--format all`.
|
|
452
|
+
2. `coauthor repurpose status <id> --format slideshow --wait --json` waits until no panel is still generating. If some failed, retry them with `coauthor image generate` or in the web app.
|
|
453
|
+
3. `coauthor repurpose download <id> --format slideshow [--variant <cta>] --out <dir>` renders the PNGs on the server and saves them as `slideshow/<cta>/slide-NN.png`, one folder per ending. `panels_not_ready` (409) means images are still generating or failed. Rendering again with no changes returns the same files.
|
|
454
|
+
|
|
455
|
+
The server draws the slides with the Inter font, so line breaks can differ slightly from the web app's own PNG download.
|
|
456
|
+
|
|
447
457
|
### Video
|
|
448
458
|
|
|
449
459
|
A short vertical video (1080x1920) of the article's key points, with illustrated panels and a closing call to action.
|
|
@@ -498,6 +508,8 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
498
508
|
| `workflow_token_mismatch`, `conflict` | The project moved on since you read it (for example someone used the web app). | Re-read the state with `coauthor workflow status <id> --json` and continue from there. |
|
|
499
509
|
| `insufficient_scope` | The token can't publish. | `coauthor auth login --with-publish`. |
|
|
500
510
|
| `wordpress_connection_required` | Several WordPress sites are connected. | Ask which one from `details.connections`, add `--connection-id`. |
|
|
511
|
+
| `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
|
|
512
|
+
| `request_timeout`, `network_error` | No answer from CoAuthor in time, or the connection failed. | For reads, retry. For exports and publishes, check `coauthor operation status <idempotency_key>` before retrying. |
|
|
501
513
|
|
|
502
514
|
### Sign-in
|
|
503
515
|
|