@clickminded/coauthor-cli 0.0.1 → 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.
Files changed (3) hide show
  1. package/README.md +54 -114
  2. package/dist/index.js +14 -1
  3. package/package.json +3 -2
package/README.md CHANGED
@@ -1,54 +1,18 @@
1
1
  # CoAuthor CLI
2
2
 
3
- `@clickminded/coauthor-cli` is the agent-facing command line for CoAuthor. It lets Codex, Claude Code, Cursor, and human operators work with CoAuthor projects through the versioned JSON API at `/api/agent/v1/*`, instead of using browser-only session routes or direct database access.
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 package installs the `coauthor` binary.
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 running CoAuthor web app with the agent API enabled.
11
- - The agent API database migration applied.
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
- For local development, the default API base URL is `http://localhost:3000`.
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
- ## Local Development Install
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
- Agents can also use an ephemeral install:
24
+ Or run without a global install:
61
25
 
62
26
  ```sh
63
- npx @clickminded/coauthor-cli auth status
27
+ npx @clickminded/coauthor-cli help
64
28
  ```
65
29
 
66
- The CLI is public, but project data is not. Every API call still requires a scoped CoAuthor token issued by browser/device login.
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 http://localhost:3000 --with-publish
47
+ coauthor auth login --base-url <coauthor-app-url> --with-publish
80
48
  ```
81
49
 
82
- The CLI opens `/cli/authorize` in the browser. Approving there issues a scoped API token for the signed-in CoAuthor user.
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=http://localhost:3000
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
- ## Release Checklist
246
-
247
- Before publishing:
201
+ ## Troubleshooting
248
202
 
249
- ```sh
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
- Release by bumping `packages/cli/package.json`, committing, and pushing a tag:
205
+ `insufficient_scope` means the token does not include the required scope. For publish/export, log in again with `--with-publish`.
257
206
 
258
- ```sh
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
- The `Publish CLI` GitHub Action publishes to npm through Trusted Publishing. After release:
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
- npx @clickminded/coauthor-cli help
267
- npx @clickminded/coauthor-cli auth status
212
+ npm exec --package=@clickminded/coauthor-cli@latest -- coauthor-cli help
268
213
  ```
269
214
 
270
- ## Troubleshooting
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
- If local commands can authenticate but workflow jobs never finish, confirm both the web app and worker are running.
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
- If database migration via direct Postgres DNS fails locally, apply the migration through the Supabase SQL editor or another network path that can reach the database.
219
+ - `docs/agent-cli.md`
220
+ - `docs/skills.md`
package/dist/index.js CHANGED
@@ -1,4 +1,6 @@
1
1
  #!/usr/bin/env node
2
+ import { realpathSync } from 'node:fs';
3
+ import { fileURLToPath } from 'node:url';
2
4
  import { AgentHttpError, AgentClient } from './client.js';
3
5
  import { resolveRuntimeConfig } from './config.js';
4
6
  import { runCommand } from './commands.js';
@@ -44,7 +46,18 @@ function extractErrorMessage(body) {
44
46
  const message = error.message;
45
47
  return typeof message === 'string' ? message : null;
46
48
  }
47
- if (import.meta.url === `file://${process.argv[1]}`) {
49
+ function isCliEntrypoint() {
50
+ const argvPath = process.argv[1];
51
+ if (!argvPath)
52
+ return false;
53
+ try {
54
+ return realpathSync(argvPath) === fileURLToPath(import.meta.url);
55
+ }
56
+ catch {
57
+ return false;
58
+ }
59
+ }
60
+ if (isCliEntrypoint()) {
48
61
  main().then((code) => {
49
62
  process.exitCode = code;
50
63
  });
package/package.json CHANGED
@@ -1,9 +1,10 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.1",
3
+ "version": "0.0.3",
4
4
  "type": "module",
5
5
  "bin": {
6
- "coauthor": "dist/index.js"
6
+ "coauthor": "dist/index.js",
7
+ "coauthor-cli": "dist/index.js"
7
8
  },
8
9
  "repository": {
9
10
  "type": "git",