@clickminded/coauthor-cli 0.0.12 → 0.0.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -92,18 +92,27 @@ Work with the project:
92
92
  coauthor chat <project-id> --message "Refine the angle for this post" --json
93
93
  coauthor workflow status <project-id> --json
94
94
  coauthor workflow run <project-id> --target draft --wait --json
95
+ coauthor workflow run <project-id> --target draft --planning-model gpt-5.5 --writing-model gpt-5.4 --wait --json
95
96
  coauthor workflow resume <project-id> --target draft --wait --json
96
97
  coauthor credits <project-id> --json
97
98
  ```
98
99
 
100
+ List and save text model preferences:
101
+
102
+ ```sh
103
+ coauthor models list
104
+ coauthor models preferences show --json
105
+ coauthor models preferences set --planning-model gpt-5.5 --writing-model gpt-5.4 --json
106
+ ```
107
+
99
108
  Read or generate artifacts:
100
109
 
101
110
  ```sh
102
111
  coauthor contract show <project-id> --json
103
- coauthor outline generate <project-id> --json
104
- coauthor research-plan generate <project-id> --json
112
+ coauthor outline generate <project-id> --planning-model claude-opus-4-8 --json
113
+ coauthor research-plan generate <project-id> --planning-model gpt-5.5 --json
105
114
  coauthor research run <project-id> --wait --json
106
- coauthor draft generate <project-id> --wait --json
115
+ coauthor draft generate <project-id> --writing-model gpt-5.4 --wait --json
107
116
  coauthor draft get <project-id> --format markdown --json
108
117
  ```
109
118
 
@@ -112,7 +121,7 @@ Images and social content:
112
121
  ```sh
113
122
  coauthor image list <project-id> --json
114
123
  coauthor image generate <project-id> --placeholder-id <placeholder-id> --prompt "Image direction" --json
115
- coauthor thread generate <project-id> --json
124
+ coauthor thread generate <project-id> --writing-model gpt-5.4 --json
116
125
  ```
117
126
 
118
127
  Use `--json` when another tool or agent needs to parse command output. Use `--wait` when starting longer-running work and you want the command to wait for completion.
package/dist/commands.js CHANGED
@@ -46,6 +46,8 @@ export async function runCommand(input, context) {
46
46
  return runResourceCommand('exports', action, input, context.client);
47
47
  if (scope === 'operation')
48
48
  return runOperationCommand(action, input, context.client);
49
+ if (scope === 'models')
50
+ return runModelsCommand(action, input, context.client);
49
51
  if (scope === 'skills')
50
52
  return runSkillsCommand(action, input);
51
53
  if (scope === 'help')
@@ -209,22 +211,29 @@ async function runWorkflowCommand(action, input, context) {
209
211
  }
210
212
  if (action === 'resume') {
211
213
  const target = normalizeWorkflowWaitTarget(getString(input.values, 'target') ?? getString(input.values, 'stage')) ?? 'draft';
214
+ if (target === 'research' && (getString(input.values, 'planning-model') || getString(input.values, 'writing-model'))) {
215
+ throw new Error('workflow resume --target research does not support --planning-model or --writing-model.');
216
+ }
217
+ const modelOverrides = modelOverrideBody(input);
212
218
  if (target === 'research') {
213
219
  const data = await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/research/run`, body: {} });
214
220
  return getBoolean(input.values, 'wait') ? waitForResearch(client, projectId, data, context.baseUrl) : { ok: true, data };
215
221
  }
216
222
  const researchStatus = await client.request({ path: `projects/${encodeURIComponent(projectId)}/research/status` });
217
223
  if (extractNestedString(researchStatus, ['run', 'status']) === 'paused_requires_key') {
224
+ if (modelOverrides.writingModel && !getBoolean(input.values, 'wait')) {
225
+ throw new Error('workflow resume --writing-model after a paused research run requires --wait so the writing model can be applied when draft starts.');
226
+ }
218
227
  const data = await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/research/run`, body: {} });
219
- return getBoolean(input.values, 'wait') ? waitForWorkflowDraft(client, projectId, data, context.baseUrl) : { ok: true, data };
228
+ return getBoolean(input.values, 'wait') ? waitForWorkflowDraft(client, projectId, data, context.baseUrl, modelOverrides) : { ok: true, data };
220
229
  }
221
230
  const draftStatus = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/status` });
