@amdahl/cli 0.3.3 → 0.3.5

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 +232 -58
  2. package/dist/amdahl.js +851 -264
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -45,78 +45,240 @@ anything, names the version it found, and links the Node.js download page.
45
45
 
46
46
  ```sh
47
47
  # Run once, with no install
48
- npx @amdahl/cli login
48
+ npx -y amdahl
49
49
 
50
50
  # Or install the `amdahl` command
51
51
  npm i -g @amdahl/cli
52
- amdahl login
52
+ amdahl
53
53
  ```
54
54
 
55
55
  `amdahl` is also on npm by its short name, so `npx amdahl ...` is the same as
56
56
  `npx @amdahl/cli ...`. That package ([packages/amdahl](packages/amdahl)) has no
57
57
  code of its own: it depends on `@amdahl/cli` at the same version and runs it.
58
+ npm asks "Ok to proceed? (y)" before every `npx` run of a package you have not
59
+ installed; `npx -y` skips that question, so every example here uses it.
58
60
 
59
- The quickest way to start is `npx amdahl` with nothing after it, in a
60
- terminal. It walks you through setup:
61
+ The quickest way to start is `npx -y amdahl` with nothing after it (or
62
+ `npx -y amdahl setup`), in a terminal. It asks where Amdahl should work:
61
63
 
