@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 CHANGED
@@ -1,224 +1,110 @@
1
1
  # CoAuthor CLI
2
2
 
3
- `@clickminded/coauthor-cli` installs the `coauthor` command for working with CoAuthor projects from a terminal or from AI coding agents such as Codex, Claude Code, Cursor, and other local agents.
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 account with access to CoAuthor.
11
-
12
- ## Install
8
+ - A CoAuthor subscription.
13
9
 
14
- Install globally:
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
- The CLI opens a browser approval page. After approval, it stores a scoped local token for your signed-in CoAuthor account.
35
-
36
- Check your login:
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
- ```sh
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
- Normal logout removes the local credential only after remote revocation succeeds or the server confirms the token was already revoked or expired. If the server cannot confirm revocation, the CLI keeps the credential so you can retry safely.
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 auth logout --local-only
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
- Use `--local-only` only when you explicitly accept that the remote token may remain usable until it expires or is revoked elsewhere.
57
-
58
- Local credentials are stored at `~/.coauthor/config.json` with best-effort `0600` permissions. Do not print, paste, or commit this file.
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
- ## Agent Skills
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
- Install agent instructions after installing the CLI:
43
+ ## What your agent does with it
63
44
 
64
- ```sh
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 skills install codex
72
- coauthor skills install claude
73
- coauthor skills install cursor
74
- coauthor skills install agents
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
- Default install paths are:
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 project create --title "Post title" --topic "Post brief" --audience "Target reader" --json
94
- coauthor project create --contract '{"topic":"Post topic","angle":"Specific angle","target_audience":"Target reader","must_include":["Point to cover"]}' --json
95
- coauthor project list --json
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
- Work with the project:
66
+ Images, social, and export:
101
67
 
102
68
  ```sh
103
- coauthor chat <project-id> --message "Refine the angle for this post" --json
104
- coauthor workflow status <project-id> --json
105
- coauthor workflow run <project-id> --target draft --wait --json
106
- coauthor workflow run <project-id> --target draft --planning-model gpt-5.6-sol --writing-model gpt-5.6-terra --wait --json
107
- coauthor workflow resume <project-id> --target draft --wait --json
108
- coauthor credits <project-id> --json
109
- coauthor share <project-id> --json
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
- List and save text model preferences:
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
- ```sh
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
- Both plans can select any supported user-visible model. Starter includes 2,500 credits per monthly subscription-anniversary period and cannot use customer API keys. Pro includes 6,000 credits and uses included credits first, then a compatible configured provider key. A provider key is never required merely to select a model while included credits remain. Drip tags alone determine customer access and plan; subscription observations are diagnostic and set anniversary timing only. All statuses are retained, only `active` observations can promote an anchor, and renewal observations do not reset credits. The Supabase `admins` table is the canonical cross-surface admin bypass source.
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
- Then run live actions only when you mean to publish or export:
90
+ ## Credits
167
91
 
168
- ```sh
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
- - Tokens are scoped CoAuthor API tokens, not browser cookies.
197
- - Default login grants workflow/project scopes only.
198
- - Publish/export scope is granted only when login is started with `--with-publish`.
199
- - Tokens are stored locally at `~/.coauthor/config.json`.
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
- `No token configured` means the CLI has no saved CoAuthor credential. Run `coauthor auth login`.
205
-
206
- `insufficient_scope` means the token does not include the required scope. For publish/export, log in again with `coauthor auth login --with-publish`.
207
-
208
- `authorization_pending` during login is normal while the browser approval page is waiting for approval.
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
- Image generation requires an existing image placeholder. Run `coauthor image list <project-id> --json` after draft generation and pass the placeholder id to `coauthor image generate <project-id> --placeholder-id <placeholder-id> --json`.
110
+ Every error prints its `code` and details with `--json`. The skill's `references/troubleshooting.md` lists them all.