Gitlawb
diff --git a/‎docs/aimlapi-setup.md‎
Lines changed: 29 additions & 17 deletions b/‎docs/aimlapi-setup.md‎
Lines changed: 29 additions & 17 deletions
diff --git a/‎src/cli/aimlapiCommand.test.ts‎
Lines changed: 166 additions & 0 deletions b/‎src/cli/aimlapiCommand.test.ts‎
Lines changed: 166 additions & 0 deletions
diff --git a/‎src/cli/aimlapiCommand.ts‎
Lines changed: 101 additions & 0 deletions b/‎src/cli/aimlapiCommand.ts‎
Lines changed: 101 additions & 0 deletions
@@ -4,41 +4,51 @@ OpenClaude connects to [AI/ML API](https://aimlapi.com) through its OpenAI-compa
 
 ## Overview
 
-AI/ML API is an aggregating gateway that exposes many chat models behind a single OpenAI-compatible API. OpenClaude ships a first-class `AI/ML API` provider preset: it stores credentials under `AIMLAPI_API_KEY`, sends the OpenClaude attribution headers, and discovers chat-capable models from the public `/models` catalog. It defaults to `gpt-4o`.
+AI/ML API is an aggregating gateway that exposes many chat models behind a single OpenAI-compatible API. OpenClaude ships a first-class `AI/ML API` provider preset: it uses `AIMLAPI_API_KEY`, sends the OpenClaude attribution headers, and discovers chat-capable models from the public `/models` catalog. It defaults to `gpt-4o`.
 
 ## Prerequisites
 
-None. You don't need to visit <https://aimlapi.com> first — the guided top-up flow below can create an AI/ML API account and issue a key for you. If you already have a key from the dashboard, you can paste it directly instead.
+None. You do not need to visit <https://aimlapi.com> first - the guided top-up flow can create an account and issue a key. If you already have a dashboard key or set `AIMLAPI_API_KEY`, OpenClaude can use that credential instead.
 
-## Option 1 — Interactive (`/provider`)
+## Option 1 - Interactive (`/provider`)
 
 1. Start OpenClaude and run `/provider`.
-2. Choose **aimlapi.com**, then confirm the default model (Step 1 of 2).
-3. Step 2 of 2 — choose how to get an API key:
-   - **Top up and get API key** — enter your AI/ML API email and password (an account is created automatically if you don't have one yet), pick a top-up amount ($20–$10,000) and payment method (card or crypto), complete payment in the browser, and OpenClaude saves the issued key for you.
-   - **Enter existing API key** — paste a key you already have from the AI/ML API dashboard.
+2. Choose **aimlapi.com**.
+3. If aimlapi.com is already configured, choose one of:
+   - **Continue with your saved API key** - validate the saved key or `AIMLAPI_API_KEY`, check its balance, optionally top up a low balance, then choose a model.
+   - **Set up a new key or switch account** - enter the new-user or existing-key flow.
+4. Otherwise choose how to get an API key:
+   - **I am a new user** - enter your email. OpenClaude creates a passwordless account, lets you pick a top-up amount and automatic top-up preference (auto top-up is pre-selected **on** here; toggle it off if you don't want it), opens card checkout, then saves the issued key.
+   - **I already have aimlapi.com key** - paste a key from the dashboard. OpenClaude validates it, checks its balance, and offers an optional API-key top-up when the balance is low.
 
-Either way, the base URL (`https://api.aimlapi.com/v1`) and default model (`gpt-4o`) are filled in automatically.
+For an email that already has an account, AI/ML API sends a 6-digit sign-in code. OpenClaude creates a new API key for that account, checks its balance, and only offers checkout when the balance is low. You can top up or save the key and skip funding for now.
 
-Switch models any time with `/model` — only chat-capable models from the AI/ML API catalog are listed.
+When `AIMLAPI_API_KEY` supplies the credential, OpenClaude uses its runtime value for validation and balance checks but saves an empty credential in the provider profile. The literal environment value is not copied into configuration.
 
-## Option 2 — CLI (`openclaude aimlapi topup`)
+Checkout progress is durable, not just kept for the current session: the payment identity and any issued key are persisted to disk, so a restart resumes the same checkout too. Retrying an ambiguous payment or exchange failure resumes the original partner session instead of creating a second checkout, and if a prior run already paid and exchanged the key, the next run finishes the profile write instead of re-provisioning.
 
-Run the same guided top-up flow non-interactively:
+The key exchange itself is one-shot: it cannot be retried. If payment succeeds and a key is issued but the local recovery receipt for it cannot be saved (for example a locked or read-only config directory), both the CLI and the interactive flow stop rather than risk losing that key silently. The error names the issued key id — open <https://aimlapi.com/app> and rotate that key to recover access, then configure the new key manually.
+
+The base URL (`https://api.aimlapi.com/v1`) and default model (`gpt-4o`) are filled in automatically. Switch models any time with `/model`; only chat-capable models from the AI/ML API catalog are listed.
+
+## Option 2 - CLI (`openclaude aimlapi topup`)
+
+Run the guided account top-up flow from the CLI:
 
 ```bash
-openclaude aimlapi topup --email you@example.com --amount 25 --method card
+openclaude aimlapi topup --email you@example.com --amount 25
 ```
 
-- Credentials: pass `--email` (or set `AIMLAPI_EMAIL`) and set `AIMLAPI_PASSWORD`; if either is missing you're prompted interactively (password entry is hidden).
+- Pass `--email` (or set `AIMLAPI_EMAIL`). Existing accounts also need the emailed 6-digit code: interactive terminals prompt for it (hidden, not echoed); for scripts, pipe it in with `--code-stdin` (reads one line from stdin) — the recommended noninteractive path, since the value never appears in this process's argv or `ps` output. Whether it also avoids shell history depends on how you feed stdin: reading from a file (`--code-stdin < code.txt`) or a secret manager avoids it, but `echo 123456 | openclaude ...` still records that whole pipeline. `AIMLAPI_CODE` has the same caveat — set it through a mechanism that itself avoids shell history (a CI secret, a sourced env file, `systemd`'s `Environment=`), not by typing `AIMLAPI_CODE=123456 openclaude ...` directly. Avoid the deprecated `--code <value>` flag entirely — a plain argument is always visible to other local users via shell history and the process list.
 - `--amount`: top-up amount in USD (min 20, max 10000; defaults to 25).
-- `--method`: `card` (Stripe, default) or `crypto` (NOWPayments).
+- Checkout always uses card payment; there is no separate payment-method step.
+- `--auto-top-up`: enroll the account in automatic top-up at checkout. Off by default here, unlike the interactive flow above, where it's pre-selected on.
 - `--model`: default model id written into the provider profile (defaults to `gpt-4o`).
 - `--no-open`: print the payment URL instead of auto-opening a browser.
 
 The issued key is written into OpenClaude's provider profile automatically once payment clears.
 
-## Option 3 — Environment variables
+## Option 3 - Environment variables
 
 Setting `AIMLAPI_API_KEY` alone is enough; OpenClaude auto-detects the AI/ML API route:
 
@@ -59,12 +69,14 @@ export OPENAI_MODEL="gpt-4o"
 
 ## Verify
 
-- `/status` shows **aimlapi.com** as the active provider with the `https://api.aimlapi.com/v1` base URL.
+- `/status` shows **AI/ML API** as the active provider with the `https://api.aimlapi.com/v1` base URL.
 - `/model` lists chat-capable models discovered from the catalog.
 - Send any prompt to confirm responses come back from the selected model.
 
 ## Notes
 
 - Model discovery uses the public, unauthenticated `GET /models` endpoint and surfaces only chat-completions models; image, audio, embeddings, and other modalities are intentionally not routed through the coding workflow.
-- Requests carry `X-AIMLAPI-Integration-*` attribution headers (owner/repo/version) plus the `HTTP-Referer: OpenClaude` and `X-Title: OpenClaude` headers that AI/ML API uses to attribute integration traffic.
+- Every request to AI/ML API (inference, catalog, sign-in/account, and checkout) carries the two mandatory attribution headers `X-AIMLAPI-Source: agent/openclaude` and `X-AIMLAPI-Partner-ID`. On the canonical `api.aimlapi.com` endpoint the inference/catalog requests additionally send `X-AIMLAPI-Integration-*` (owner/repo/version) plus `HTTP-Referer: OpenClaude` and `X-Title: OpenClaude`; all attribution headers are stripped when a non-canonical (proxy) base URL is configured, so a third-party host never receives OpenClaude's partner identity.
+- `AIMLAPI_AUTH_URL`, `AIMLAPI_APP_URL`, `AIMLAPI_PAY_URL`, and `AIMLAPI_VERIFICATION_BASE_URL` can point the complete flow at another environment. Guided **new-account** onboarding and key provisioning require the canonical `api.aimlapi.com` inference endpoint, so `AIMLAPI_INFERENCE_URL` must be unset (or left at its default) to create a new account and mint its key — a non-canonical value is rejected there. The existing-key top-up path (paste an aimlapi.com key) instead runs against whatever `AIMLAPI_INFERENCE_URL` is configured. `AIMLAPI_RETURN_URL` overrides only the browser landing page.
+- Checkout success is detected by polling. The browser return target is an HTTPS page; OpenClaude does not install a custom URL-scheme handler.
 - Usage (`/usage`) reporting is not supported for this provider.
@@ -0,0 +1,166 @@
+import { expect, mock, test } from 'bun:test'
+import { Command as CommanderCommand } from '@commander-js/extra-typings'
+
+import { registerAimlapiCommand } from './aimlapiCommand.js'
+
+test('aimlapi topup forwards the passwordless CLI contract', async () => {
+  const handler = mock(async () => {})
+  const program = new CommanderCommand().exitOverride()
+  registerAimlapiCommand(program, async () => handler)
+
+  await program.parseAsync([
+    'node',
+    'openclaude',
+    'aimlapi',
+    'topup',
+    '--email',
+    'user@example.com',
+    '--code',
+    '123456',
+    '--auto-top-up',
+    '--no-open',
+  ])
+
+  expect(handler).toHaveBeenCalledWith({
+    email: 'user@example.com',
+    code: '123456',
+    amountUsd: undefined,
+    autoTopUp: true,
+    model: 'gpt-4o',
+    noOpen: true,
+  })
+})
+
+test('aimlapi topup forwards explicit amount and model', async () => {
+  const handler = mock(async () => {})
+  const program = new CommanderCommand().exitOverride()
+  registerAimlapiCommand(program, async () => handler)
+
+  await program.parseAsync([
+    'node',
+    'openclaude',
+    'aimlapi',
+    'topup',
+    '--email',
+    'user@example.com',
+    '--amount',
+    '50',
+    '--model',
+    'gpt-5',
+    '--no-open',
+  ])
+
+  expect(handler).toHaveBeenCalledWith({
+    email: 'user@example.com',
+    code: undefined,
+    amountUsd: '50',
+    autoTopUp: undefined,
+    model: 'gpt-5',
+    noOpen: true,
+  })
+})
+
+test('aimlapi topup defaults to opening the browser when --no-open is absent', async () => {
+  const handler = mock(async () => {})
+  const program = new CommanderCommand().exitOverride()
+  registerAimlapiCommand(program, async () => handler)
+
+  await program.parseAsync([
+    'node',
+    'openclaude',
+    'aimlapi',
+    'topup',
+    '--email',
+    'user@example.com',
+  ])
+
+  expect(handler).toHaveBeenCalledWith(
+    expect.objectContaining({ noOpen: false }),
+  )
+})
+
+test('aimlapi topup --code-stdin reads the code from stdin instead of argv', async () => {
+  const handler = mock(async () => {})
+  const program = new CommanderCommand().exitOverride()
+  registerAimlapiCommand(program, async () => handler)
+
+  const { Readable } = await import('node:stream')
+  const originalStdin = process.stdin
+  const fakeStdin = Readable.from('123456\n') as unknown as typeof process.stdin
+  Object.defineProperty(process, 'stdin', { value: fakeStdin, configurable: true })
+  try {
+    await program.parseAsync([
+      'node',
+      'openclaude',
+      'aimlapi',
+      'topup',
+      '--email',
+      'user@example.com',
+      '--code-stdin',
+      '--no-open',
+    ])
+  } finally {
+    Object.defineProperty(process, 'stdin', { value: originalStdin, configurable: true })
+  }
+
+  expect(handler).toHaveBeenCalledWith(
+    expect.objectContaining({ email: 'user@example.com', code: '123456' }),
+  )
+})
+
+test('aimlapi topup --code prints a deprecation warning steering off argv', async () => {
+  const handler = mock(async () => {})
+  const program = new CommanderCommand().exitOverride()
+  registerAimlapiCommand(program, async () => handler)
+  const stderr = mock(() => true)
+  const originalWrite = process.stderr.write.bind(process.stderr)
+  process.stderr.write = stderr as unknown as typeof process.stderr.write
+  try {
+    await program.parseAsync([
+      'node',
+      'openclaude',
+      'aimlapi',
+      'topup',
+      '--email',
+      'user@example.com',
+      '--code',
+      '123456',
+      '--no-open',
+    ])
+  } finally {
+    process.stderr.write = originalWrite
+  }
+
+  expect(stderr).toHaveBeenCalledWith(expect.stringContaining('shell history'))
+  expect(handler).toHaveBeenCalledWith(
+    expect.objectContaining({ code: '123456' }),
+  )
+})
+
+test('aimlapi topup help text does not encourage the argv --code form', () => {
+  const program = new CommanderCommand().exitOverride()
+  const aimlapi = registerAimlapiCommand(program, async () => async () => {})
+  const topupHelp = aimlapi.commands
+    .find(command => command.name() === 'topup')
+    ?.helpInformation()
+  expect(topupHelp).toBeTruthy()
+  expect(topupHelp).toContain('--code-stdin')
+  expect(topupHelp).toContain('Deprecated')
+  expect(topupHelp).not.toMatch(/--code <code>\s+6-digit code/)
+})
+
+test('aimlapi topup rejects the removed method option', async () => {
+  const program = new CommanderCommand().exitOverride()
+  registerAimlapiCommand(program, async () => async () => {})
+
+  await expect(
+    program.parseAsync([
+      'node',
+      'openclaude',
+      'aimlapi',
+      'topup',
+      '--method',
+      'card',
+    ]),
+  ).rejects.toMatchObject({ code: 'commander.unknownOption' })
+})
@@ -0,0 +1,101 @@
+import { Command as CommanderCommand } from '@commander-js/extra-typings'
+import { createInterface } from 'node:readline'
+
+import {
+  DEFAULT_MODEL,
+  MAX_AMOUNT_USD_MINOR,
+  MIN_AMOUNT_USD_MINOR,
+} from '../integrations/aimlapi/config.js'
+import type { AimlapiTopupOptions } from '../integrations/aimlapi/topup.js'
+
+type AimlapiTopupHandler = (options: AimlapiTopupOptions) => Promise<void>
+type LoadAimlapiTopupHandler = () => Promise<AimlapiTopupHandler>
+
+const loadAimlapiTopupHandler: LoadAimlapiTopupHandler = async () => {
+  const { aimlapiTopup } = await import('./handlers/aimlapi.js')
+  return aimlapiTopup
+}
+
+/**
+ * Read exactly one line from stdin for --code-stdin: a noninteractive way to
+ * supply the passwordless sign-in code that never touches argv (visible to
+ * other local users via shell history and the process list, e.g. `ps` /
+ * `/proc/<pid>/cmdline`) or an env var (visible via `/proc/<pid>/environ`).
+ * Stops at the first line rather than draining to EOF, so a caller piping
+ * more than one value is not silently read past its intended input.
+ */
+async function readOneLineFromStdin(): Promise<string> {
+  const rl = createInterface({ input: process.stdin })
+  try {
+    for await (const line of rl) {
+      return line.trim()
+    }
+    return ''
+  } finally {
+    rl.close()
+  }
+}
+
+/**
+ * Register the `aimlapi` command group (`topup`). The handler is lazily imported
+ * so the heavy top-up flow only loads when the subcommand actually runs; tests
+ * inject `loadHandler` to capture the parsed options without touching the network.
+ */
+export function registerAimlapiCommand(
+  program: CommanderCommand,
+  loadHandler: LoadAimlapiTopupHandler = loadAimlapiTopupHandler,
+): CommanderCommand {
+  const aimlapi = program
+    .command('aimlapi')
+    .description('AI/ML API (aimlapi.com) — top up balance and configure the provider')
+  aimlapi
+    .command('topup')
+    .description(
+      'Use passwordless sign-in, open AI/ML API top-up, then configure OpenClaude',
+    )
+    .option('--email <email>', 'AI/ML API account email (or AIMLAPI_EMAIL env)')
+    .option(
+      '--code <code>',
+      'Deprecated: 6-digit code for an existing account, as a plain argument. This ' +
+        'exposes it to shell history and the process list (`ps`, /proc/<pid>/cmdline) on ' +
+        'the local machine. Prefer --code-stdin for scripts, or the interactive prompt.',
+    )
+    .option(
+      '--code-stdin',
+      'Read the 6-digit code for an existing account from stdin (one line) instead of ' +
+        '--code, so it never appears in this process\'s argv/`ps` output. Whether it also ' +
+        'avoids shell history depends on how you feed stdin (e.g. a file avoids it; ' +
+        '`echo code | ...` does not).',
+    )
+    .option(
+      '--amount <usd>',
+      `Top-up amount in USD (min ${MIN_AMOUNT_USD_MINOR / 100}, max ${MAX_AMOUNT_USD_MINOR / 100})`,
+    )
+    .option('--auto-top-up', 'Enable automatic top-up at checkout')
+    .option(
+      '--model <model>',
+      'Default model id written into the provider profile',
+      DEFAULT_MODEL,
+    )
+    .option('--no-open', 'Do not auto-open the browser; print the payment URL instead')
+    .action(async opts => {
+      if (opts.code) {
+        process.stderr.write(
+          'Warning: --code exposes the sign-in code via shell history and the process ' +
+            'list. Use --code-stdin for scripts, or omit it to be prompted instead.\n',
+        )
+      }
+      const code = opts.codeStdin ? await readOneLineFromStdin() : opts.code
+      const handler = await loadHandler()
+      await handler({
+        email: opts.email,
+        code,
+        amountUsd: opts.amount,
+        autoTopUp: opts.autoTopUp,
+        model: opts.model,
+        noOpen: opts.open === false,
+      })
+    })
+
+  return aimlapi
+}