62
64
  ```
63
- $ npx amdahl
65
+ $ npx -y amdahl
64
66
  Amdahl · predictive ML for GTM
65
- Set up in:
66
- > [x] Claude Code
67
+ Where should Amdahl work?
68
+ > [x] Claude Code found on your machine
67
69
  [ ] Cursor
68
70
  [ ] Codex
69
- (Use the arrow keys, Space to tick or untick, then Enter)
70
- Opening your browser…
71
- Browser didn't open? Press Enter for the link.
71
+ [ ] This terminal
72
+ ↑↓ move · Space tick/untick · Enter continue
73
+ ```
74
+
75
+ It finds Claude Code, Cursor and Codex by their command on your PATH
76
+ (`claude`, `cursor`, `codex`) or their files in your home folder (`.claude`
77
+ or `.claude.json`, `.cursor`, `.codex`). Only the ones it finds are ticked
78
+ and tagged "found on your machine" (in dim grey where colour is allowed).
79
+ "This terminal" is always there and never ticked for you. If it finds none
80
+ of the three, it says so under the question, points Claude and ChatGPT app
81
+ users to https://amdahl.ai/connect, and the marker starts on "This
82
+ terminal", so Space then Enter picks it:
83
+
84
+ ```
85
+ Where should Amdahl work?
86
+ We didn't find Claude Code, Cursor or Codex on this computer.
87
+ Using the Claude or ChatGPT app? Connect it at https://amdahl.ai/connect
88
+ [ ] Claude Code
89
+ [ ] Cursor
90
+ [ ] Codex
91
+ > [ ] This terminal
92
+ ↑↓ move · Space tick/untick · Enter continue
93
+ ```
94
+
95
+ The `>` marker starts on the first ticked row, and only the marker is
96
+ coloured, so the row under it never looks picked when it is not. Esc, `q`
97
+ or Ctrl+C stops with nothing changed (exit 130). The menu redraws in place
98
+ in any width, also in a split pane narrower than its lines, and `NO_COLOR`
99
+ or `--no-color` turn the colour off. Enter with nothing ticked changes
100
+ nothing and says how to try Amdahl: run it again and tick "This terminal",
101
+ or connect the Claude or ChatGPT app at https://amdahl.ai/connect.
102
+
103
+ ### The AI tools: set up first, then one sign-in in the tool
104
+
105
+ For Claude Code, Cursor and Codex there is no sign-in in the terminal. The
106
+ setup writes each tool's config straight away (as `amdahl install` does), so
107
+ nothing is lost if you stop later, and then prints that tool's next steps.
108
+ Each tool signs in to Amdahl itself, over OAuth, the first time it connects;
109
+ that sign-in is also where a new user creates their free workspace. Each
110
+ screen is six lines or fewer:
111
+
112
+ ```
113
+ ✓ Added Amdahl to Claude Code.
114
+ One step left, in Claude Code:
115
+ 1. If it's open, quit and reopen it. Type /mcp, pick amdahl, sign in.
116
+ 2. Paste an email and say: "Use Amdahl to make this sound less like AI"
117
+ New to Amdahl? The sign-in sets up your free workspace.
118
+ ```
119
+
120
+ ```
121
+ ✓ Added Amdahl to Cursor.
122
+ One step left, in Cursor:
123
+ 1. If it's open, quit and reopen it. In Customize > MCPs, sign in to amdahl.
124
+ 2. In chat, paste an email, say: "Use Amdahl to make this sound less like AI"
125
+ ```
126
+
127
+ Cursor reads `~/.cursor/mcp.json` when it starts and lists its MCP servers
128
+ under Customize, then MCPs.
129
+
130
+ Codex runs in the same terminal, so with `codex` on your PATH the setup
131
+ offers to run its sign-in for you:
132
+
133
+ ```
134
+ ✓ Added Amdahl to Codex.
135
+ Press Enter to sign Codex in to Amdahl (opens your browser).
136
+ ✓ Codex is connected.
137
+ Run codex, paste an email and say: "Use Amdahl to make this sound less like AI"
138
+ ```
139
+
140
+ Enter runs `codex mcp login amdahl` on your terminal (it prints the link and
141
+ opens the browser). Ctrl+C there skips it and names the command to run
142
+ later; if the sign-in does not finish, it says so and names the same
143
+ command. Without `codex` on your PATH, the screen lists `codex mcp login
144
+ amdahl` as step 1. With more than one tool, the screens follow one another
145
+ and the "New to Amdahl?" line is printed once. A tool that fails (a broken
146
+ `~/.cursor/mcp.json` or `~/.claude.json`, say) prints its error, the rest
147
+ still run, and the exit code is the first failure's. In a terminal narrower
148
+ than a screen's lines, they break between words, and a numbered step's next
149
+ line starts under its text.
150
+
151
+ ### This terminal: try it on a message
152
+
153
+ Pick "This terminal" (alone or beside the tools, which are set up first) to
154
+ see Amdahl work right away. It signs you in through the browser if you are
155
+ not signed in yet, then asks for a message:
156
+
157
+ ```
72
158
  ✓ Signed in · Acme
159
+ Paste an email or LinkedIn message, then press Enter on an empty line:
160
+ <your draft>
161
+ Amdahl is rewriting it. This can take a minute.
162
+ ── Amdahl's version ──────────────
163
+ <the rewritten message>
164
+ Cut the opener and 2 sentences nothing backed.
165
+ Next time: npx -y amdahl optimize draft.txt,
166
+ or pbpaste | npx -y amdahl optimize -
167
+ ```
168
+
169
+ Empty lines inside a paste stay in the message: the terminal marks a paste
170
+ (bracketed paste), and where it does not, an empty line that more text
171
+ follows at once counts as pasted. Ctrl+D also ends the message. The lines
172
+ under Amdahl's version say what it did, as `amdahl optimize` does. The
173
+ `pbpaste` line is printed on macOS only.
174
+
175
+ While it waits for the browser, it prints one short line under "Opening
176
+ your browser…". In a terminal that shows links (iTerm2, VS Code, Warp,
177
+ Terminal, WezTerm, Ghostty, Windows Terminal, VTE 0.50 or later) it reads
178
+ "Browser didn't open? Open the sign-in page" and the last words are a link;
179
+ elsewhere it says to press Enter for the link. `FORCE_HYPERLINK=1` or `0`
180
+ overrides the guess, and `NO_COLOR` turns the link off. Either way, Enter
181
+ prints the full sign-in link once. Once you are signed in, that line is
182
+ replaced by `✓ Signed in`. If the browser could not be opened, or with
183
+ `--no-browser`, the full link prints at once. It waits up to 15 minutes, so
184
+ someone new can create their workspace on the way and land back in the same
185
+ setup. If the server rejects a key set in `AMDAHL_KEY` (or `AMDAHL_API_KEY`,
186
+ `AMDAHL_ACCESS_TOKEN`, `--api-key`), it says so, skips the browser sign-in
187
+ (that key would still win) and exits 3. Ctrl+C during the sign-in or the
188
+ paste stops with exit 130; if tools were set up first, it says they still
189
+ are.
190
+
191
+ ### Run it again
192
+
193
+ When every tool it finds already points at Amdahl, it asks nothing, needs no
194
+ network and signs in nowhere. It says so, with the one thing to try and how
195
+ to finish the tool's sign-in if you have not yet:
196
+
197
+ ```
198
+ Amdahl is in Claude Code. You're all set.
199
+ Paste an email there and say: "Use Amdahl to make this sound less like AI"
200
+ If you've already run /mcp, you're done.
201
+ If not: quit and reopen Claude Code, type /mcp, pick amdahl, sign in.
202
+ Want to try it here instead? Run: npx -y amdahl optimize
203
+ ```
204
+
205
+ An old copy of the Amdahl skill is brought up to date on the way. A tool it
206
+ finds that does not point at Amdahl yet brings the menu back.
207
+ `npx -y amdahl --verbose` also prints the files it wrote, the profile and
208
+ where the sign-in is stored.
209
+
210
+ ### Run by an agent, or with no terminal
211
+
212
+ You can ask Claude Code, Cursor or Codex to run `npx -y amdahl` for you. With
213
+ no terminal (an agent's shell, a pipe such as `npx -y amdahl | cat`, or stdin,
214
+ stdout or stderr redirected), and whenever `CLAUDECODE` or `CURSOR_AGENT`
215
+ is set, it sets up without a question and without a browser sign-in:
216
+
217
+ - `CLAUDECODE` set (Claude Code runs it): Claude Code only.
218
+ - `CURSOR_AGENT` set (Cursor runs it): Cursor only.
219
+ - Anything else (Codex sets no variable): every client it finds.
220
+
221
+ In Codex's default sandbox, writes outside the workspace and network access
222
+ are blocked, so the run usually fails (`npx` cannot fetch the package, or
223
+ `Could not update ~/.codex/config.toml`, exit 1) unless you approve the
224
+ escalation Codex asks for, or run `npx -y amdahl` in your own terminal.
225
+
226
+ Each client signs in on its first connect, over OAuth, so the CLI needs no
227
+ sign-in of its own here. The last lines say what to try and the one step
228
+ that connects each client:
229
+
230
+ ```
73
231
  ✓ Added to Claude Code
74
- Try it: in Claude Code, run /mcp once to connect, then say "make this email sound less like AI"
232
+ Try it: paste an email and say "Use Amdahl to make this sound less like AI" in Claude Code.
233
+ Before that, restart Claude Code and run /mcp once to connect Amdahl.
75
234
  ```