222
231
  if (getResponseString(draftStatus, 'phase') === 'paused_requires_key') {
223
- const data = await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/draft/generate`, body: {} });
232
+ const data = await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/draft/generate`, body: modelOverrides });
224
233
  return getBoolean(input.values, 'wait') ? waitForDraft(client, projectId, data, context.baseUrl) : { ok: true, data };
225
234
  }
226
- const data = await client.request({ method: 'POST', path: `${projectPath}/run`, body: { target } });
227
- return getBoolean(input.values, 'wait') ? waitForWorkflowDraft(client, projectId, data, context.baseUrl) : { ok: true, data };
235
+ const data = await client.request({ method: 'POST', path: `${projectPath}/run`, body: { target, ...modelOverrides } });
236
+ return getBoolean(input.values, 'wait') ? waitForWorkflowDraft(client, projectId, data, context.baseUrl, modelOverrides) : { ok: true, data };
228
237
  }
229
238
  if (action === 'advance' || action === 'run' || action === 'rewind' || action === 'approve') {
230
239
  const body = withNamedOptions(parseJsonOption(input.values), input.values, [
@@ -234,6 +243,7 @@ async function runWorkflowCommand(action, input, context) {
234
243
  'reason',
235
244
  'briefing-mode',
236
245
  'max-brief-questions',
246
+ ...(action === 'advance' || action === 'run' ? ['planning-model', 'writing-model'] : []),
237
247
  ]);
238
248
  if (getBoolean(input.values, 'require-brief-review'))
239
249
  body.requireBriefReview = true;
@@ -252,7 +262,7 @@ async function runWorkflowCommand(action, input, context) {
252
262
  if (target === 'research')
253
263
  return waitForResearch(client, projectId, data, context.baseUrl);
254
264
  if (target === 'draft')
255
- return waitForWorkflowDraft(client, projectId, data, context.baseUrl);
265
+ return waitForWorkflowDraft(client, projectId, data, context.baseUrl, modelOverrideBody(input));
256
266
  }
257
267
  return { ok: true, data };
258
268
  }
@@ -263,6 +273,65 @@ async function runCreditsCommand(input, client) {
263
273
  const data = await client.request({ path: `projects/${encodeURIComponent(projectId)}/credits` });
264
274
  return { ok: true, data };
265
275
  }
276
+ async function runModelsCommand(action, input, client) {
277
+ if (!action || action === 'list') {
278
+ const data = await client.request({ path: 'models' });
279
+ return { ok: true, message: formatModelsList(data), data };
280
+ }
281
+ if (action === 'preferences') {
282
+ const subaction = input.command[2] ?? 'show';
283
+ if (subaction === 'show') {
284
+ const data = await client.request({ path: 'models/preferences' });
285
+ return { ok: true, data };
286
+ }
287
+ if (subaction === 'set') {
288
+ const body = modelOverrideBody(input);
289
+ if (!body.planningModel && !body.writingModel) {
290
+ throw new Error('Usage: coauthor models preferences set [--planning-model <id>] [--writing-model <id>]');
291
+ }
292
+ const data = await client.request({ method: 'POST', path: 'models/preferences', body });
293
+ return { ok: true, message: 'Model preferences updated', data };
294
+ }
295
+ }
296
+ throw new Error('Usage: coauthor models <list|preferences show|preferences set>');
297
+ }
298
+ function modelOverrideBody(input) {
299
+ const body = {};
300
+ const planningModel = getString(input.values, 'planning-model');
301
+ const writingModel = getString(input.values, 'writing-model');
302
+ if (planningModel)
303
+ body.planningModel = planningModel;
304
+ if (writingModel)
305
+ body.writingModel = writingModel;
306
+ return body;
307
+ }
308
+ function formatModelsList(data) {
309
+ if (!data || typeof data !== 'object' || Array.isArray(data))
310
+ return '';
311
+ const models = data.models;
312
+ if (!models || typeof models !== 'object' || Array.isArray(models))
313
+ return '';
314
+ const formatGroup = (label, value) => {
315
+ const entries = Array.isArray(value) ? value : [];
316
+ return [
317
+ label,
318
+ ...entries.map((entry) => {
319
+ if (!entry || typeof entry !== 'object' || Array.isArray(entry))
320
+ return null;
321
+ const id = entry.id;
322
+ const name = entry.label;
323
+ if (typeof id !== 'string')
324
+ return null;
325
+ return `- ${id}${typeof name === 'string' ? ` ${name}` : ''}`;
326
+ }).filter((line) => Boolean(line)),
327
+ ].join('\n');
328
+ };
329
+ return [
330
+ formatGroup('Planning models (--planning-model)', models.planning),
331
+ '',
332
+ formatGroup('Writing models (--writing-model)', models.writing),
333
+ ].join('\n');
334
+ }
266
335
  async function runArtifactCommand(artifact, action, input, client) {
267
336
  const projectId = requireProjectId(input);
268
337
  const basePath = `projects/${encodeURIComponent(projectId)}/${artifact}`;
@@ -273,7 +342,10 @@ async function runArtifactCommand(artifact, action, input, client) {
273
342
  if (action === 'generate' || action === 'save' || action === 'approve') {
274
343
  const body = action === 'approve'
275
344
  ? await buildArtifactApproveBody(artifact, input, client, basePath)
276
- : withNamedOptions(parseJsonOption(input.values), input.values, ['execution-token']);
345
+ : withNamedOptions(parseJsonOption(input.values), input.values, [
346
+ 'execution-token',
347
+ ...(action === 'generate' && (artifact === 'outline' || artifact === 'research-plan') ? ['planning-model'] : []),
348
+ ]);
277
349
  const path = action === 'save' ? basePath : `${basePath}/${action}`;
278
350
  const data = await client.request({ method: 'POST', path, body });
279
351
  return { ok: true, data };
@@ -305,7 +377,7 @@ async function runDraftCommand(action, input, context) {
305
377
  const projectId = requireProjectId(input);
306
378
  const basePath = `projects/${encodeURIComponent(projectId)}/draft`;
307
379
  if (action === 'generate') {
308
- const body = withNamedOptions(parseJsonOption(input.values), input.values, ['execution-token']);
380
+ const body = withNamedOptions(parseJsonOption(input.values), input.values, ['execution-token', 'writing-model']);
309
381
  const data = await client.request({ method: 'POST', path: `${basePath}/generate`, body });
310
382
  if (getBoolean(input.values, 'wait')) {
311
383
  return waitForDraft(client, projectId, data, context.baseUrl);
@@ -386,6 +458,7 @@ async function runResourceCommand(resource, action, input, client) {
386
458
  'execution-token',
387
459
  'grounding-mode',
388
460
  'image-generation-model',
461
+ ...(resource === 'threads' && action === 'generate' ? ['writing-model'] : []),
389
462
  'edit-prompt',
390
463
  ]);
391
464
  const path = action === 'create' && resource !== 'threads' ? basePath : `${basePath}/${action}`;
@@ -676,7 +749,7 @@ async function waitForDraft(client, projectId, initialData, baseUrl) {
676
749
  }
677
750
  return waitTimedOutResult(projectId, 'draft', initialData, null, latest);
678
751
  }
679
- async function waitForWorkflowDraft(client, projectId, initialData, baseUrl) {
752
+ async function waitForWorkflowDraft(client, projectId, initialData, baseUrl, modelOverrides = {}) {
680
753
  const deadline = Date.now() + waitTimeoutMs(40 * 60_000);
681
754
  const pollMs = waitPollMs();
682
755
  let latestDraft = initialData;
@@ -733,7 +806,7 @@ async function waitForWorkflowDraft(client, projectId, initialData, baseUrl) {
733
806
  draftGenerate = await client.request({
734
807
  method: 'POST',
735
808
  path: `projects/${encodeURIComponent(projectId)}/draft/generate`,
736
- body: {},
809
+ body: modelOverrides.writingModel ? { writingModel: modelOverrides.writingModel } : {},
737
810
  });
738
811
  }
739
812
  catch (error) {
@@ -1003,6 +1076,7 @@ export function helpResult(command = []) {
1003
1076
  ' export blog|clickminded',
1004
1077
  ' operation list|show|status',
1005
1078
  ' credits',
1079
+ ' models list|preferences show|preferences set',
1006
1080
  ' skills list|install',
1007
1081
  ' skills install supports codex|claude|cursor|agents|all',
1008
1082
  ].join('\n'),
@@ -1017,20 +1091,30 @@ function commandHelp(command) {
1017
1091
  'Creates a project. When --topic or --audience is provided, CoAuthor seeds the saved contract so workflow briefing review can use that context.',
1018
1092
  ].join('\n'),
1019
1093
  'workflow run': [
1020
- 'Usage: coauthor workflow run <project-id> --target <outline|research|draft> [--wait] [--briefing-mode auto|strict|off] [--json]',
1094
+ 'Usage: coauthor workflow run <project-id> --target <outline|research|draft> [--planning-model <id>] [--writing-model <id>] [--wait] [--briefing-mode auto|strict|off] [--json]',
1021
1095
  '',
1022
1096
  '--wait blocks until the requested target completes, pauses for a key, fails, reports stale research, or times out.',
1023
1097
  ].join('\n'),
1024
1098
  'workflow resume': [
1025
- 'Usage: coauthor workflow resume <project-id> [--target <research|draft>] [--wait] [--json]',
1099
+ 'Usage: coauthor workflow resume <project-id> [--target <research|draft>] [--planning-model <id>] [--writing-model <id>] [--wait] [--json]',
1026
1100
  '',
1027
1101
  'Use after an interruption, timeout, or requires_key pause. For draft targets, --wait continues through research and draft generation.',
1028
1102
  ].join('\n'),
1029
1103
  'draft generate': [
1030
- 'Usage: coauthor draft generate <project-id> [--wait] [--json]',
1104
+ 'Usage: coauthor draft generate <project-id> [--writing-model <id>] [--wait] [--json]',
1031
1105
  '',
1032
1106
  'Requires project_state "research_structured". If research is still running or structuring, inspect the returned status and next commands.',
1033
1107
  ].join('\n'),
1108
+ 'models list': [
1109
+ 'Usage: coauthor models list [--json]',
1110
+ '',
1111
+ 'Lists user-visible planning and writing model IDs for --planning-model and --writing-model.',
1112
+ ].join('\n'),
1113
+ 'models preferences': [
1114
+ 'Usage: coauthor models preferences <show|set> [--planning-model <id>] [--writing-model <id>] [--json]',
1115
+ '',
1116
+ 'Shows or updates saved primary planning/writing model preferences while preserving fallback order.',
1117
+ ].join('\n'),
1034
1118
  'draft get': [
1035
1119
  'Usage: coauthor draft get <project-id> [--format json|markdown|html|text] [--json]',
1036
1120
  '',
@@ -1046,6 +1130,11 @@ function commandHelp(command) {
1046
1130
  '',
1047
1131
  'Image generation requires an image placeholder from coauthor image list. Draft generation creates placeholders.',
1048
1132
  ].join('\n'),
1133
+ 'thread generate': [
1134
+ 'Usage: coauthor thread generate <project-id> [--writing-model <id>] [--json]',
1135
+ '',
1136
+ 'Generates a social thread from the saved draft.',
1137
+ ].join('\n'),
1049
1138
  };
1050
1139
  return help[key] ?? null;
1051
1140
  }
package/dist/parser.js CHANGED
@@ -54,6 +54,8 @@ export function parseCliArgs(argv) {
54
54
  limit: { type: 'string' },
55
55
  cursor: { type: 'string' },
56
56
  'execution-token': { type: 'string' },
57
+ 'planning-model': { type: 'string' },
58
+ 'writing-model': { type: 'string' },
57
59
  },
58
60
  });
59
61
  const positionals = parsed.positionals;
@@ -104,6 +106,10 @@ function commandLength(positionals) {
104
106
  return second && ['show', 'list'].includes(second) ? 2 : 1;
105
107
  if (first === 'skills')
106
108
  return second && ['list', 'install'].includes(second) ? 2 : 1;
109
+ if (first === 'models')
110
+ return second && ['list', 'preferences'].includes(second)
111
+ ? (second === 'preferences' && positionals[2] && ['show', 'set'].includes(positionals[2]) ? 3 : 2)
112
+ : 1;
107
113
  if (first === 'workflow')
108
114
  return second ? 2 : 1;
109
115
  if (first === 'credits')
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.12",
3
+ "version": "0.0.13",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -22,6 +22,8 @@ This skill guides agent use of the CoAuthor CLI.
22
22
  - `coauthor workflow run <project-id> --target draft --wait` should not be treated as complete until the CLI reports draft completion, a key pause, terminal failure, `research_running_stale`, or `timed_out`.
23
23
  - For images, run `coauthor image list <project-id> --json` and pass an existing placeholder with `coauthor image generate <project-id> --placeholder-id <placeholder-id> --json`. Draft generation creates placeholders.
24
24
  - Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
25
+ - Use `coauthor models list` to see user-visible planning and writing models. Use `--planning-model <id>` for outline/research-plan/workflow planning overrides and `--writing-model <id>` for draft/thread/workflow writing overrides; do not use a global `--model`.
26
+ - Use `coauthor models preferences show|set` to inspect or update saved planning/writing preferences. Internal structuring models are not exposed through the CLI.
25
27
  - After a timeout, interruption, network error, or unclear result, check operation status before retrying.
26
28
  - `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
27
29
 
@@ -22,6 +22,8 @@ This skill guides agent use of the CoAuthor CLI.
22
22
  - `coauthor workflow run <project-id> --target draft --wait` should not be treated as complete until the CLI reports draft completion, a key pause, terminal failure, `research_running_stale`, or `timed_out`.
23
23
  - For images, run `coauthor image list <project-id> --json` and pass an existing placeholder with `coauthor image generate <project-id> --placeholder-id <placeholder-id> --json`. Draft generation creates placeholders.
24
24
  - Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
25
+ - Use `coauthor models list` to see user-visible planning and writing models. Use `--planning-model <id>` for outline/research-plan/workflow planning overrides and `--writing-model <id>` for draft/thread/workflow writing overrides; do not use a global `--model`.
26
+ - Use `coauthor models preferences show|set` to inspect or update saved planning/writing preferences. Internal structuring models are not exposed through the CLI.
25
27
  - After a timeout, interruption, network error, or unclear result, check operation status before retrying.
26
28
  - `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
27
29
 
@@ -22,6 +22,8 @@ This skill guides agent use of the CoAuthor CLI.
22
22
  - `coauthor workflow run <project-id> --target draft --wait` should not be treated as complete until the CLI reports draft completion, a key pause, terminal failure, `research_running_stale`, or `timed_out`.
23
23
  - For images, run `coauthor image list <project-id> --json` and pass an existing placeholder with `coauthor image generate <project-id> --placeholder-id <placeholder-id> --json`. Draft generation creates placeholders.
24
24
  - Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
25
+ - Use `coauthor models list` to see user-visible planning and writing models. Use `--planning-model <id>` for outline/research-plan/workflow planning overrides and `--writing-model <id>` for draft/thread/workflow writing overrides; do not use a global `--model`.
26
+ - Use `coauthor models preferences show|set` to inspect or update saved planning/writing preferences. Internal structuring models are not exposed through the CLI.
25
27
  - After a timeout, interruption, network error, or unclear result, check operation status before retrying.
26
28
  - `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
27
29
 
@@ -19,6 +19,8 @@ alwaysApply: true
19
19
  - `coauthor workflow run <project-id> --target draft --wait` should not be treated as complete until the CLI reports draft completion, a key pause, terminal failure, `research_running_stale`, or `timed_out`.
20
20
  - For images, run `coauthor image list <project-id> --json` and pass an existing placeholder with `coauthor image generate <project-id> --placeholder-id <placeholder-id> --json`. Draft generation creates placeholders.
21
21
  - Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
22
+ - Use `coauthor models list` to see user-visible planning and writing models. Use `--planning-model <id>` for outline/research-plan/workflow planning overrides and `--writing-model <id>` for draft/thread/workflow writing overrides; do not use a global `--model`.
23
+ - Use `coauthor models preferences show|set` to inspect or update saved planning/writing preferences. Internal structuring models are not exposed through the CLI.
22
24
  - After timeout, interruption, network error, or ambiguous output, check operation status before retrying or reporting success.
23
25
  - `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
24
26
  - Never print tokens, service-role keys, cookies, or authorization headers.