@clickminded/coauthor-cli 0.0.2 → 0.0.3
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 +54 -114
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,54 +1,18 @@
|
|
|
1
1
|
# CoAuthor CLI
|
|
2
2
|
|
|
3
|
-
`@clickminded/coauthor-cli`
|
|
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, and Cursor.
|
|
4
4
|
|
|
5
|
-
The
|
|
5
|
+
The CLI is public, but your CoAuthor data is private. Every project command requires a scoped token issued by browser/device login.
|
|
6
6
|
|
|
7
7
|
## Requirements
|
|
8
8
|
|
|
9
9
|
- Node.js 20 or newer.
|
|
10
|
-
- A
|
|
11
|
-
- The
|
|
12
|
-
- `COAUTHOR_API_TOKEN_PEPPER` configured on the web app.
|
|
13
|
-
- A CoAuthor web account for browser-based device authorization.
|
|
10
|
+
- A CoAuthor account.
|
|
11
|
+
- The base URL for the CoAuthor workspace you want to use.
|
|
14
12
|
|
|
15
|
-
|
|
13
|
+
CoAuthor server setup, database migrations, and web app environment variables are maintainer/deployment concerns. They are not required for normal CLI users.
|
|
16
14
|
|
|
17
|
-
##
|
|
18
|
-
|
|
19
|
-
From the monorepo root:
|
|
20
|
-
|
|
21
|
-
```sh
|
|
22
|
-
pnpm install
|
|
23
|
-
pnpm --filter @clickminded/coauthor-cli build
|
|
24
|
-
node packages/cli/dist/index.js help
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
For a shorter local command while developing:
|
|
28
|
-
|
|
29
|
-
```sh
|
|
30
|
-
alias coauthor='node /Users/eduardoyi/Coding/CoAuthor/packages/cli/dist/index.js'
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
Or run through pnpm:
|
|
34
|
-
|
|
35
|
-
```sh
|
|
36
|
-
pnpm --filter @clickminded/coauthor-cli build
|
|
37
|
-
node packages/cli/dist/index.js auth status --base-url http://localhost:3000
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
## npm Install
|
|
41
|
-
|
|
42
|
-
The package is published as a public scoped npm package:
|
|
43
|
-
|
|
44
|
-
```json
|
|
45
|
-
{
|
|
46
|
-
"name": "@clickminded/coauthor-cli",
|
|
47
|
-
"publishConfig": {
|
|
48
|
-
"access": "public"
|
|
49
|
-
}
|
|
50
|
-
}
|
|
51
|
-
```
|
|
15
|
+
## Install
|
|
52
16
|
|
|
53
17
|
Install globally:
|
|
54
18
|
|
|
@@ -57,18 +21,22 @@ npm install -g @clickminded/coauthor-cli
|
|
|
57
21
|
coauthor auth status
|
|
58
22
|
```
|
|
59
23
|
|
|
60
|
-
|
|
24
|
+
Or run without a global install:
|
|
61
25
|
|
|
62
26
|
```sh
|
|
63
|
-
npx @clickminded/coauthor-cli
|
|
27
|
+
npx @clickminded/coauthor-cli help
|
|
64
28
|
```
|
|
65
29
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
## Authentication
|
|
30
|
+
## Authenticate
|
|
69
31
|
|
|
70
32
|
Start browser/device login:
|
|
71
33
|
|
|
34
|
+
```sh
|
|
35
|
+
coauthor auth login --base-url <coauthor-app-url>
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
For example, when testing against a local CoAuthor app:
|
|
39
|
+
|
|
72
40
|
```sh
|
|
73
41
|
coauthor auth login --base-url http://localhost:3000
|
|
74
42
|
```
|
|
@@ -76,10 +44,10 @@ coauthor auth login --base-url http://localhost:3000
|
|
|
76
44
|
Request publish/export permission during login:
|
|
77
45
|
|
|
78
46
|
```sh
|
|
79
|
-
coauthor auth login --base-url
|
|
47
|
+
coauthor auth login --base-url <coauthor-app-url> --with-publish
|
|
80
48
|
```
|
|
81
49
|
|
|
82
|
-
The CLI opens
|
|
50
|
+
The CLI opens a browser approval page. Approving there issues a scoped API token for the signed-in CoAuthor user.
|
|
83
51
|
|
|
84
52
|
Check the current token:
|
|
85
53
|
|
|
@@ -98,7 +66,7 @@ Local credentials are stored at `~/.coauthor/config.json` with best-effort `0600
|
|
|
98
66
|
Environment variables override the config file:
|
|
99
67
|
|
|
100
68
|
```sh
|
|
101
|
-
COAUTHOR_BASE_URL
|
|
69
|
+
COAUTHOR_BASE_URL=<coauthor-app-url>
|
|
102
70
|
COAUTHOR_TOKEN=coauthor_xxx
|
|
103
71
|
```
|
|
104
72
|
|
|
@@ -133,7 +101,7 @@ Default install paths are:
|
|
|
133
101
|
|
|
134
102
|
Use `--dry-run` to preview, `--force` to overwrite existing files, and `--cwd <path>` to install Claude/Cursor skills into a specific project.
|
|
135
103
|
|
|
136
|
-
## Commands
|
|
104
|
+
## Common Commands
|
|
137
105
|
|
|
138
106
|
Projects:
|
|
139
107
|
|
|
@@ -149,64 +117,27 @@ Chat and workflow:
|
|
|
149
117
|
```sh
|
|
150
118
|
coauthor chat <project-id> --message "..." --json
|
|
151
119
|
coauthor workflow status <project-id> --json
|
|
152
|
-
coauthor workflow advance <project-id> --stage contract --json
|
|
153
120
|
coauthor workflow run <project-id> --target draft --wait --json
|
|
154
|
-
coauthor workflow run <project-id> --target draft --briefing-mode auto --wait --json
|
|
155
|
-
coauthor workflow run <project-id> --target outline --briefing-mode strict --max-brief-questions 2 --json
|
|
156
121
|
coauthor workflow rewind <project-id> --stage outline --reason "..." --json
|
|
157
122
|
coauthor workflow approve <project-id> --stage research_plan --json
|
|
158
123
|
```
|
|
159
124
|
|
|
160
|
-
`--briefing-mode` controls the bounded contract review before the CLI moves from brainstorming to outline:
|
|
161
|
-
|
|
162
|
-
- `auto` (default): enrich a thin brief and continue when the reviewer can make safe assumptions.
|
|
163
|
-
- `strict`: stop with structured clarification questions unless the brief is clearly strong enough.
|
|
164
|
-
- `off`: preserve the old direct approval behavior.
|
|
165
|
-
|
|
166
|
-
`--require-brief-review` is equivalent to strict mode. If the review needs input, the command returns `ok: true` with `data.status = "needs_clarification"` and a `clarification_questions` array instead of entering an open-ended brainstorm.
|
|
167
|
-
|
|
168
125
|
Artifacts:
|
|
169
126
|
|
|
170
127
|
```sh
|
|
171
128
|
coauthor contract show <project-id> --json
|
|
172
|
-
coauthor contract save <project-id> --data '{"contract":{}}' --json
|
|
173
|
-
coauthor contract approve <project-id> --json
|
|
174
|
-
|
|
175
|
-
coauthor outline show <project-id> --json
|
|
176
129
|
coauthor outline generate <project-id> --json
|
|
177
|
-
coauthor outline save <project-id> --data '{"outline":{}}' --json
|
|
178
|
-
coauthor outline approve <project-id> --json
|
|
179
|
-
|
|
180
|
-
coauthor research-plan show <project-id> --json
|
|
181
130
|
coauthor research-plan generate <project-id> --json
|
|
182
|
-
coauthor research-plan save <project-id> --data '{"plan":{}}' --json
|
|
183
|
-
coauthor research-plan approve <project-id> --json
|
|
184
|
-
```
|
|
185
|
-
|
|
186
|
-
Research and draft generation:
|
|
187
|
-
|
|
188
|
-
```sh
|
|
189
131
|
coauthor research run <project-id> --wait --json
|
|
190
|
-
coauthor research status <project-id> --json
|
|
191
|
-
coauthor research structured <project-id> --json
|
|
192
|
-
|
|
193
132
|
coauthor draft generate <project-id> --wait --json
|
|
194
|
-
coauthor draft status <project-id> --json
|
|
195
|
-
coauthor draft get <project-id> --format json --json
|
|
196
133
|
coauthor draft get <project-id> --format markdown --json
|
|
197
|
-
coauthor draft save <project-id> --data '{"document_id":"...","content":{},"expected_base_version":1}' --json
|
|
198
134
|
```
|
|
199
135
|
|
|
200
136
|
Images and threads:
|
|
201
137
|
|
|
202
138
|
```sh
|
|
203
139
|
coauthor image list <project-id> --json
|
|
204
|
-
coauthor image status <project-id> --json
|
|
205
|
-
coauthor image show <project-id> <image-id> --json
|
|
206
140
|
coauthor image generate <project-id> --prompt "..." --json
|
|
207
|
-
|
|
208
|
-
coauthor thread list <project-id> --json
|
|
209
|
-
coauthor thread show <project-id> --json
|
|
210
141
|
coauthor thread generate <project-id> --json
|
|
211
142
|
coauthor thread save <project-id> --data '{"posts":[]}' --json
|
|
212
143
|
```
|
|
@@ -222,6 +153,23 @@ coauthor operation status <operation-key> --json
|
|
|
222
153
|
|
|
223
154
|
Live actions require both token scope and `--yes`.
|
|
224
155
|
|
|
156
|
+
## Briefing Review
|
|
157
|
+
|
|
158
|
+
Workflow runs perform a bounded briefing review before the CLI moves from brainstorming to outline. This avoids weak briefs without trapping an agent in an open-ended conversation.
|
|
159
|
+
|
|
160
|
+
```sh
|
|
161
|
+
coauthor workflow run <project-id> --target draft --briefing-mode auto --wait --json
|
|
162
|
+
coauthor workflow run <project-id> --target outline --briefing-mode strict --max-brief-questions 2 --json
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
`--briefing-mode` options:
|
|
166
|
+
|
|
167
|
+
- `auto` (default): enrich a thin brief and continue when the reviewer can make safe assumptions.
|
|
168
|
+
- `strict`: stop with structured clarification questions unless the brief is clearly strong enough.
|
|
169
|
+
- `off`: skip the bounded review.
|
|
170
|
+
|
|
171
|
+
`--require-brief-review` is equivalent to strict mode. If the review needs input, the command returns `ok: true` with `data.status = "needs_clarification"` and a `clarification_questions` array.
|
|
172
|
+
|
|
225
173
|
## Agent Usage Rules
|
|
226
174
|
|
|
227
175
|
Agents should:
|
|
@@ -233,6 +181,14 @@ Agents should:
|
|
|
233
181
|
- Use `coauthor operation status <operation-key>` after uncertainty.
|
|
234
182
|
- Never print tokens, cookies, service-role keys, or authorization headers.
|
|
235
183
|
|
|
184
|
+
## Security
|
|
185
|
+
|
|
186
|
+
- Tokens are scoped CoAuthor API tokens, not browser cookies.
|
|
187
|
+
- Default login grants workflow/project scopes only.
|
|
188
|
+
- Publish/export scope is granted only when login is started with `--with-publish`.
|
|
189
|
+
- Tokens are stored locally at `~/.coauthor/config.json`.
|
|
190
|
+
- Run `coauthor auth logout` to revoke the current token and remove local credentials.
|
|
191
|
+
|
|
236
192
|
## Public API Stability
|
|
237
193
|
|
|
238
194
|
The CLI talks to `/api/agent/v1/*`. Treat this as a public beta API surface:
|
|
@@ -242,39 +198,23 @@ The CLI talks to `/api/agent/v1/*`. Treat this as a public beta API surface:
|
|
|
242
198
|
- Errors should stay structured and machine-readable with `--json`.
|
|
243
199
|
- Server-side auth, ownership checks, scopes, and rate limits remain mandatory.
|
|
244
200
|
|
|
245
|
-
##
|
|
246
|
-
|
|
247
|
-
Before publishing:
|
|
201
|
+
## Troubleshooting
|
|
248
202
|
|
|
249
|
-
|
|
250
|
-
pnpm --filter @clickminded/coauthor-cli test
|
|
251
|
-
pnpm --filter @clickminded/coauthor-cli build
|
|
252
|
-
cd packages/cli
|
|
253
|
-
npm pack --dry-run
|
|
254
|
-
```
|
|
203
|
+
`No token configured` means the CLI has no credential for the selected base URL. Run `coauthor auth login --base-url <url>`.
|
|
255
204
|
|
|
256
|
-
|
|
205
|
+
`insufficient_scope` means the token does not include the required scope. For publish/export, log in again with `--with-publish`.
|
|
257
206
|
|
|
258
|
-
|
|
259
|
-
git tag @clickminded/coauthor-cli@0.0.2
|
|
260
|
-
git push origin @clickminded/coauthor-cli@0.0.2
|
|
261
|
-
```
|
|
207
|
+
`authorization_pending` during login is normal while the browser approval page is waiting for browser approval.
|
|
262
208
|
|
|
263
|
-
|
|
209
|
+
If `npx @clickminded/coauthor-cli help` fails while you are inside the CLI package source directory, run it from another directory or use:
|
|
264
210
|
|
|
265
211
|
```sh
|
|
266
|
-
|
|
267
|
-
npx @clickminded/coauthor-cli auth status
|
|
212
|
+
npm exec --package=@clickminded/coauthor-cli@latest -- coauthor-cli help
|
|
268
213
|
```
|
|
269
214
|
|
|
270
|
-
##
|
|
271
|
-
|
|
272
|
-
`No token configured` means the CLI has no credential for the selected base URL. Run `coauthor auth login --base-url <url>`.
|
|
273
|
-
|
|
274
|
-
`insufficient_scope` means the token does not include the required scope. For publish/export, log in again with `--with-publish`.
|
|
275
|
-
|
|
276
|
-
`authorization_pending` during login is normal while the browser approval page is still waiting.
|
|
215
|
+
## For CoAuthor Maintainers
|
|
277
216
|
|
|
278
|
-
|
|
217
|
+
This README is written for public CLI users. Maintainer/deployment details such as database migrations, `COAUTHOR_API_TOKEN_PEPPER`, local monorepo development, and npm Trusted Publishing live in the CoAuthor repository docs:
|
|
279
218
|
|
|
280
|
-
|
|
219
|
+
- `docs/agent-cli.md`
|
|
220
|
+
- `docs/skills.md`
|