76
235
 
77
- It finds Claude Code, Cursor and Codex by their command on your PATH
78
- (`claude`, `cursor`, `codex`) or their folder in your home folder (`.claude`,
79
- `.cursor`, `.codex`), and ticks the ones it finds. Enter accepts. If you are
80
- not signed in, it signs you in through the browser first. Under "Opening
81
- your browser…" it prints one short line. In a terminal that shows links
82
- (iTerm2, VS Code, Warp, Terminal, WezTerm, Ghostty, Windows Terminal, VTE 0.50
83
- or later) it reads "Browser didn't open? Open the sign-in page" and the last
84
- words are a link; elsewhere it says to press Enter for the link.
85
- `FORCE_HYPERLINK=1` or `0` overrides the guess, and `NO_COLOR` turns the link
86
- off. Either way, Enter prints the full sign-in link once. If the browser
87
- could not be opened, or with `--no-browser`, the full link prints at once.
88
- It waits up to 15 minutes, so someone new can create their workspace on the
89
- way and land back in the same setup. If the server
90
- rejects a key set in
91
- `AMDAHL_KEY` (or `AMDAHL_API_KEY`, `AMDAHL_ACCESS_TOKEN`, `--api-key`), it says
92
- so and skips the browser sign-in, since that key would still win. Then it
93
- sets up each client you ticked the way `amdahl install` does, one line each.
94
- A client that fails prints
95
- its error and the rest still run; the exit code is the first failure's. It
96
- ends with something to try in the first client it set up. Each client then
97
- signs in to Amdahl itself, once, the first time it connects: `/mcp` in
98
- Claude Code, `codex mcp login amdahl` for Codex (always named, since the CLI
99
- cannot tell whether it ran), and Cursor asks on first use.
100
- `npx amdahl --verbose` also prints the files it wrote, the profile and where
101
- the sign-in is stored.
102
- Run it again once you are set up and it says `You're set up in Claude Code
103
- and Cursor.` with a line to try, and asks nothing; if it cannot reach
104
- Amdahl to check your sign-in, it still says so. Ctrl+C at the question stops
105
- it with nothing written (exit 130).
106
-
107
- It only does this for a person at a terminal. When stdin, stdout or stderr
108
- (where the menu draws) is not a terminal, `CI` is set, an agent runs it (`CLAUDECODE` or `CURSOR_AGENT` is
109
- set), `AMDAHL_NO_PROMPT=1` is set, or any flag other than `--verbose` is given
110
- (such as `--json`), bare `amdahl` prints the usage to stderr and exits 2, as
111
- before.
236
+ Run from inside Claude Code, the step is "restart Claude Code and run /mcp
237
+ once", since a running session may only see the new server after a
238
+ restart. If
239
+ it finds no client, it says so on stderr, names `npx -y amdahl install
240
+ claude-code`, writes nothing and exits 1.
241
+
242
+ **Exit code change in 0.3.4.** Before 0.3.4, bare `amdahl` with no terminal
243
+ or with `CLAUDECODE` or `CURSOR_AGENT` set printed the usage and exited 2.
244
+ It now sets up as above and exits 0 (1 when nothing was found or a client
245
+ failed). In CI, with `AMDAHL_NO_PROMPT=1`, or with `--json`, bare `amdahl`
246
+ still changes nothing, exits 2 and prints the usage to stderr, now after one
247
+ line that says why and names `amdahl install`. CI means one of `CI`, `JENKINS_URL`, `TF_BUILD`,
248
+ `CODEBUILD_BUILD_ID`, `TEAMCITY_VERSION`, `GITHUB_ACTIONS`, `GITLAB_CI`,
249
+ `BUILDKITE` or `CIRCLECI` is set (other than `false` or `0`), or
250
+ `BUILD_NUMBER` is set together with `JENKINS_HOME`.
251
+
252
+ When the CLI was started by `npx`, every message that names a command says
253
+ `npx -y amdahl ...` (for example `npx -y amdahl login`), since an `npx` user
254
+ has no `amdahl` on their PATH, and `-y` skips npm's question.
112
255
 
