@clickminded/coauthor-cli 0.0.21 → 0.0.23
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 +278 -87
- package/dist/parser.js +1 -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 +62 -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 +45 -0
- package/skills/cursor/coauthor-cli.mdc +322 -139
- package/skills/agents/SKILL.md +0 -274
- package/skills/claude/SKILL.md +0 -274
- package/skills/codex/SKILL.md +0 -274
package/README.md
CHANGED
|
@@ -1,224 +1,110 @@
|
|
|
1
1
|
# CoAuthor CLI
|
|
2
2
|
|
|
3
|
-
`@clickminded/coauthor-cli` installs the `coauthor` command for
|
|
4
|
-
|
|
5
|
-
The CLI connects to CoAuthor at `https://tools.clickminded.com/coauthor`. Your projects stay private and every project command requires browser/device login.
|
|
3
|
+
`@clickminded/coauthor-cli` installs the `coauthor` command and a CoAuthor skill for AI agents such as Claude Code, Codex, and Cursor. Your agent can then research, outline, draft, illustrate, revise, and export articles with [CoAuthor](https://tools.clickminded.com/coauthor), acting as your editor along the way.
|
|
6
4
|
|
|
7
5
|
## Requirements
|
|
8
6
|
|
|
9
7
|
- Node.js 20 or newer.
|
|
10
|
-
- A CoAuthor
|
|
11
|
-
|
|
12
|
-
## Install
|
|
8
|
+
- A CoAuthor subscription.
|
|
13
9
|
|
|
14
|
-
|
|
10
|
+
## Set up
|
|
15
11
|
|
|
16
12
|
```sh
|
|
17
13
|
npm install -g @clickminded/coauthor-cli
|
|
18
|
-
```
|
|
19
|
-
|
|
20
|
-
Or run without a global install:
|
|
21
|
-
|
|
22
|
-
```sh
|
|
23
|
-
npx @clickminded/coauthor-cli help
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
## Sign In
|
|
27
|
-
|
|
28
|
-
Start browser/device login:
|
|
29
|
-
|
|
30
|
-
```sh
|
|
31
14
|
coauthor auth login
|
|
15
|
+
coauthor skills install
|
|
32
16
|
```
|
|
33
17
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
```sh
|
|
39
|
-
coauthor auth status --json
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
-
Log out and revoke the local token:
|
|
18
|
+
1. `auth login` opens a browser page to approve the CLI for your CoAuthor account. On a remote machine or inside an agent, use `coauthor auth login --no-browser` and open the printed URL yourself.
|
|
19
|
+
2. `skills install` installs the CoAuthor skill for the agents on this machine (Claude Code and Codex), in your user folder, so it works in every project.
|
|
20
|
+
3. Start a new agent session and ask: *"Use CoAuthor to write a blog post about …"*.
|
|
43
21
|
|
|
44
|
-
|
|
45
|
-
coauthor auth logout
|
|
46
|
-
```
|
|
22
|
+
If `npm install -g` fails with a permissions error, use a Node version manager (nvm, fnm, volta) or run commands with `npx @clickminded/coauthor-cli <command>`.
|
|
47
23
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
To deliberately remove only the local credential while leaving the remote token potentially active:
|
|
24
|
+
## The skill
|
|
51
25
|
|
|
52
26
|
```sh
|
|
53
|
-
coauthor
|
|
27
|
+
coauthor skills install # agents detected on this machine (Claude Code, Codex), per user
|
|
28
|
+
coauthor skills install claude # one agent: claude, codex, agents, cursor
|
|
29
|
+
coauthor skills install all # claude, codex, and agents
|
|
30
|
+
coauthor skills install claude --scope project # into the current repo instead of your user folder
|
|
31
|
+
coauthor skills list # where each one is and whether it is current
|
|
54
32
|
```
|
|
55
33
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
34
|
+
| Agent | Installed at |
|
|
35
|
+
| --- | --- |
|
|
36
|
+
| Claude Code | `~/.claude/skills/coauthor/` (`--scope project`: `./.claude/skills/coauthor/`) |
|
|
37
|
+
| Codex | `~/.codex/skills/coauthor/` |
|
|
38
|
+
| Agents (`.agents/skills`) | `~/.agents/skills/coauthor/` (`--scope project`: `./.agents/skills/coauthor/`) |
|
|
39
|
+
| Cursor | `./.cursor/rules/coauthor-cli.mdc` (per project) |
|
|
59
40
|
|
|
60
|
-
|
|
41
|
+
Updating the CLI updates installed skills automatically, unless you edited them; then they are left alone until you run `coauthor skills install <agent> --force`. `--dry-run` previews an install.
|
|
61
42
|
|
|
62
|
-
|
|
43
|
+
## What your agent does with it
|
|
63
44
|
|
|
64
|
-
|
|
65
|
-
coauthor skills install all
|
|
66
|
-
```
|
|
67
|
-
|
|
68
|
-
Install one target at a time:
|
|
45
|
+
A typical piece:
|
|
69
46
|
|
|
70
47
|
```sh
|
|
71
|
-
coauthor
|
|
72
|
-
coauthor
|
|
73
|
-
coauthor
|
|
74
|
-
coauthor
|
|
48
|
+
coauthor project create --title "Post title" --contract @brief.json --json
|
|
49
|
+
coauthor workflow run <id> --target contract --briefing-mode strict --json # CoAuthor questions the brief
|
|
50
|
+
coauthor outline generate <id> --json # review, then:
|
|
51
|
+
coauthor outline approve <id> --json
|
|
52
|
+
coauthor research-plan generate <id> --json # review, then:
|
|
53
|
+
coauthor research-plan approve <id> --json
|
|
54
|
+
coauthor workflow run <id> --target draft --wait --json # research + draft
|
|
55
|
+
coauthor draft get <id> --format markdown --json
|
|
75
56
|
```
|
|
76
57
|
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
- Codex: `~/.codex/skills/coauthor/SKILL.md`
|
|
80
|
-
- Claude: `./.claude/skills/coauthor/SKILL.md`
|
|
81
|
-
- Cursor: `./.cursor/rules/coauthor-cli.mdc`
|
|
82
|
-
- Agents: `./.agents/skills/coauthor/SKILL.md`
|
|
83
|
-
|
|
84
|
-
Use `--dry-run` to preview, `--force` to overwrite existing files, and `--cwd <path>` to install project-local Claude, Cursor, or Agents skills into a specific project.
|
|
85
|
-
|
|
86
|
-
Skill installs are recorded in `~/.config/coauthor/managed-skills.json`. Future package updates automatically refresh recorded skill files when they still match the previously installed template. If you edit a skill file by hand, the auto-update leaves it alone until you run `coauthor skills install <target> --force`.
|
|
87
|
-
|
|
88
|
-
## Common Commands
|
|
89
|
-
|
|
90
|
-
Create and inspect projects:
|
|
58
|
+
Editing:
|
|
91
59
|
|
|
92
60
|
```sh
|
|
93
|
-
coauthor
|
|
94
|
-
coauthor
|
|
95
|
-
coauthor
|
|
96
|
-
coauthor project show <project-id> --json
|
|
97
|
-
coauthor workspace show <project-id> --json
|
|
61
|
+
coauthor draft revise <id> --instruction "Cut the intro to two sentences" --wait --json
|
|
62
|
+
coauthor draft revision apply <id> <revision-id> --json # or --accept/--reject <group ids>, or discard
|
|
63
|
+
coauthor draft save <id> --data @payload.json --json # exact edits to the editor document
|
|
98
64
|
```
|
|
99
65
|
|
|
100
|
-
|
|
66
|
+
Images, social, and export:
|
|
101
67
|
|
|
102
68
|
```sh
|
|
103
|
-
coauthor
|
|
104
|
-
coauthor
|
|
105
|
-
coauthor
|
|
106
|
-
coauthor
|
|
107
|
-
coauthor
|
|
108
|
-
coauthor
|
|
109
|
-
coauthor
|
|
69
|
+
coauthor image list <id> --json
|
|
70
|
+
coauthor image generate <id> --placeholder-id <placeholder id> --json
|
|
71
|
+
coauthor image status <id> --json
|
|
72
|
+
coauthor thread generate <id> --json
|
|
73
|
+
coauthor share <id> --json # public read-only link
|
|
74
|
+
coauthor export wordpress <id> --yes --slug <slug> --json # creates a WordPress draft post
|
|
75
|
+
coauthor credits <id> --json
|
|
110
76
|
```
|
|
111
77
|
|
|
112
|
-
|
|
78
|
+
Run `coauthor --help` or `coauthor <command> --help` for every command and option. `--json` gives machine-readable output, `--wait` waits for long-running work, and JSON options such as `--data` and `--contract` accept `@file.json` (or `@-` for stdin).
|
|
113
79
|
|
|
114
|
-
|
|
115
|
-
coauthor models list
|
|
116
|
-
coauthor models preferences show --json
|
|
117
|
-
coauthor models preferences set --planning-model gpt-5.6-sol --writing-model gpt-5.6-terra --json
|
|
118
|
-
```
|
|
80
|
+
## Live actions
|
|
119
81
|
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
Read or generate artifacts:
|
|
123
|
-
|
|
124
|
-
```sh
|
|
125
|
-
coauthor contract show <project-id> --json
|
|
126
|
-
coauthor outline generate <project-id> --planning-model claude-opus-4-8 --json
|
|
127
|
-
coauthor research-plan generate <project-id> --planning-model gpt-5.6-sol --json
|
|
128
|
-
coauthor research run <project-id> --wait --json
|
|
129
|
-
coauthor draft generate <project-id> --writing-model gpt-5.6-terra --wait --json
|
|
130
|
-
coauthor draft get <project-id> --format markdown --json
|
|
131
|
-
```
|
|
132
|
-
|
|
133
|
-
Images and social content:
|
|
134
|
-
|
|
135
|
-
```sh
|
|
136
|
-
coauthor image list <project-id> --json
|
|
137
|
-
coauthor image generate <project-id> --placeholder-id <placeholder-id> --json
|
|
138
|
-
coauthor image status <project-id> --json
|
|
139
|
-
coauthor image edit <project-id> --placeholder-id <placeholder-id> --edit-prompt "Make the sky overcast" --json
|
|
140
|
-
coauthor thread generate <project-id> --writing-model gpt-5.6-terra --json
|
|
141
|
-
```
|
|
142
|
-
|
|
143
|
-
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.
|
|
144
|
-
|
|
145
|
-
## Draft Export
|
|
146
|
-
|
|
147
|
-
Export a finished draft in the format you need:
|
|
148
|
-
|
|
149
|
-
```sh
|
|
150
|
-
coauthor draft get <project-id> --format markdown --json
|
|
151
|
-
coauthor draft get <project-id> --format html --json
|
|
152
|
-
coauthor draft get <project-id> --format text --json
|
|
153
|
-
coauthor draft get <project-id> --format json --json
|
|
154
|
-
```
|
|
155
|
-
|
|
156
|
-
Markdown, HTML, and text exports resolve generated image URLs when images are available. Use `--format json` or omit `--format` for the raw editor document JSON.
|
|
157
|
-
|
|
158
|
-
## Live Actions
|
|
159
|
-
|
|
160
|
-
Publishing and external exports are real side effects. The default login grants project/workflow access only. To run live publish/export commands, sign in with publish permission:
|
|
82
|
+
Publishing an X thread and exporting to WordPress are real side effects. They need a login with publish permission and an explicit `--yes`:
|
|
161
83
|
|
|
162
84
|
```sh
|
|
163
85
|
coauthor auth login --with-publish
|
|
86
|
+
coauthor publish thread <id> --yes --json
|
|
87
|
+
coauthor export wordpress <id> --yes --slug <slug> --json
|
|
164
88
|
```
|
|
165
89
|
|
|
166
|
-
|
|
90
|
+
## Credits
|
|
167
91
|
|
|
168
|
-
|
|
169
|
-
coauthor publish thread <project-id> --yes --json
|
|
170
|
-
coauthor export blog <project-id> --yes --slug "post-slug" --json
|
|
171
|
-
coauthor export clickminded <project-id> --yes --permalink <permalink> --json
|
|
172
|
-
coauthor export wordpress <project-id> --yes --slug "post-slug" --json
|
|
173
|
-
coauthor operation status <operation-key> --json
|
|
174
|
-
```
|
|
175
|
-
|
|
176
|
-
For multiple WordPress connections, include `--connection-id <id>`.
|
|
177
|
-
|
|
178
|
-
Live actions require both publish scope and `--yes`.
|
|
179
|
-
|
|
180
|
-
## Agent Usage Rules
|
|
181
|
-
|
|
182
|
-
Agents should:
|
|
183
|
-
|
|
184
|
-
- Prefer `coauthor` commands over browser automation, hand-written HTTP requests, or direct database access.
|
|
185
|
-
- Use `--json` for machine-readable output.
|
|
186
|
-
- Use `--wait` when starting asynchronous work and the user expects the result.
|
|
187
|
-
- Treat `status: "credits_exhausted"` or `paused_credits_exhausted` as a recoverable Starter pause. Report the supplied `reset_at`, `allowance`, `used`, `held`, and `remaining`, then resume after credits reset; do not tell a Starter user to add an API key.
|
|
188
|
-
- Treat `status: "requires_key"` or `paused_requires_key` as a recoverable Pro pause. Report the compatible required provider, ask the user to add that key in CoAuthor AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
|
|
189
|
-
- Treat `coauthor_access_required` as an access failure and `entitlement_sync_unavailable` as a temporary verification outage. Do not retry blocked credit-spending commands in a loop.
|
|
190
|
-
- Treat `status: "research_running_stale"` as a stale research run and inspect `coauthor research structured <project-id> --json` before retrying.
|
|
191
|
-
- Check operation status after timeouts, interruptions, network errors, or uncertain live-action results.
|
|
192
|
-
- Never print tokens, cookies, provider keys, service-role keys, or authorization headers.
|
|
92
|
+
`coauthor credits <id> --json` shows your plan, credits used, and when they reset. A typical article uses about 300 credits; images and rework rounds add the most. When included credits run out, work pauses safely and resumes with `coauthor workflow resume <id> --wait --json` (after the reset, or on Pro after adding your own provider key in CoAuthor's AI settings).
|
|
193
93
|
|
|
194
94
|
## Security
|
|
195
95
|
|
|
196
|
-
-
|
|
197
|
-
-
|
|
198
|
-
-
|
|
199
|
-
-
|
|
200
|
-
- Run `coauthor auth logout` to revoke the current token and then remove local credentials. A failed revoke preserves the local credential for retry; `--local-only` explicitly skips remote revocation.
|
|
96
|
+
- The CLI stores a scoped CoAuthor token (not a browser cookie) at `~/.coauthor/config.json`. Don't print, paste, or commit it.
|
|
97
|
+
- The default login can read and write your projects. Publishing and exports need `auth login --with-publish`.
|
|
98
|
+
- `coauthor auth logout` revokes the token on the server, then removes it locally. If revocation can't be confirmed, the token is kept so you can retry; `--local-only` removes it locally without revoking.
|
|
99
|
+
- AI provider keys are only ever entered in CoAuthor's AI settings, never in the CLI.
|
|
201
100
|
|
|
202
101
|
## Troubleshooting
|
|
203
102
|
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
If `auth logout` cannot confirm remote revocation, it leaves `~/.coauthor/config.json` intact and exits with an error. Retry normal logout when connectivity recovers. Use `auth logout --local-only` only to abandon remote revocation and remove the local credential anyway.
|
|
211
|
-
|
|
212
|
-
`coauthor_access_required` means the signed-in account no longer has verified CoAuthor access. A device token does not grant product access by itself. `auth status` and `auth logout` remain available, and an unexpired token works again if access is restored.
|
|
213
|
-
|
|
214
|
-
`entitlement_sync_unavailable` means Drip verification is temporarily degraded. Read-only inspection may remain available, but new credit-spending work is blocked until synchronization recovers. Login retries verification immediately, and scheduled reconciliation continues retrying with backoff; do not loop write commands while degraded.
|
|
215
|
-
|
|
216
|
-
`credits_exhausted` or `paused_credits_exhausted` means a Starter workflow is safely paused until the response's `reset_at`. Report its `allowance`, `used`, `held`, and `remaining` so the pause can be explained without guessing. Starter does not support BYOK.
|
|
217
|
-
|
|
218
|
-
`requires_key` or `paused_requires_key` means Pro included credits are exhausted and no usable compatible provider key is configured. Open CoAuthor AI settings, add one of the response's `required_providers`, then run `coauthor workflow resume <project-id> --wait --json`.
|
|
219
|
-
|
|
220
|
-
`byok_not_allowed` means the current plan cannot create, validate, or use provider keys. Starter users can delete a retained key from an earlier Pro period, but it remains inactive unless Pro access returns.
|
|
221
|
-
|
|
222
|
-
`research_running_stale` means a research run is still marked running beyond the expected progress window. Inspect `coauthor research structured <project-id> --json`; if it only contains empty section shells, rewind research or report the stale run instead of repeatedly resuming.
|
|
103
|
+
- **"Missing bearer token" / 401:** run `coauthor auth login`.
|
|
104
|
+
- **`insufficient_scope`:** run `coauthor auth login --with-publish` for publish and export.
|
|
105
|
+
- **`coauthor_access_required`:** the account has no active CoAuthor subscription.
|
|
106
|
+
- **`credits_exhausted` / `requires_key`:** see Credits above.
|
|
107
|
+
- **`timed_out`:** the work is still running in CoAuthor; run the resume command printed in the output.
|
|
108
|
+
- **`stale_draft`:** the draft changed since it was read; re-read it with `coauthor draft get` and apply the edit again.
|
|
223
109
|
|
|
224
|
-
|
|
110
|
+
Every error prints its `code` and details with `--json`. The skill's `references/troubleshooting.md` lists them all.
|