@clickminded/coauthor-cli 0.0.22 → 0.0.24
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 +61 -175
- package/dist/commands.js +377 -89
- package/dist/parser.js +7 -0
- package/package.json +1 -1
- package/scripts/build-cursor-rule.mjs +58 -0
- package/scripts/postinstall.mjs +60 -48
- package/scripts/verify-skill-sync.mjs +50 -42
- package/skills/coauthor/SKILL.md +63 -0
- package/skills/coauthor/references/brief-and-contract.md +151 -0
- package/skills/coauthor/references/credits-and-plans.md +26 -0
- package/skills/coauthor/references/editing-drafts.md +59 -0
- package/skills/coauthor/references/images-and-social.md +28 -0
- package/skills/coauthor/references/publishing-and-export.md +37 -0
- package/skills/coauthor/references/troubleshooting.md +48 -0
- package/skills/cursor/coauthor-cli.mdc +326 -139
- package/skills/agents/SKILL.md +0 -274
- package/skills/claude/SKILL.md +0 -274
- package/skills/codex/SKILL.md +0 -274
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Images and social posts
|
|
2
|
+
|
|
3
|
+
## Article images
|
|
4
|
+
|
|
5
|
+
Draft generation plans image placeholders, including a featured image (`is_featured: true`) when one fits. It does not generate them. CoAuthor decides how many images a piece gets, sometimes only the featured image, and the CLI cannot add more placeholders. If the user expected several images, tell them more can be added in the web app editor.
|
|
6
|
+
|
|
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
|
+
2. Generate each one: `coauthor image generate <id> --placeholder-id <id UUID> --json`. Use the `id` UUID; the descriptive `placeholder_id` string is not accepted. Optional: `--grounding-mode <mode>`, `--image-generation-model <id>`.
|
|
9
|
+
3. Generation is asynchronous. Poll `coauthor image status <id> --json` every 15–30 seconds until no placeholder's latest image is `generating`. Each takes about 20 seconds.
|
|
10
|
+
4. Check every finished image (the URLs are in `image status` and in `draft get --format markdown`):
|
|
11
|
+
- Charts and tables must match the article's numbers, and must not state figures the article deliberately leaves open.
|
|
12
|
+
- Screens of real products (for example a Google or Meta interface) must not be presented as genuine.
|
|
13
|
+
- Prices, dates, and text inside the image must match the article.
|
|
14
|
+
5. Fix an image with an instruction: `coauthor image edit <id> --placeholder-id <id UUID> --edit-prompt "Remove the price tag; keep everything else." --json`, then poll `image status` again. To drop an image entirely, remove its `imagePlaceholder` node with a direct draft edit (`references/editing-drafts.md`).
|
|
15
|
+
6. Rewrite the SEO metadata for every generated image: `coauthor image metadata <id> <placeholder id UUID> --alt-text "..." --file-slug "..." --description "..." --json`. This is required, not polish: the stored alt text was written from the plan before the image existed and often describes things that aren't in the picture. Alt text must describe what is actually visible.
|
|
16
|
+
|
|
17
|
+
Images cost credits each time they are generated or edited, so check the brief and placeholder purpose before regenerating.
|
|
18
|
+
|
|
19
|
+
## X thread
|
|
20
|
+
|
|
21
|
+
1. `coauthor thread generate <id> --json` writes a thread from the saved draft (optional `--writing-model <id>`).
|
|
22
|
+
2. `coauthor thread show <id> --json` returns `data.thread.posts` (`[{ "id", "text", "image_placeholder_id" }]`) and the user's connected X accounts in `data.social_accounts`.
|
|
23
|
+
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).
|
|
24
|
+
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`.
|
|
25
|
+
|
|
26
|
+
## Other formats
|
|
27
|
+
|
|
28
|
+
LinkedIn, Facebook, and email newsletter versions, carousel slideshows, and short videos are generated in the CoAuthor web app (open the project and use Promote). The CLI cannot create them yet.
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Publishing and export
|
|
2
|
+
|
|
3
|
+
## Get the finished draft
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
coauthor draft get <id> --format markdown --json # data.markdown, images as markdown image links
|
|
7
|
+
coauthor draft get <id> --format html --json # data.html, images as <img> tags
|
|
8
|
+
coauthor draft get <id> --format text --json # data.text, plain text with image URLs
|
|
9
|
+
coauthor draft get <id> --format json --json # data.content, the editor document (for edits)
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
The markdown and HTML have no H1: they start with the featured image (once generated) and then the first section. Add the title yourself from `coauthor project show <id> --json` (`data.project.title`) when you hand over a file. Images appear only after they have been generated, and their URLs are public, so the markdown can be pasted anywhere.
|
|
13
|
+
|
|
14
|
+
## Share link (public)
|
|
15
|
+
|
|
16
|
+
`coauthor share <id> --json` returns `data.share_url`, a public read-only page anyone with the link can open. Create one only when the user asks for a link. Calling it again returns the same link.
|
|
17
|
+
|
|
18
|
+
## WordPress
|
|
19
|
+
|
|
20
|
+
Export creates a **draft post** in the user's WordPress site (it is not published), with images and SEO metadata.
|
|
21
|
+
|
|
22
|
+
1. The token needs publish permission. If an export fails with `insufficient_scope`, have the user run `coauthor auth login --with-publish` (in the background with `--no-browser`; they approve in the browser).
|
|
23
|
+
2. With the user's yes:
|
|
24
|
+
`coauthor export wordpress <id> --yes --slug <url-slug> --json`
|
|
25
|
+
3. If they have several WordPress sites connected, the error `wordpress_connection_required` lists them in `details.connections` (`id`, `label`, `site_base_url`). Ask which one, then add `--connection-id <id>`.
|
|
26
|
+
4. `wordpress_not_connected` means no site is connected yet. The user connects one in CoAuthor's settings (Publishing).
|
|
27
|
+
5. Give the user `wordpress_edit_url` from the response (also `wordpress_link`) so they can review and publish the post in WordPress.
|
|
28
|
+
|
|
29
|
+
`coauthor export list <id> --json` shows past exports.
|
|
30
|
+
|
|
31
|
+
## X thread
|
|
32
|
+
|
|
33
|
+
See `references/images-and-social.md`. Publishing a thread posts immediately and needs the user's yes.
|
|
34
|
+
|
|
35
|
+
## If a live action's result is unclear
|
|
36
|
+
|
|
37
|
+
After a network error or an unclear result on an export or publish, do not run it again straight away. Check `coauthor operation list --json` for the operation and its status first, then decide.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Troubleshooting
|
|
2
|
+
|
|
3
|
+
Every failure prints JSON on stderr with `ok: false`, `error` (a readable message), `code`, `http_status`, and often `details` with the current state and next commands. Paused or blocked work is saved; nothing needs to be redone from scratch.
|
|
4
|
+
|
|
5
|
+
## Statuses and codes
|
|
6
|
+
|
|
7
|
+
| Status or code | Meaning | What to do |
|
|
8
|
+
| --- | --- | --- |
|
|
9
|
+
| `needs_clarification` | The brief is too thin to outline well. | Answer `data.clarification_questions` from your context (ask the user only what you can't know), update the contract, run again. |
|
|
10
|
+
| `timed_out` | The wait window ended; the work is still running on CoAuthor's side. | Run the resume command in `data.next_commands`, usually `coauthor workflow resume <id> --target draft --wait --json`. |
|
|
11
|
+
| `still_running` | Same, for a draft revision. | `coauthor draft revision show <id> <revision-id> --json`. |
|
|
12
|
+
| `research_structuring` | Research finished and is being organized for drafting. Normal. | Keep waiting or resume toward draft. Don't rewind. |
|
|
13
|
+
| `research_running_stale` | Research progress has not changed for 30+ minutes. | Check `coauthor research status <id> --json` a few minutes apart and look at `coauthor research structured <id> --json`. Rewinding (`coauthor workflow rewind <id> --target research --json`) discards the research done so far and costs credits to redo, so ask the user first. |
|
|
14
|
+
| `research_run_state_mismatch` | Research run and project state disagree. | Report it and use the `recovery_commands` in the output. |
|
|
15
|
+
| `blocked_by_research` | A draft was requested while research is still running. | Use the `recovery_commands`; usually just resume toward draft. |
|
|
16
|
+
| `credits_exhausted` | The plan's credits for this period are used up. Work is paused and saved. | Tell the user `reset_at`, `used`, and `remaining`. Resume with `coauthor workflow resume <id> --wait --json` after the reset. See `references/credits-and-plans.md`. |
|
|
17
|
+
| `requires_key` | Included credits are used up and the plan can continue with the user's own AI provider key. | The user adds a key in CoAuthor's AI settings (`settings_url`); never ask for it in chat. Then run `resume_command`. |
|
|
18
|
+
| `byok_not_allowed` | The plan can't use provider keys. | Wait for the credit reset, or the user upgrades in CoAuthor. |
|
|
19
|
+
| `coauthor_access_required` | No active CoAuthor subscription on this account. | Tell the user. `coauthor auth status` still works. |
|
|
20
|
+
| `entitlement_sync_unavailable` | Subscription status couldn't be checked right now. | Don't retry in a loop. Try again in a few minutes. |
|
|
21
|
+
| `draft_exists` | `brief answer` on a project that already has a draft. | Edit the draft instead. `--force` only if the user wants to restart from the brief (the draft is regenerated). |
|
|
22
|
+
| `downstream_exists` | `outline revise` or `research-plan revise` after research ran. | Same: edit the draft, or `--force` to restart from that stage with the user's OK. |
|
|
23
|
+
| `revision_invalid` | CoAuthor's revision referenced sections that don't exist. | Run `revise` again with feedback that names sections by their current headings. |
|
|
24
|
+
| `stale_draft` | The draft changed after you read it. | Re-read with `draft get`, reapply your edit, save. |
|
|
25
|
+
| `user_recently_editing` | The user saved in the browser in the last 90 seconds. | Wait, or ask them. `--force` only with their OK. |
|
|
26
|
+
| `review_pending`, `document_locked` | An AI review or edit is in progress in the editor. | Wait, or apply or discard it. |
|
|
27
|
+
| `revision_pending` | Another draft revision is open. | Apply or discard it (`details.revision_id`). |
|
|
28
|
+
| `revise_unavailable` | Revise by instruction isn't available on this account. | Use a direct edit (`references/editing-drafts.md`). |
|
|
29
|
+
| `invalid_document` | `draft save` content isn't an editor document. | Send the edited `data.content` from `draft get --format json`, never markdown. |
|
|
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
|
+
| `insufficient_scope` | The token can't publish. | `coauthor auth login --with-publish`. |
|
|
32
|
+
| `wordpress_connection_required` | Several WordPress sites are connected. | Ask which one from `details.connections`, add `--connection-id`. |
|
|
33
|
+
|
|
34
|
+
## Sign-in
|
|
35
|
+
|
|
36
|
+
- `Missing bearer token` or HTTP 401: run `coauthor auth login --no-browser` in the background and give the user the printed URL and code. The login waits up to 10 minutes for approval.
|
|
37
|
+
- `coauthor auth status --json` shows which account and permissions the saved token has.
|
|
38
|
+
- `coauthor auth logout` revokes the token on the server, then removes it locally.
|
|
39
|
+
|
|
40
|
+
## Waiting
|
|
41
|
+
|
|
42
|
+
- `COAUTHOR_CLI_WAIT_TIMEOUT_MS` caps any `--wait` (use `540000` to stay under a 10-minute shell limit).
|
|
43
|
+
- `COAUTHOR_CLI_WAIT_POLL_MS` sets how often `--wait` checks (default 3000).
|
|
44
|
+
- `COAUTHOR_CLI_RESEARCH_STALE_MS` sets how long research progress may stand still before `research_running_stale` (default 30 minutes).
|
|
45
|
+
|
|
46
|
+
## Before retrying anything
|
|
47
|
+
|
|
48
|
+
Check state first: `coauthor workflow status <id> --json`, `coauthor research status <id> --json`, `coauthor draft status <id> --json`, and for exports `coauthor operation list --json`. Starting a step twice can spend credits twice.
|