Command line (CLI)
Run npx amdahl to set up Claude Code, Cursor or Codex with one sign-in. Then, from your terminal, check your setup, optimize or grade one draft, optimize a whole list, grade or improve a prompt, ask about your customers, connect data, say what happened to a message, and create and revoke API keys with approval in the browser.
The amdahl command line tool sets up Amdahl in your AI tools with one
command. It also signs in to your workspace in the browser, then lets you check
your setup, optimize one draft or a whole list, ask about your customers,
connect data, say what happened to a message and manage API keys from a
terminal. It never stores an API key, and it prints a secret only when you ask
for one.
Guided setup
Requires Node.js 22 or later. Run this in a terminal, with nothing after it:
npx amdahlIt asks where Amdahl should work:
Amdahl · predictive ML for GTM
Where should Amdahl work?
> [x] Claude Code found on your machine
[ ] Cursor
[ ] Codex
↑↓ move · Space tick/untick · Enter to install- The tools it found on your computer are already ticked. Use the arrow keys to move and Space to tick or untick a tool. If it finds none, it says so, and you tick the ones you use.
- Press Enter. Your browser opens once to sign you in with your work email. That one sign-in covers every tool you ticked. If you are already signed in, it skips this step.
- It adds Amdahl to each tool you ticked, and to each one it also adds the Amdahl skill, so your agent knows which Amdahl tool fits each job.
- It prints the last step for each tool. Do it once:
| Tool | Last step |
|---|---|
| Claude Code | Run /mcp once inside Claude Code, and sign in. |
| Codex | Run codex mcp login amdahl, and sign in. |
| Cursor | Nothing to run. Cursor asks you to sign in the first time it uses Amdahl. |
Run npx amdahl again at any time. If you are already set up, it says so,
prints the last step for each tool again, and changes nothing. If you are also
signed in in this terminal, it ends with what to try next: amdahl optimize,
amdahl search, amdahl connect and amdahl open.
Signed in with a personal email? Amdahl needs your work email. The browser and the terminal say so and link a new sign-in. The terminal keeps waiting, so the setup finishes in the same run.
Want only one tool? npx amdahl install claude-code (or codex,
cursor) sets up that one tool, with no menu. See
Connect your AI clients.
When an agent runs it
Your coding agent can run npx amdahl for you. With no terminal to draw a
menu in, it does not ask anything and does not open a browser:
- Run by the Claude Code or Cursor agent, it sets up that tool only.
- Run any other way without a terminal, for example by Codex, it sets up every tool it finds on the computer.
Each tool signs in itself the first time it connects. The last line names the step to do, as in the table above.
In CI, or with AMDAHL_NO_PROMPT=1, npx amdahl with nothing after it sets
up nothing. It prints how to use the CLI and exits with code 2.
Install
Every command on this page also runs with no install: put npx in front, for
example npx amdahl login. To install the amdahl command, which the rest of
this page uses:
npm i -g @amdahl/cli
amdahl --versionamdahl and @amdahl/cli are the same tool on npm, so npx amdahl and
npx @amdahl/cli do the same thing.
Sign in
amdahl loginYour browser opens the Amdahl sign-in page. Enter your work email and the one-time code we send you. When the browser says "Signed in. You can close this tab.", the terminal is signed in too.
- Several workspaces? Pick one with
amdahl login --workspace <slug>. A member signs straight in to that workspace, with no consent screen. - No browser on this machine?
amdahl login --no-browserprints the URL to open somewhere else. The sign-in still returns to this machine, so open it on the same computer, for example through an SSH port forward. - No workspace yet? The terminal tells you where to go. If you are approved
for the beta, create a workspace at console.amdahl.ai/new. If not, join the
waitlist at the same address, or try Amdahl meanwhile at
console.amdahl.ai/try. Then run
amdahl loginagain.
The sign-in grants three things only: searching and reading (data:read),
reading your connections (connections:read) and optimizing drafts
(messages:execute). Sign-in tokens live in your operating system's keychain
(macOS Keychain or the Linux secret service). Where no keychain is available,
they go in a file only you can read, and the CLI warns you once.
amdahl whoami
amdahl logoutwhoami shows who you are, which workspace, your role, and where the credential
came from. logout revokes this sign-in and forgets it (--all for every
workspace).
logout always forgets the sign-in on this machine. If the server cannot revoke
a sign-in's tokens, it names that sign-in (not_revoked in --json output),
and those tokens stay valid until they expire.
Check your setup
amdahl statusIt shows your workspace, your role, whether you can optimize drafts and how many optimizations are left this month, and any data connection that needs attention. When optimizing is blocked, it names the fix:
| Blocker | Fix |
|---|---|
missing_scope | Your credential cannot optimize. Sign in again with amdahl login, or use a Customer agent key. |
role_too_low | You are a Viewer. Ask a workspace admin to make you an Editor or above. |
quota_exhausted | The workspace used this month's optimizations. It shows the day they reset. |
With no data connected, it says so and names amdahl connect. A connection
that needs attention gets a link to its page in the console (the Connections
page when several do).
Optimize drafts
Amdahl writes from context. Each file is sent as a draft. With a --context file that holds facts or rules, the draft is the starting point: the message keeps what it says and its voice, the facts add to it and the rules shape it. A file sent with no --context is improved, with a draft_improved_no_context note. Put what you know about the recipient in the --context file as facts.
amdahl optimize draft.md
amdahl optimize step1.md step2.md step3.md --channel email
pbpaste | amdahl optimize -Each file is one draft. Files run one after another, each with up to 180 seconds to finish. The output is the version Amdahl returns, exactly as returned, with one line on why it changed or why your draft was kept.
| Flag | What it does |
|---|---|
--channel email|linkedin | Say what the draft is. Left out, it is inferred. |
--evidence workspace | Also evaluate every claim in the draft against your customers' own conversations. Slower. |
--on-unsupported flag|remove | What to do with a claim nothing backs: flag it (default) or remove it. |
--tries | Also show every version the run scored on the way. |
--context <file.json> | Your rules, voice_examples and facts, as a JSON file. See Keep your voice, rules and facts. |
Each run ends with its run id (Run: ...), which amdahl feedback and
amdahl sent take. Two lines then give those two commands to paste, with the
run id filled in and the flags each needs as placeholders: replace each
<placeholder> before you run one. On a workspace with no data connected, a
line says that connecting calls or a CRM lets Amdahl evaluate claims against
them, and names amdahl connect.
With --json, the output is {"ok", "file", "result"}. The message Amdahl
wrote is .result.message, and the run id is .result.run_id. Several files
give an array of those.
A whole list
amdahl optimize --list drafts.csv
amdahl optimize --list drafts.jsonl --channel email--list sends every message in the file as one batch,
which runs on spare capacity and is never refused as busy, and waits until it
completes, with progress in the terminal. A CSV file has a header row with a
message column, and may have item_id, channel, evidence,
on_unsupported, facts and rules (one fact or rule per line in the cell;
a channel is read in any case, so LinkedIn is linkedin).
Any other column, such as a CRM export's Company or Email, is not sent: one
line names it, and it is copied to the results in its place. The CLI refuses
only a list with no message column, or one with a column it reads twice. A
JSONL file has one batch item per line, with any field a single optimize
takes. The flags above apply to every message that does not set its own.
The results go next to the list: drafts.csv gets drafts.optimized.csv,
with every column you sent, in its original order, then optimized_message,
status, summary, run_id and error. A column of yours with one of those
names keeps it, and Amdahl's column takes amdahl_ in front. The summary
cell says the message was checked against your facts and rules only when you
sent some: for a message with neither, it is empty. A cell that starts with
=, +, - or @ starts with a ' there, so a spreadsheet does not run it
as a formula. That includes a phone number such as +1 555 0100 copied
through from your own columns: delete the ' to use the value. The CLI does
not replace a results file that exists unless you add --force. With
--json, the results go to standard output instead.
A batch takes up to 500 messages. --no-wait only queues the batch and
prints the command that picks it up later (--batch <id>, with the same
list). Ctrl+C stops the wait, not the batch.
Send a list to your sequencer
amdahl optimize --list drafts.csv --for lemlist --channel email--for <tool> also writes the messages Amdahl wrote as a file that tool
imports, next to the results, and prints three steps: where to import it, what
to map, and what to paste into the step. The file is <list>-<tool>.csv, so
drafts.csv for lemlist gets drafts-lemlist.csv. The console's Send to
writes the same file for the same list. You import the file into your tool:
The CLI writes only this file, and Amdahl emails no one. In the console, Send to can add the
leads to a campaign you pick in a connected sequencer.
Results: drafts.optimized.csv
Import file for lemlist: drafts-lemlist.csv
38 messages ready for lemlist. 2 left out: 1 failed, 1 with no email.
1. Import: In your campaign, open Leads list > Import new leads > CSV.
2. email and the name columns map on their own. amdahl_subject and
amdahl_message become custom variables.
3. Paste into your step: Subject {{amdahl_subject}}, Body {{amdahl_message}}--for | Tool | Channels |
|---|---|---|
instantly | Instantly | |
smartlead | Smartlead | |
lemlist | lemlist | Email, LinkedIn |
heyreach | HeyReach | |
reply_io | Reply.io | Email, LinkedIn |
apollo | Apollo | |
outreach | Outreach | |
salesloft | Salesloft | |
hubspot | HubSpot | |
lgm | La Growth Machine | |
woodpecker | Woodpecker | |
other | Any tool with a CSV import | Email, LinkedIn |
Gmail and Outlook send from a mailbox, so they have no import file.
- One channel per file. A tool that takes one channel needs no
--channel. lemlist, Reply.io andothertake both: add--channel emailor--channel linkedin, or put the channel in the list'schannelcolumn. A list with both channels is refused. - Only leads Amdahl wrote. A lead that failed, needed input or was not written is left out. So is one with no email, or no LinkedIn URL for a LinkedIn file; HeyReach also needs a first and a last name. The line after the count says how many and why.
- Your columns. The file has your
email,first_name,last_name,companyandlinkedin_url, found by header in any common spelling and named as the tool names them (lemlistfirstNameandcompanyName; Instantly and Smartleadcompany_name). Then comeamdahl_subjectandamdahl_message(onlyamdahl_messagefor LinkedIn), then every other column of your list, in its order, as lowercase snake_case. The column the message came from (the first whose header names a draft, such asmessage,draftorbody) and the columns Amdahl reads itself (message,channel,evidence,on_unsupported,facts,rulesanditem_id, matched on the snake_case header, soItem IDtoo) are not in the file. Your tool imports a value as it is, so no cell gets the'guard that the results file has: a-20% offsubject or a+1 415...phone number arrives as written. - Checked first. Before anything is queued, a list the tool cannot import
exits
2: no email column for an email file, no LinkedIn URL column for a LinkedIn one, a JSONL list, or a file that already exists (--forcereplaces it).--no-waitprints a pick-up command that carries--for. - With
--json, the file is still written and no steps are printed. The batch gainssend_towithtool,channel,file(null when no lead was ready),ready,left_outandover_limit. With no lead ready, no file is written and the exit code is1.
Ask about your customers
amdahl search "What objections came up in lost deals last quarter?"It prints a short answer, then the rows it came from. Each row shows its
company or title and its date, with the quote under it. If the rows do not
answer the question, it says "Amdahl couldn't answer that from these rows" and
suggests rephrasing the question or running amdahl connections to see
whether your data is synced. With no rows, it says why in the server's own
words, then how fresh the data is, and "No matches." only when the server said
nothing. For a why or compare question that comes back empty or unsupported, it
adds one next step: --research (it needs a Customer agent key), or name the
company exactly. --json prints the full search answer
with every row.
A search the server cut at its deadline, or could not read, is not "no
matches". The CLI says it ran out of time, suggests --research, which can run
longer, and exits with code 1; with --json it prints the answer with
ok: false. Rows that came back before the cut are shown, with a note, and exit
0.
The CLI sends your question as you typed it. A time window such as "last month" is read from the words of the question, as on the search page. The request has no separate field for a window.
For a question one search cannot answer, add --research. Search starts a
research job, and the CLI waits for its cited answer.
Search also starts one by itself for a statistical question. Research needs a
Customer agent key (amdahl keys create --preset agent, used as
AMDAHL_KEY). With your browser sign-in, the CLI says first that research
needs a Customer agent key, and then prints the search answer.
When research starts, the CLI prints its id. amdahl search --research-id <id>
reads a job started earlier and waits for it; it needs a Customer agent key too.
An id that is no job of your workspace says "No research job with that id in
this workspace."
amdahl recipes lists the console's recipe library: the same questions the
console asks as a search. Run one with amdahl search --recipe <id>, and give
its fill-in as a flag, such as --account "Acme" (a fill-in is --account,
--products, --messages or --objection, at most 300 characters).
The research answer prints first. Under Details: the CLI then prints what the
answer rests on, in the order the job presented it. A table prints as a plain
table that fits 80 columns. A long cell wraps, and a table with too many
columns prints each row as label: value lines, so no column is dropped.
Quotes and figures print as plain text. A chart, and any block type the CLI
does not know, prints one line that points to --json.
With no data connected, it says so, links the console page that fixes it, and
names amdahl connect.
Grade a message
amdahl grade draft.md --evidence workspacegrade grades a draft and writes nothing: it calls
messages.optimize with mode: "grade".
The file is the message, - reads standard input, and with no file, at a
terminal, you paste it. It takes --channel, --evidence and --context.
It prints the score as the API returns it, always with the five lines it rests
on and a verdict and reason for each. A line that could not be evaluated says
"Not evaluated" and is not a fail. Without --evidence workspace, only the
ask is evaluated and the other lines say "Not evaluated: evidence was off". The
headline says how many lines the score rests on: "Grade 5 of 5, on 1 of the 5
lines (1 of 1 line passed)." When no line could be evaluated it prints "Not graded.", never 0. Every grade says it
is one reading and does not predict replies; it says "and your evidence" only
when evidence was used. A key that cannot optimize is
refused with "This credential cannot grade." --json prints
{ok, file, result}, with the grade in result.grade.
Grade or improve a prompt
amdahl prompt prompt.md --recipients recipients.json
amdahl prompt prompt.md --mode grade
amdahl prompt --run <id>prompt grades or improves a reusable prompt by the emails it writes
(messages.optimize_prompt).
--mode improve (the default) returns a revised prompt only when it wrote
better email on recipients held out of the revising; --mode grade grades
each email. --recipients is a JSON file of 1 to 6 sample recipients
(improve needs two or more); left out, Amdahl picks accounts from your
workspace. A run takes minutes: the CLI prints its id and waits, --no-wait
stops after starting it, and --run <id> reads it later. The revised prompt
goes to standard output and the report to standard error. A lift is printed
only when it is reportable, in points, to one decimal. A revision that was not
kept says so with its mean and the gap: "The revision averaged 3.7 of 5, 1.3
points lower, not kept." When a revision scored higher but Amdahl did not
keep it (for example, it left unfilled placeholders in the held-out emails),
the report says so and prints Amdahl's note, and your prompt stays as it is.
Neither mode predicts replies.
Your runs
amdahl runs
amdahl run <run-id>run shows one optimize run you made: your draft, then the message Amdahl
returned and what it left out
(messages.get_run). Only the person who made
a run can open it. The API does not return a run's grade, so run on a run
made as a grade says the grade is not stored (grade the draft again with
amdahl grade). The API has no list of your runs, so runs lists the ones
this computer made, and it says so: the CLI keeps each run's id, time, kind
and channel (the last 50) in runs.json next to its config, never any text. A
run made with an API key is kept under the key's display prefix (the same first
14 characters keys list shows, never the secret), and a key lists only its own
runs; a sign-in lists its own. A run made in the console or an AI client is not
listed, but its id opens with amdahl run. A prompt run is read with
amdahl prompt --run <id>, and runs says so under its list.
What your workspace holds
amdahl data
amdahl data --surface dealsdata shows each surface's row count and the span of its dates
(search.overview),
then the fields a search can filter on (search.fields). A count that could not
be read says "unknown", never 0. --surface lists one surface's fields with
their type, the first sentence of their meaning and known values. Lines fit the
terminal's width, 80 at most (COLUMNS is honored).
Connect your data
amdahl connections
amdahl connect hubspot
amdahl openconnections lists the sources this workspace has connected, with each one's
health and last sync, and links the page that fixes one that needs attention.
connect looks the connector name up in the catalog, then opens the console's
add page with that connector in its search box. You pick it there and sign in to that tool.
With no name, the search box is empty. open opens your workspace in the
console. If that connector is already connected and healthy, connect says so
first and prints the add page instead of opening it. A connection that needs
attention gets its own page. They open the browser only for a person at a
terminal. With
--no-browser, --json, an agent, CI, or when stdin or stdout is not a
terminal (amdahl connect hubspot | cat), they print the link instead.
Say what happened to a message
amdahl feedback <run-id> --evidence did_it_myself --outcome used_with_edits --sent-text sent.txt
amdahl sent <run-id> --provider gmail --channel email --sent-as edited --provider-send-id "<[email protected]>"feedback tells Amdahl what happened to the message a run returned:
--outcome (used, used_with_edits, not_used, unsure), --comment, or
--sent-text (a file, or - for standard input), and always --evidence
(did_it_myself, reported_to_me or inferred). Amdahl learns your
preferences from an edit, unless the evidence is inferred.
At a terminal, feedback and sent ask for what you left out, with a default
for each and at most three questions: where it went out, who it went to, and
whether you changed it first. Press Enter to take a question's default. At
"changed it?", Enter means you sent it as returned, and a pasted text means you
edited it. The tool question is a menu of tool names. A recipient must be an
email address or a LinkedIn profile URL: a name such as priya is asked for
once more, then refused. Without --channel the channel comes from the
recipient (an email address is email, a LinkedIn profile is
linkedin_message), then the run's channel, then the one kind a tool sends.
Only when none of these says (a tool that sends both, a send id and no
recipient) it asks what was sent: Email, LinkedIn message, LinkedIn invite or
LinkedIn InMail. A question is asked only when there is a terminal
to read the answer and to show it. With --json, in an agent, in CI, with
output piped or with AMDAHL_NO_PROMPT=1, nothing is asked and a missing flag
exits with code 2. After an optimize at a terminal, the next-step lines
are the short commands, amdahl sent <run-id> and amdahl feedback <run-id>;
anywhere else they are written out in full, with every flag.
sent is for the system that sent the message: it
reports the send. --provider,
--channel and --sent-as are required, and --sent-at defaults to now.
--providerislemlist,instantly,outreach,salesloft,hubspot,salesforce,gmail,heyreach,apollo,smartlead,reply_io,lgm,woodpecker,linkedin_manualorother. Useotherfor a sender that is not on the list. A tool and a channel that cannot go together are refused before anything is sent: Instantly and Gmail send email only, and HeyReach andlinkedin_manualsend LinkedIn only. Every other tool takes both. A prompt run's id (opt_...) cannot be reported as sent or given feedback.--channelisemail,linkedin_invite,linkedin_messageorlinkedin_inmail.linkedinis also accepted and meanslinkedin_message, as it does foramdahl optimize --channel.--sent-as editedneeds--sent-text, the message as you sent it (a file, or-for standard input), and it must not be empty. Amdahl keeps only a hash of the text.
Amdahl stores a report only when it can tell which send it is, so give at
least one of --provider-send-id (the provider's own id; for Gmail, the
Message-ID header with its angle brackets) and a recipient: --recipient (an
email address, or a LinkedIn profile URL for a LinkedIn channel) or
--recipient-key-hash, never both. A send id with a recipient is fine. Without
either, or with both a recipient and a hash, the CLI exits with code 2 before
it sends anything. --sent-at needs an uppercase T and Z, for example
2026-11-12T09:30:00Z. The CLI counts a text's length as the server does, so
an emoji counts as two characters. The command reports one send, and a run id
given twice is refused. To report many at once, call
POST /messages/report_send, which takes up to 100.
API keys for servers and CI
A server or a CI job cannot sign in through a browser, so it needs an API key. The CLI creates one without the key ever passing through a browser, and only after you approve it in the console:
amdahl keys create --name "CI optimizer" --preset agent --expires 90d- The CLI makes the key on your machine and sends the server only a hash of it.
- It shows a code such as
BCDF-GHJKand opens the console approval page. - On that page, check the details (workspace, key name, access, expiry, device), type the code from your terminal and click Approve.
- The terminal prints the key once. Store it in your secret manager as
AMDAHL_KEY. The CLI does not keep a copy.
The request expires after 10 minutes. Five wrong codes deny it.
--preset | Access |
|---|---|
read-only (default) | Read only: search and reads, no changes. |
agent | Customer agent: reads, optimize (write and evaluate) and chats. |
internal, admin | The admin levels. Workspace admins only. |
--expires is 30d, 90d (default) or 365d.
amdahl keys list
amdahl keys revoke amdhl_1a2b3c4dkeys list shows your workspace's keys, without their secrets. keys revoke
asks you to type the key name, then approve in the console.
Creating and revoking keys always needs your browser sign-in and an approval in the console. A key cannot create or revoke another key.
Connect your AI clients
amdahl install claude-code
amdahl install codex
amdahl install cursorEach adds the Amdahl MCP server (https://app.amdahl.ai/mcp) to that client,
and the Amdahl skill to the client's skills folder. None of them writes a key
or token: the client signs in over OAuth itself the first time it connects.
For Codex the CLI also sets required = true. Add --print to see the change
without making it. To set up several clients with one sign-in, use
Guided setup.
Credentials and environment
The CLI uses the first credential it finds, in this order, and amdahl whoami
says which one won:
--api-key <key>AMDAHL_KEYAMDAHL_API_KEYAMDAHL_ACCESS_TOKEN- Your browser sign-in (
--profile, thenAMDAHL_PROFILE, then your default)
amdahl keys and amdahl auth token need the browser sign-in.
| Variable | What it does |
|---|---|
AMDAHL_API_URL | The API to talk to. Default https://app.amdahl.ai. |
AMDAHL_CONSOLE_URL | The console that messages point you to, for example when you have no workspace yet. Default https://console.amdahl.ai. |
AMDAHL_PROFILE | Which signed-in workspace to use. |
AMDAHL_NO_PROMPT=1 | Never ask a question; fail instead. A command run without a terminal never asks either. With this variable (or CI) set, npx amdahl alone prints how to use the CLI and sets up nothing. |
AMDAHL_CREDENTIAL_STORE | keychain or file, to force where sign-in tokens are kept. |
NO_COLOR | Turn off colour. |
One sign-in is one workspace. amdahl workspace list shows your sign-ins and
amdahl workspace use <profile> picks the default.
Help and errors
amdahl <command> --help (also -h, or amdahl help <command>) prints that
command's usage and nothing else. amdahl keys --help lists the keys
commands.
A refused credential, and a file that is not there, each print a plain sentence:
| Case | What it prints | Exit code |
|---|---|---|
| The credential lacks a scope | "This credential cannot optimize. Use a Customer agent key, or run amdahl login again." (the verb names the call) | 4 |
| A key the server will not take | "This key isn't valid (revoked or expired)." It says "token" for an access token in AMDAHL_ACCESS_TOKEN, and "Your sign-in is no longer valid." for a saved sign-in. | 3 |
| A file is not there | "Can't find <file>." This covers a draft, a list, --context and --sent-text. | 2 |
With --json, only the message changed: error.code is still the code the
server sent, and error.hint is the same, so a script can branch on them.
Scripts and JSON
Add --json to any command. Data goes to standard output as one JSON object
with "ok": true, and messages go to standard error. A failure prints
{"ok": false, "error": {"code", "message"}}.
| Exit code | Meaning |
|---|---|
0 | Success. |
1 | General failure, for example the sign-in timed out, a message in a list failed, no lead was ready for --for, or a send was not stored. |
2 | The command was used wrongly. |
3 | Not signed in, or the sign-in expired. |
4 | Not allowed: scope, role, or a command that needs the browser sign-in. Also research that started, but that your credential cannot read back. |
5 | No workspace. |
6 | Rate limited, or out of quota. |
7 | The key request was denied, expired or locked. |
8 | Network error or a server error. Your sign-in is kept. |
See also
- What Amdahl can do: one map of every job, with its MCP tool, CLI command and endpoint, for you and your agent.
- Authentication: keys, OAuth tokens and scopes.
- Connect your agent: connect from inside a client instead.
- Optimize a message: every request and response field.