@amdahl/cli 0.3.3 → 0.3.4
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 +129 -51
- package/dist/amdahl.js +516 -206
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -56,67 +56,142 @@ amdahl login
|
|
|
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
58
|
|
|
59
|
-
The quickest way to start is `npx amdahl` with nothing after it
|
|
60
|
-
terminal. It walks you through setup:
|
|
59
|
+
The quickest way to start is `npx amdahl` with nothing after it (or
|
|
60
|
+
`npx amdahl setup`), in a terminal. It walks you through setup:
|
|
61
61
|
|
|
62
62
|
```
|
|
63
63
|
$ npx amdahl
|
|
64
64
|
Amdahl · predictive ML for GTM
|
|
65
|
-
|
|
66
|
-
> [x] Claude Code
|
|
65
|
+
Where should Amdahl work?
|
|
66
|
+
> [x] Claude Code found on your machine
|
|
67
67
|
[ ] Cursor
|
|
68
68
|
[ ] Codex
|
|
69
|
-
|
|
69
|
+
↑↓ move · Space tick/untick · Enter to install
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
It finds Claude Code, Cursor and Codex by their command on your PATH
|
|
73
|
+
(`claude`, `cursor`, `codex`) or their files in your home folder (`.claude`
|
|
74
|
+
or `.claude.json`, `.cursor`, `.codex`). Only the ones it finds are ticked
|
|
75
|
+
and tagged "found on your machine" (in dim grey where colour is allowed). If
|
|
76
|
+
it finds none, it says "We didn't find any of these on this computer. Tick
|
|
77
|
+
the ones you use." under the question. The `>` marker starts on the first
|
|
78
|
+
ticked row, and only the marker is coloured, so the row under it never
|
|
79
|
+
looks picked when it is not. Esc, `q` or Ctrl+C stops with nothing changed
|
|
80
|
+
(exit 130). The menu redraws in place in any width, also in a split pane
|
|
81
|
+
narrower than its lines, and `NO_COLOR` or `--no-color` turn the colour off.
|
|
82
|
+
|
|
83
|
+
After Enter it first checks each client it can set up, so a broken
|
|
84
|
+
`~/.cursor/mcp.json` or `~/.claude.json` is reported before you sign in.
|
|
85
|
+
If you are not signed in, it signs you in through the browser:
|
|
86
|
+
|
|
87
|
+
```
|
|
88
|
+
Where should Amdahl work? Claude Code
|
|
70
89
|
Opening your browser…
|
|
71
|
-
Browser didn't open? Press Enter for the link.
|
|
72
90
|
✓ Signed in · Acme
|
|
73
91
|
✓ Added to Claude Code
|
|
74
|
-
Try it:
|
|
92
|
+
Try it: say "make this email sound less like AI" in Claude Code.
|
|
93
|
+
Before that, run /mcp once in Claude Code to connect Amdahl.
|
|
75
94
|
```
|
|
76
95
|
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
96
|
+
While it waits, it prints one short line under "Opening your browser…". In
|
|
97
|
+
a terminal that shows links (iTerm2, VS Code, Warp, Terminal, WezTerm,
|
|
98
|
+
Ghostty, Windows Terminal, VTE 0.50 or later) it reads "Browser didn't open?
|
|
99
|
+
Open the sign-in page" and the last words are a link; elsewhere it says to
|
|
100
|
+
press Enter for the link. `FORCE_HYPERLINK=1` or `0` overrides the guess,
|
|
101
|
+
and `NO_COLOR` turns the link off. Either way, Enter prints the full sign-in
|
|
102
|
+
link once. Once you are signed in, that line is replaced by `✓ Signed in`.
|
|
103
|
+
If the browser could not be opened, or with `--no-browser`, the full link
|
|
104
|
+
prints at once. It waits up to 15 minutes, so someone new can create their
|
|
105
|
+
workspace on the way and land back in the same setup. If the server rejects
|
|
106
|
+
a key set in `AMDAHL_KEY` (or `AMDAHL_API_KEY`, `AMDAHL_ACCESS_TOKEN`,
|
|
107
|
+
`--api-key`), it says so and skips the browser sign-in, since that key would
|
|
108
|
+
still win.
|
|
109
|
+
|
|
110
|
+
Then it sets up each client you ticked the way `amdahl install` does, one
|
|
111
|
+
line each. A client that fails prints its error and the rest still run; the
|
|
112
|
+
exit code is the first failure's. Each client then signs in to Amdahl
|
|
113
|
+
itself, once, the first time it connects, and the setup ends with that step
|
|
114
|
+
for every client it set up, on every run: `/mcp` in Claude Code, `codex mcp
|
|
115
|
+
login amdahl` for Codex, and Cursor asks on first use. With more than one:
|
|
116
|
+
|
|
117
|
+
```
|
|
118
|
+
Try it: say "make this email sound less like AI" in any of them.
|
|
119
|
+
Before that, connect each one once:
|
|
120
|
+
Claude Code: run /mcp
|
|
121
|
+
Cursor: sign in when it asks, on first use
|
|
122
|
+
Codex: run `codex mcp login amdahl`
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
`npx amdahl --verbose` also prints the files it wrote, the profile and
|
|
126
|
+
where the sign-in is stored. Run it again once you are set up and it says
|
|
127
|
+
`You're set up in Claude Code and Cursor.` with the same closing lines, and
|
|
128
|
+
asks nothing; if it cannot reach Amdahl to check your sign-in, it still
|
|
129
|
+
says so.
|
|
130
|
+
|
|
131
|
+
### Run by an agent, or with no terminal
|
|
132
|
+
|
|
133
|
+
You can ask Claude Code, Cursor or Codex to run `npx amdahl` for you. With
|
|
134
|
+
no terminal (an agent's shell, a pipe such as `npx amdahl | cat`, or stdin,
|
|
135
|
+
stdout or stderr redirected), and whenever `CLAUDECODE` or `CURSOR_AGENT`
|
|
136
|
+
is set, it sets up without a question and without a browser sign-in:
|
|
137
|
+
|
|
138
|
+
- `CLAUDECODE` set (Claude Code runs it): Claude Code only.
|
|
139
|
+
- `CURSOR_AGENT` set (Cursor runs it): Cursor only.
|
|
140
|
+
- Anything else (Codex sets no variable): every client it finds.
|
|
141
|
+
|
|
142
|
+
In Codex's default sandbox, writes outside the workspace and network access
|
|
143
|
+
are blocked, so the run usually fails (`npx` cannot fetch the package, or
|
|
144
|
+
`Could not update ~/.codex/config.toml`, exit 1) unless you approve the
|
|
145
|
+
escalation Codex asks for, or run `npx amdahl` in your own terminal.
|
|
146
|
+
|
|
147
|
+
Each client signs in on its first connect, over OAuth, so the CLI needs no
|
|
148
|
+
sign-in of its own here. The last lines say how to finish, as above. Run
|
|
149
|
+
from inside Claude Code, the step is "restart Claude Code and run /mcp
|
|
150
|
+
once", since a running session may only see the new server after a
|
|
151
|
+
restart. If
|
|
152
|
+
it finds no client, it says so on stderr, names `npx amdahl install
|
|
153
|
+
claude-code`, writes nothing and exits 1.
|
|
154
|
+
|
|
155
|
+
**Exit code change in 0.3.4.** Before 0.3.4, bare `amdahl` with no terminal
|
|
156
|
+
or with `CLAUDECODE` or `CURSOR_AGENT` set printed the usage and exited 2.
|
|
157
|
+
It now sets up as above and exits 0 (1 when nothing was found or a client
|
|
158
|
+
failed). In CI, with `AMDAHL_NO_PROMPT=1`, or with `--json`, bare `amdahl`
|
|
159
|
+
still changes nothing, exits 2 and prints the usage to stderr, now after one
|
|
160
|
+
line that says why and names `amdahl install`. CI means one of `CI`, `JENKINS_URL`, `TF_BUILD`,
|
|
161
|
+
`CODEBUILD_BUILD_ID`, `TEAMCITY_VERSION`, `GITHUB_ACTIONS`, `GITLAB_CI`,
|
|
162
|
+
`BUILDKITE` or `CIRCLECI` is set (other than `false` or `0`), or
|
|
163
|
+
`BUILD_NUMBER` is set together with `JENKINS_HOME`.
|
|
164
|
+
|
|
165
|
+
When the CLI was started by `npx`, every message that names a command says
|
|
166
|
+
`npx amdahl ...` (for example `npx amdahl login`), since an `npx` user has no
|
|
167
|
+
`amdahl` on their PATH.
|
|
112
168
|
|
|
113
169
|
To connect one AI client yourself, run `amdahl install claude-code` (or `codex`,
|
|
114
170
|
`cursor`). It adds the Amdahl MCP server and also installs the Amdahl skill,
|
|
115
171
|
a map of everything Amdahl can do, so your agent knows which tool fits each
|
|
116
172
|
job. If the client already points at Amdahl, `install` leaves that as it is
|
|
117
|
-
(for Claude Code it skips `claude mcp add` when `
|
|
118
|
-
shows the same URL) and still installs the skill.
|
|
119
|
-
|
|
173
|
+
(for Claude Code it skips `claude mcp add` when `~/.claude.json` or `claude
|
|
174
|
+
mcp get amdahl` shows the same URL) and still installs the skill.
|
|
175
|
+
|
|
176
|
+
For Claude Code it runs `claude mcp add --scope user --transport http amdahl
|
|
177
|
+
https://app.amdahl.ai/mcp`. The desktop app and the IDE extensions often
|
|
178
|
+
leave no `claude` on your PATH, so it also looks in `~/.local/bin`,
|
|
179
|
+
`~/.claude/local`, `/opt/homebrew/bin`, `/usr/local/bin` and npm's global
|
|
180
|
+
bin. If none has `claude`, it writes the same entry into Claude Code's user
|
|
181
|
+
settings itself: `mcpServers.amdahl` set to `{"type": "http", "url":
|
|
182
|
+
"https://app.amdahl.ai/mcp"}` at the top level of `~/.claude.json` (in
|
|
183
|
+
`CLAUDE_CONFIG_DIR` when that is set). It keeps every other key, saves the
|
|
184
|
+
file as it was to `~/.claude.json.amdahl-backup` first, writes the new file
|
|
185
|
+
to a temp file and renames it into place (following a symbolic link), and
|
|
186
|
+
changes nothing when the entry is already there. A file that is not a JSON
|
|
187
|
+
object is left alone (exit 1, `invalid_config`). Cursor's and Codex's config
|
|
188
|
+
files are also written whole through a temp file. A symbolic link at
|
|
189
|
+
`~/.claude.json` is followed to its target, even one not created yet, and
|
|
190
|
+
stays a link. An `mcpServers` that is not a JSON object (an array, say) in
|
|
191
|
+
`~/.claude.json` or `~/.cursor/mcp.json` is left alone with `invalid_config`,
|
|
192
|
+
found before the sign-in. If it cannot write the client's config file, it
|
|
193
|
+
exits 1 with `write_failed` and names the file. The skill goes to the
|
|
194
|
+
client's user skills folder:
|
|
120
195
|
|
|
121
196
|
| client | skill file |
|
|
122
197
|
|---|---|
|
|
@@ -134,7 +209,7 @@ https://docs.amdahl.ai/skills/amdahl/SKILL.md.
|
|
|
134
209
|
## Quick start
|
|
135
210
|
|
|
136
211
|
```sh
|
|
137
|
-
amdahl #
|
|
212
|
+
amdahl # guided setup for Claude Code, Cursor and Codex (an agent can run it too)
|
|
138
213
|
amdahl login # sign in through the browser with your console account
|
|
139
214
|
amdahl whoami # the account, workspace and role you are signed in as
|
|
140
215
|
amdahl status # can this workspace optimize, and what blocks it
|
|
@@ -157,7 +232,8 @@ On a server or in CI, skip `login` and set an API key in `AMDAHL_KEY`.
|
|
|
157
232
|
## Commands
|
|
158
233
|
|
|
159
234
|
```
|
|
160
|
-
amdahl
|
|
235
|
+
amdahl [--no-browser] (guided setup; also: amdahl setup)
|
|
236
|
+
amdahl help (same as --help)
|
|
161
237
|
amdahl login [--workspace <slug>] [--no-browser] [--port <n>] (alias: auth login)
|
|
162
238
|
amdahl logout [--all] (alias: auth logout)
|
|
163
239
|
amdahl whoami [--show-token] (alias: auth status)
|
|
@@ -174,7 +250,9 @@ amdahl skills add <publisher>/<skill> [-g] [--agents] [--force] [--accept-warnin
|
|
|
174
250
|
```
|
|
175
251
|
|
|
176
252
|
Global flags: `--profile`, `--api-url`, `--api-key`, `--json`, `--no-color`,
|
|
177
|
-
`-h`, `-v`. With `--json`, data goes to stdout and messages to
|
|
253
|
+
`--verbose`, `-h`, `-v`. With `--json`, data goes to stdout and messages to
|
|
254
|
+
stderr. An unknown option prints `Unknown option --foo.` and `Run \`amdahl
|
|
255
|
+
--help\`.` (exit 2).
|
|
178
256
|
|
|
179
257
|
## Skills
|
|
180
258
|
|
|
@@ -365,8 +443,8 @@ code shown in the terminal; then the key is printed once and stored nowhere.
|
|
|
365
443
|
| code | meaning |
|
|
366
444
|
|---|---|
|
|
367
445
|
| 0 | ok |
|
|
368
|
-
| 1 | general (`login_timeout`, `state_mismatch`, optimize `ok: false`, a `skills add` refusal) |
|
|
369
|
-
| 2 | usage |
|
|
446
|
+
| 1 | general (`login_timeout`, `state_mismatch`, optimize `ok: false`, a `skills add` refusal, `invalid_config`, bare `amdahl` with no terminal that found no client) |
|
|
447
|
+
| 2 | usage (also bare `amdahl` in CI, with `AMDAHL_NO_PROMPT=1` or with `--json`) |
|
|
370
448
|
| 3 | not signed in (401, `invalid_grant`, no credential) |
|
|
371
449
|
| 4 | forbidden (403, `oauth_required`, `cli_client_required`, `not_admin`) |
|
|
372
450
|
| 5 | no workspace |
|
|
@@ -374,7 +452,7 @@ code shown in the terminal; then the key is printed once and stored nowhere.
|
|
|
374
452
|
| 7 | approval denied, expired or locked out |
|
|
375
453
|
| 8 | network or 5xx |
|
|
376
454
|
| 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
|
|
455
|
+
| 130 | stopped with Ctrl+C (or Esc or `q` in a menu) at a question: "Stopped. Nothing changed." |
|
|
378
456
|
|
|
379
457
|
## Development
|
|
380
458
|
|