# Command line (CLI)

Sign in from your terminal, check your setup, optimize drafts from files, create and revoke API keys with approval in the browser, and connect Claude Code, Codex or Cursor in one command.

The `amdahl` command line tool signs in to your workspace in the browser, then
lets you check your setup, optimize drafts, manage API keys and connect your AI
clients from a terminal. It never stores an API key, and it prints a secret only
when you ask for one.

## Install

Requires Node.js 20 or later. Run it once with no install:

```bash
npx @amdahl/cli login
```

Or install the `amdahl` command, which the rest of this page uses:

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

## 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 the optimizer 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:

| 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 when they reset. |

## Optimize drafts

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

| Flag | What it does |
| --- | --- |
| `--channel email\|linkedin` | Say what the draft is. Left out, it is inferred. |
| `--evidence workspace` | Also check the draft's claims against your own customer 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](/cookbooks/keep-your-voice-rules-and-facts). |

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

| `--preset` | Access |
| --- | --- |
| `read-only` (default) | Read only: search and reads, no changes. |
| `agent` | Customer agent: reads, optimize, evals and chats. |
| `internal`, `admin` | The 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.
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.

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

| 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. Also on when input is not a terminal. |
| `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.

## 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. |
| `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. |
| `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](/skills/amdahl/SKILL): one map of every job, with its MCP tool, CLI command and endpoint, for you and your agent.
- [Authentication](/authentication): keys, OAuth tokens and scopes.
- [Connect your agent](/mcp/connect-agent): connect from inside a client instead.
- [Message Optimizer](/endpoints/message-optimizer): every request and response field.