113
256
  To connect one AI client yourself, run `amdahl install claude-code` (or `codex`,
114
257
  `cursor`). It adds the Amdahl MCP server and also installs the Amdahl skill,
115
258
  a map of everything Amdahl can do, so your agent knows which tool fits each
116
259
  job. If the client already points at Amdahl, `install` leaves that as it is
117
- (for Claude Code it skips `claude mcp add` when `claude mcp get amdahl`
118
- shows the same URL) and still installs the skill. If it cannot write the
119
- client's config file, it exits 1 with `write_failed` and names the file. The skill goes to the client's user skills folder:
260
+ (for Claude Code it skips `claude mcp add` when `~/.claude.json` or `claude
261
+ mcp get amdahl` shows the same URL) and still installs the skill.
262
+
263
+ For Claude Code it runs `claude mcp add --scope user --transport http amdahl
264
+ https://app.amdahl.ai/mcp`. The desktop app and the IDE extensions often
265
+ leave no `claude` on your PATH, so it also looks in `~/.local/bin`,
266
+ `~/.claude/local`, `/opt/homebrew/bin`, `/usr/local/bin` and npm's global
267
+ bin. If none has `claude`, it writes the same entry into Claude Code's user
268
+ settings itself: `mcpServers.amdahl` set to `{"type": "http", "url":
269
+ "https://app.amdahl.ai/mcp"}` at the top level of `~/.claude.json` (in
270
+ `CLAUDE_CONFIG_DIR` when that is set). It keeps every other key, saves the
271
+ file as it was to `~/.claude.json.amdahl-backup` first, writes the new file
272
+ to a temp file and renames it into place (following a symbolic link), and
273
+ changes nothing when the entry is already there. A file that is not a JSON
274
+ object is left alone (exit 1, `invalid_config`). Cursor's and Codex's config
275
+ files are also written whole through a temp file. A symbolic link at
276
+ `~/.claude.json` is followed to its target, even one not created yet, and
277
+ stays a link. An `mcpServers` that is not a JSON object (an array, say) in
278
+ `~/.claude.json` or `~/.cursor/mcp.json` is left alone with `invalid_config`,
279
+ found before the setup writes anything. If it cannot write the client's config file, it
280
+ exits 1 with `write_failed` and names the file. The skill goes to the
281
+ client's user skills folder:
120
282
 
121
283
  | client | skill file |
122
284
  |---|---|
@@ -134,11 +296,11 @@ https://docs.amdahl.ai/skills/amdahl/SKILL.md.
134
296
  ## Quick start
135
297
 
136
298
  ```sh
137
- amdahl # in a terminal: guided setup for Claude Code, Cursor and Codex
299
+ amdahl # guided setup for Claude Code, Cursor and Codex, or try it here (an agent can run it too)
138
300
  amdahl login # sign in through the browser with your console account
139
301
  amdahl whoami # the account, workspace and role you are signed in as
140
302
  amdahl status # can this workspace optimize, and what blocks it
141
- amdahl optimize draft.md # rewrite one message (or pipe it in with -)
303
+ amdahl optimize draft.md # rewrite one message (or pipe it in with -, or run it bare and paste)
142
304
  amdahl install claude-code # connect an AI client and add the Amdahl skill (also codex, cursor)
143
305
  amdahl skills add <publisher>/<skill> # add a skill from amdahl.ai/skills to this project
144
306
  ```
