Docs

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:

bash
npx amdahl

It asks where Amdahl should work:

code
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
  1. 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.
  2. 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.
  3. 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.
  4. It prints the last step for each tool. Do it once:
ToolLast step
Claude CodeRun /mcp once inside Claude Code, and sign in.
CodexRun codex mcp login amdahl, and sign in.
CursorNothing 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:

bash
npm i -g @amdahl/cli
amdahl --version

amdahl and @amdahl/cli are the same tool on npm, so npx amdahl and npx @amdahl/cli do the same thing.

Sign in

bash
amdahl login

Your 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-browser prints 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 login again.

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.

bash
amdahl whoami
amdahl logout

whoami 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

bash
amdahl status

It 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:

BlockerFix
missing_scopeYour credential cannot optimize. Sign in again with amdahl login, or use a Customer agent key.
role_too_lowYou are a Viewer. Ask a workspace admin to make you an Editor or above.
quota_exhaustedThe 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.

bash
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.

FlagWhat it does
--channel email|linkedinSay what the draft is. Left out, it is inferred.
--evidence workspaceAlso evaluate every claim in the draft against your customers' own conversations. Slower.
--on-unsupported flag|removeWhat to do with a claim nothing backs: flag it (default) or remove it.
--triesAlso 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

bash
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

bash
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.

text
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}}
--forToolChannels
instantlyInstantlyEmail
smartleadSmartleadEmail
lemlistlemlistEmail, LinkedIn
heyreachHeyReachLinkedIn
reply_ioReply.ioEmail, LinkedIn
apolloApolloEmail
outreachOutreachEmail
salesloftSalesloftEmail
hubspotHubSpotEmail
lgmLa Growth MachineLinkedIn
woodpeckerWoodpeckerEmail
otherAny tool with a CSV importEmail, 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 and other take both: add --channel email or --channel linkedin, or put the channel in the list's channel column. 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, company and linkedin_url, found by header in any common spelling and named as the tool names them (lemlist firstName and companyName; Instantly and Smartlead company_name). Then come amdahl_subject and amdahl_message (only amdahl_message for 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 as message, draft or body) and the columns Amdahl reads itself (message, channel, evidence, on_unsupported, facts, rules and item_id, matched on the snake_case header, so Item ID too) 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% off subject 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 (--force replaces it). --no-wait prints a pick-up command that carries --for.
  • With --json, the file is still written and no steps are printed. The batch gains send_to with tool, channel, file (null when no lead was ready), ready, left_out and over_limit. With no lead ready, no file is written and the exit code is 1.

Ask about your customers

bash
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

bash
amdahl grade draft.md --evidence workspace

grade 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

bash
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

bash
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

bash
amdahl data
amdahl data --surface deals

data 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

bash
amdahl connections
amdahl connect hubspot
amdahl open

connections 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

bash
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.

  • --provider is lemlist, instantly, outreach, salesloft, hubspot, salesforce, gmail, heyreach, apollo, smartlead, reply_io, lgm, woodpecker, linkedin_manual or other. Use other for 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 and linkedin_manual send LinkedIn only. Every other tool takes both. A prompt run's id (opt_...) cannot be reported as sent or given feedback.
  • --channel is email, linkedin_invite, linkedin_message or linkedin_inmail. linkedin is also accepted and means linkedin_message, as it does for amdahl optimize --channel.
  • --sent-as edited needs --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:

bash
amdahl keys create --name "CI optimizer" --preset agent --expires 90d
  1. The CLI makes the key on your machine and sends the server only a hash of it.
  2. It shows a code such as BCDF-GHJK and opens the console approval page.
  3. On that page, check the details (workspace, key name, access, expiry, device), type the code from your terminal and click Approve.
  4. 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.

--presetAccess
read-only (default)Read only: search and reads, no changes.
agentCustomer agent: reads, optimize (write and evaluate) and chats.
internal, adminThe admin levels. Workspace admins only.

--expires is 30d, 90d (default) or 365d.

bash
amdahl keys list
amdahl keys revoke amdhl_1a2b3c4d

keys 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

bash
amdahl install claude-code
amdahl install codex
amdahl install cursor

Each 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:

  1. --api-key <key>
  2. AMDAHL_KEY
  3. AMDAHL_API_KEY
  4. AMDAHL_ACCESS_TOKEN
  5. Your browser sign-in (--profile, then AMDAHL_PROFILE, then your default)

amdahl keys and amdahl auth token need the browser sign-in.

VariableWhat it does
AMDAHL_API_URLThe API to talk to. Default https://app.amdahl.ai.
AMDAHL_CONSOLE_URLThe console that messages point you to, for example when you have no workspace yet. Default https://console.amdahl.ai.
AMDAHL_PROFILEWhich signed-in workspace to use.
AMDAHL_NO_PROMPT=1Never 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_STOREkeychain or file, to force where sign-in tokens are kept.
NO_COLORTurn 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:

CaseWhat it printsExit 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 codeMeaning
0Success.
1General 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.
2The command was used wrongly.
3Not signed in, or the sign-in expired.
4Not allowed: scope, role, or a command that needs the browser sign-in. Also research that started, but that your credential cannot read back.
5No workspace.
6Rate limited, or out of quota.
7The key request was denied, expired or locked.
8Network error or a server error. Your sign-in is kept.

See also