@@ -152,12 +314,22 @@ terminal keeps waiting for it. Anything
152
314
  else exits 5 with the one next step (ask your company's admins, try again
153
315
  tomorrow, and so on). The CLI itself never creates or joins a workspace.
154
316
 
317
+ `amdahl login` ends with the next step: `amdahl optimize` to try a pasted
318
+ message, or bare `amdahl` to add Amdahl to Claude Code, Cursor or Codex.
319
+
320
+ `amdahl optimize` with no file, at a terminal, asks you to paste the message
321
+ (as the setup's "This terminal" does) and signs you in through the browser
322
+ first if you are not signed in ("Sign in first, then paste your message."). With stdin piped, or `-`, it reads stdin
323
+ whole as before. With `AMDAHL_NO_PROMPT=1` at a terminal it still says to
324
+ give a file (exit 2).
325
+
155
326
  On a server or in CI, skip `login` and set an API key in `AMDAHL_KEY`.
156
327
 
157
328
  ## Commands
158
329
 
159
330
  ```
160
- amdahl (guided setup, in a terminal)
331
+ amdahl [--no-browser] (guided setup; also: amdahl setup)
332
+ amdahl help (same as --help)
161
333
  amdahl login [--workspace <slug>] [--no-browser] [--port <n>] (alias: auth login)
162
334
  amdahl logout [--all] (alias: auth logout)
163
335
  amdahl whoami [--show-token] (alias: auth status)
@@ -174,7 +346,9 @@ amdahl skills add <publisher>/<skill> [-g] [--agents] [--force] [--accept-warnin
174
346
  ```
175
347
 
176
348
  Global flags: `--profile`, `--api-url`, `--api-key`, `--json`, `--no-color`,
177
- `-h`, `-v`. With `--json`, data goes to stdout and messages to stderr.
349
+ `--verbose`, `-h`, `-v`. With `--json`, data goes to stdout and messages to
350
+ stderr. An unknown option prints `Unknown option --foo.` and `Run \`amdahl
351
+ --help\`.` (exit 2).
178
352
 
179
353
  ## Skills
180
354
 
@@ -182,9 +356,9 @@ Global flags: `--profile`, `--api-url`, `--api-key`, `--json`, `--no-color`,
182
356
  It needs no sign-in.
183
357
 
184
358
  ```sh
185
- npx amdahl skills add <publisher>/<skill>
359
+ npx -y amdahl skills add <publisher>/<skill>
186
360
  # the skill's link works too, with or without .md:
187
- npx amdahl skills add https://amdahl.ai/skills/<publisher>/<skill>
361
+ npx -y amdahl skills add https://amdahl.ai/skills/<publisher>/<skill>
188
362
  ```
189
363
 
190
364
  In a terminal, it asks one question. It prints `Checking <publisher>/<skill>
@@ -365,8 +539,8 @@ code shown in the terminal; then the key is printed once and stored nowhere.
365
539
  | code | meaning |
366
540
  |---|---|
367
541
  | 0 | ok |
368
- | 1 | general (`login_timeout`, `state_mismatch`, optimize `ok: false`, a `skills add` refusal) |
369
- | 2 | usage |
542
+ | 1 | general (`login_timeout`, `state_mismatch`, optimize `ok: false`, a `skills add` refusal, `invalid_config`, bare `amdahl` with no terminal that found no client) |
543
+ | 2 | usage (also bare `amdahl` in CI, with `AMDAHL_NO_PROMPT=1` or with `--json`) |
370
544
  | 3 | not signed in (401, `invalid_grant`, no credential) |
371
545
  | 4 | forbidden (403, `oauth_required`, `cli_client_required`, `not_admin`) |
372
546
  | 5 | no workspace |
@@ -374,7 +548,7 @@ code shown in the terminal; then the key is printed once and stored nowhere.
374
548
  | 7 | approval denied, expired or locked out |
375
549
  | 8 | network or 5xx |
376
550
  | 9 | `skills add` did not install a skill amdahl.ai's security review flagged: no terminal to ask, `-y`, `--json` or an agent ran it, and no `--accept-warning` (nothing was written) |
377
- | 130 | stopped with Ctrl+C at a question (nothing was written) |
551
+ | 130 | stopped with Ctrl+C (or Esc or `q` in a menu) at a question: "Stopped. Nothing changed." (in the setup, after tools were set up: "Stopped. Amdahl is still set up in …") |
378
552
 
379
553
  ## Development
380
554