7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.
TypeScript
feat(cli): add provider key management (#1276)
y88c191cf3354
diff --git a/README.md b/README.mdindex 47ae469b..3cd94462 100644--- a/README.md+++ b/README.md@@ -212,6 +212,8 @@ npx freellmapi setup-claude --url http://localhost:3001 --api-key <unified-key>Every generator supports `--dry-run`, creates a timestamped backup before changing an existing file, and merges into the user's configuration. Launchers keep credentials out of config files entirely: `npx freellmapi launch` for Claude Code and `npx freellmapi launch-codex` for Codex.+Provider keys can be managed from the terminal too, with a dashboard session token (`FREELLMAPI_DASHBOARD_TOKEN` or `--token`): `npx freellmapi keys add|list|remove|test <platform>`, where `keys test` re-checks stored keys. See [cli/README.md](cli/README.md#provider-keys).+| Agent | Automated setup | Base URL || --- | --- | --- || Claude Code | `setup-claude` | root |diff --git a/cli/README.md b/cli/README.mdindex 43829f52..9f45e3c0 100644--- a/cli/README.md+++ b/cli/README.md@@ -36,6 +36,7 @@ dashboard (or the tray popover in the desktop app).| `launch` | Run Claude Code with credentials injected into the child process || `launch-codex` | Run Codex the same way || `list` | Print the supported tools and their base URLs |+| `keys` | Add, list, remove, or test provider keys (`keys --help`) |## Options@@ -49,6 +50,48 @@ dashboard (or the tray popover in the desktop app).`FREELLMAPI_URL` and `FREELLMAPI_API_KEY` work in place of `--url` / `--api-key`.+## Provider keys++The `keys` commands use a **dashboard session token**. Set+`FREELLMAPI_DASHBOARD_TOKEN`, or pass `--token TOKEN` to override it. This is the+session returned by dashboard sign-in (stored in the signed-in browser's local+storage as `freellmapi_dashboard_token`). The unified `--api-key` /+`FREELLMAPI_API_KEY` used by coding agents cannot authenticate these commands.+The CLI does not log in or persist the dashboard token.++```bash+export FREELLMAPI_URL=http://localhost:3001+export FREELLMAPI_DASHBOARD_TOKEN='<dashboard-session-token>'++npx freellmapi keys add groq # hidden provider-key prompt+npx freellmapi keys add groq --key '<key>' # non-interactive alternative+npx freellmapi keys list+npx freellmapi keys test groq # check every stored Groq key+npx freellmapi keys test groq --id 7 # check one key+npx freellmapi keys remove groq --id 7+```++`keys list` prints each key's ID, platform, enabled chat model count,+enabled/disabled state, and stored health status. Counts respect the key's model+scope; custom keys count models registered to their endpoint. Credentials and+masked keys are never printed. Use the IDs from this list when a platform has+multiple keys: `remove` requires `--id` in that case, and also checks that the ID+belongs to the requested platform. With one matching key, `--id` is optional.++`add` saves the key and immediately validates it through the gateway. A failed or+inconclusive check exits with code 1 and **leaves the key saved** for later testing+or removal. `test` also exits with code 1 if any selected key is not healthy or the+gateway cannot confirm its validity (for example, after a provider network+failure). Successful commands exit with code 0; argument, authentication, and+request errors exit with code 1. Validation uses the gateway's usual health+checks, including its policy of disabling a key after repeated confirmed failures.++Keyless providers skip the prompt. Custom endpoints need a URL and model+registration, so create them in the dashboard; existing custom keys can be+listed, tested, and removed here. Requests accept `--url` / `FREELLMAPI_URL` and+`--timeout MS` (30,000 ms per request by default). `--dry-run` is not supported for+`keys`; it is rejected before any request.+## SafetyEvery generator is non-destructive: it merges into your existing configurationdiff --git a/cli/package.json b/cli/package.jsonindex 4d9911e2..792fd087 100644--- a/cli/package.json+++ b/cli/package.json@@ -40,6 +40,8 @@"dist/config-files.d.ts","dist/doctor.js","dist/doctor.d.ts",+ "dist/keys.js",+ "dist/keys.d.ts","dist/models.js","dist/models.d.ts","dist/tools.js",diff --git a/cli/src/index.ts b/cli/src/index.tsindex 50101984..78fbafa2 100644--- a/cli/src/index.ts+++ b/cli/src/index.ts@@ -10,19 +10,13 @@ import { applyGeneratedFiles, printDryRunDiff } from './config-files.js';import { getTool, tools } from './tools.js';import { resolveLaunchModel, type ResolvedModel } from './models.js';import { DOCTOR_TOOLS, diagnose, exitCodeFor, formatReport, type ToolReport } from './doctor.js';+import { keysHelp, runKeys, type KeyCommandOptions } from './keys.js';import type { CatalogModel, GenerateContext } from './types.js';-interface CliOptions {- url: string;+interface CliOptions extends KeyCommandOptions {apiKey?: string;profile: string;model?: string;- dryRun: boolean;- /** `doctor --timeout`: how long to wait for the /livez probe. */- timeoutMs?: number;- /** Positional arguments after the command. Only `doctor` takes any; every- * other command still rejects a second positional as it always has. */- args: string[];}function rootUrl(url: string): string {@@ -57,6 +51,7 @@ export function parseArgs(argv: string[]): { command?: string; options: CliOptioconst options: CliOptions = {url: process.env.FREELLMAPI_URL || 'http://localhost:3000',apiKey: process.env.FREELLMAPI_API_KEY,+ token: process.env.FREELLMAPI_DASHBOARD_TOKEN,profile: 'default',dryRun: false,args: [],@@ -79,11 +74,14 @@ export function parseArgs(argv: string[]): { command?: string; options: CliOptiooptions.dryRun = true;continue;}- const [flag, inline] = arg.split('=', 2);+ const equals = arg.indexOf('=');+ const flag = equals < 0 ? arg : arg.slice(0, equals);+ const inline = equals < 0 ? undefined : arg.slice(equals + 1);const value = inline ?? argv[index + 1];if (flag === '--url' || flag === '--api-key' || flag === '--profile'|| flag === '--model' || flag === '--timeout'+ || flag === '--token' || flag === '--key' || flag === '--id') {if (inline === undefined) index += 1;if (!value || (inline === undefined && value.startsWith('-'))) {@@ -93,6 +91,14 @@ export function parseArgs(argv: string[]): { command?: string; options: CliOptioelse if (flag === '--api-key') options.apiKey = value;else if (flag === '--profile') options.profile = validateProfile(value);else if (flag === '--timeout') options.timeoutMs = parseTimeout(value);+ else if (flag === '--token') options.token = value;+ else if (flag === '--key') options.key = value;+ else if (flag === '--id') {+ if (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(Number(value))) {+ throw new Error('--id must be a positive integer');+ }+ options.keyId = Number(value);+ }else options.model = value;continue;}@@ -101,10 +107,12 @@ export function parseArgs(argv: string[]): { command?: string; options: CliOptioreturn { command, options };}-async function promptForKey(): Promise<string> {+async function promptForKey(provider = false): Promise<string> {if (!process.stdin.isTTY) {throw new Error(- 'No API key supplied. Pass --api-key or set FREELLMAPI_API_KEY.',+ provider+ ? 'No provider key supplied. Pass --key or use an interactive terminal for hidden input.'+ : 'No API key supplied. Pass --api-key or set FREELLMAPI_API_KEY.',);}// Imported lazily, not statically: `node:readline/promises` only exists on@@ -126,16 +134,27 @@ async function promptForKey(): Promise<string> {output,terminal: true,});+ const controller = new AbortController();+ const cancel = (): void => { controller.abort(); };+ rl.on('SIGINT', cancel);+ rl.on('close', cancel);try {- const answer = rl.question('FreeLLMAPI unified API key: ');+ const answer = rl.question(provider ? 'Provider API key: ' : 'FreeLLMAPI unified API key: ', {+ signal: controller.signal,+ });muted = true;const value = (await answer).trim();muted = false;process.stderr.write('\n');if (!value) throw new Error('An API key is required');return value;+ } catch (error) {+ if (controller.signal.aborted) throw new Error('Key entry cancelled');+ throw error;} finally {muted = false;+ rl.off('SIGINT', cancel);+ rl.off('close', cancel);rl.close();}}@@ -242,7 +261,7 @@ export function resolvePinnedModel(function help(): string {return [- 'FreeLLMAPI coding-agent setup',+ 'FreeLLMAPI coding-agent setup and provider key management','','Usage:',' freellmapi <command> [--url URL] [--api-key KEY] [--profile NAME] [--model ID] [--dry-run]',@@ -254,9 +273,10 @@ function help(): string {' launch Run Claude Code with credentials injected into the child environment',' launch-codex Run Codex with provider overrides and injected credentials',' list List supported coding agents',+ ' keys Add, list, remove, or test provider keys (keys --help)','','Environment:',- ' FREELLMAPI_URL, FREELLMAPI_API_KEY',+ ' FREELLMAPI_URL, FREELLMAPI_API_KEY, FREELLMAPI_DASHBOARD_TOKEN (keys only)',].join('\n');}@@ -435,10 +455,20 @@ async function runDoctor(options: CliOptions): Promise<number> {export async function main(argv = process.argv.slice(2)): Promise<number> {const { command, options } = parseArgs(argv);if (!command || command === 'help' || argv.includes('--help') || argv.includes('-h')) {- process.stdout.write(`${help()}\n`);+ process.stdout.write(`${command === 'keys' ? keysHelp() : help()}\n`);return 0;}- // `doctor` is the only command that takes positional arguments. Every other+ for (const arg of argv) {+ const flag = arg.split('=', 1)[0];+ if (command !== 'keys' && ['--token', '--key', '--id'].includes(flag)) {+ throw new Error(`${flag} is only supported by keys`);+ }+ if (command === 'keys' && ['--api-key', '--profile', '--model'].includes(flag)) {+ throw new Error(`${flag} is not supported by keys; use keys --help for available options`);+ }+ }+ if (command === 'keys') return runKeys(options, () => promptForKey(true));+ // `doctor` and `keys` take positional arguments. Every other// one rejects them here, BEFORE dispatch — checking after the setup-* branch// would let `setup-claude typo` run with the stray word silently ignored,// where it used to be an error.diff --git a/cli/src/keys.test.ts b/cli/src/keys.test.tsnew file mode 100644index 00000000..3c4b23aa--- /dev/null+++ b/cli/src/keys.test.ts@@ -0,0 +1,210 @@+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';+import { main, parseArgs } from './index.js';++const token = 'dashboard-session==';+const secret = 'provider-secret==';+const key = { id: 7, platform: 'groq', enabled: true, status: 'healthy', maskedKey: secret, lastHealthError: null as string | null };+const calls: Array<{ path: string; init: RequestInit }> = [];+let keys: Array<typeof key & { modelScope?: string[]; models?: Array<{ id: number; kind: string }> }>;+let output: string;++beforeEach(() => {+ keys = [{ ...key }];+ output = '';+ calls.length = 0;+ vi.stubEnv('FREELLMAPI_DASHBOARD_TOKEN', token);+ vi.spyOn(process.stdout, 'write').mockImplementation(chunk => { output += String(chunk); return true; });+ vi.stubGlobal('fetch', vi.fn(async (input: string, init: RequestInit = {}) => {+ const path = new URL(input).pathname;+ calls.push({ path, init });+ if (path === '/api/keys/providers') return Response.json({ providers: [{ platform: 'groq' }, { platform: 'kilo', keyless: true }] });+ if (path === '/api/keys' && init.method === 'POST') return Response.json({ id: 7, platform: 'groq', maskedKey: secret }, { status: 201 });+ if (path === '/api/keys') return Response.json(keys);+ if (path === '/api/models') return Response.json([+ { id: 1, platform: 'groq', modelId: 'model-a', enabled: true },+ { id: 2, platform: 'groq', modelId: 'model-b', enabled: true },+ { id: 3, platform: 'groq', modelId: 'disabled', enabled: false },+ { id: 4, platform: 'other', modelId: 'other', enabled: true },+ ]);+ if (path.startsWith('/api/health/check/')) return Response.json({ keyId: Number(path.split('/').at(-1)), status: 'healthy' });+ if (path.startsWith('/api/keys/') && init.method === 'DELETE') return Response.json({ success: true });+ throw new Error(`Unexpected request: ${path}`);+ }));+});++afterEach(() => {+ vi.restoreAllMocks();+ vi.unstubAllGlobals();+ vi.unstubAllEnvs();+});++describe('provider key commands', () => {+ it('preserves equals signs in credentials and lets --token override the environment', async () => {+ expect(parseArgs(['keys', 'add', 'groq', `--token=${token}`, `--key=${secret}`]).options)+ .toMatchObject({ token, key: secret });+ await main(['--url', 'http://localhost:3100/v1/', 'keys', 'add', 'groq', '--token', 'override', `--key=${secret}`]);+ expect(calls.map(c => c.path)).toEqual(['/api/keys/providers', '/api/keys', '/api/health/check/7', '/api/keys']);+ expect(calls[1].init.body).toBe(JSON.stringify({ platform: 'groq', key: secret }));+ for (const call of calls) expect(new Headers(call.init.headers).get('Authorization')).toBe('Bearer override');+ expect(output).toContain('Saved groq key 7');+ expect(output).not.toContain(secret);+ expect(output).not.toContain(token);+ });++ it('lists metadata and enabled chat model counts, without printing even masked keys', async () => {+ keys.push({ ...key, id: 8, enabled: false, modelScope: ['model-b'] });+ expect(await main(['keys', 'list'])).toBe(0);+ expect(output).toContain('7\tgroq\t2\tenabled\thealthy');+ expect(output).toContain('8\tgroq\t1\tdisabled\thealthy');+ expect(output).not.toContain(secret);+ expect(output).not.toContain(token);+ });++ it('requires an id to remove one of several keys and verifies its platform', async () => {+ keys.push({ ...key, id: 8 });+ await expect(main(['keys', 'remove', 'groq'])).rejects.toThrow('--id');+ await expect(main(['keys', 'remove', 'other', '--id', '7'])).rejects.toThrow('No matching key');+ expect(calls.every(c => c.init.method !== 'DELETE')).toBe(true);+ expect(await main(['keys', 'remove', 'groq', '--id', '8'])).toBe(0);+ expect(calls.at(-1)).toMatchObject({ path: '/api/keys/8', init: { method: 'DELETE' } });+ });++ it('removes a single matching key without touching other providers', async () => {+ keys.push({ ...key, id: 8, platform: 'other' });+ await main(['keys', 'remove', 'groq']);+ expect(calls.filter(c => c.init.method === 'DELETE').map(c => c.path)).toEqual(['/api/keys/7']);+ });++ it('does not equate HTTP 200 with successful validation', async () => {+ keys[0].status = 'invalid';+ expect(await main(['keys', 'test', 'groq'])).toBe(1);+ expect(output).toContain('invalid');+ });++ it('reports inconclusive validation when the server preserves a previously healthy status', async () => {+ keys[0] = { ...key, lastHealthError: secret };+ expect(await main(['keys', 'test', 'groq'])).toBe(1);+ expect(output).toContain('inconclusive');+ expect(output).not.toContain(secret);+ });++ it('checks every matching key and combines unsuccessful results', async () => {+ keys.push({ ...key, id: 8, status: 'invalid' }, { ...key, id: 9, platform: 'other' });+ expect(await main(['keys', 'test', 'groq'])).toBe(1);+ expect(calls.filter(c => c.path.startsWith('/api/health')).map(c => c.path))+ .toEqual(['/api/health/check/7', '/api/health/check/8']);+ });++ it('keeps a newly saved key when validation fails and returns a failure exit code', async () => {+ keys[0].status = 'invalid';+ expect(await main(['keys', 'add', 'groq', '--key', secret])).toBe(1);+ expect(output).toContain('Saved groq key 7');+ expect(calls.every(c => c.init.method !== 'DELETE')).toBe(true);+ });++ it('does not prompt for a keyless provider', async () => {+ keys[0].platform = 'kilo';+ expect(await main(['keys', 'add', 'kilo'])).toBe(0);+ expect(JSON.parse(calls[1].init.body as string)).toEqual({ platform: 'kilo', key: '' });+ });++ it('rejects a missing provider key in a non-interactive terminal without adding one', async () => {+ const descriptor = Object.getOwnPropertyDescriptor(process.stdin, 'isTTY');+ Object.defineProperty(process.stdin, 'isTTY', { configurable: true, value: false });+ try {+ await expect(main(['keys', 'add', 'groq'])).rejects.toThrow('Pass --key');+ expect(calls.some(c => c.init.method === 'POST')).toBe(false);+ } finally {+ if (descriptor) Object.defineProperty(process.stdin, 'isTTY', descriptor);+ else Reflect.deleteProperty(process.stdin, 'isTTY');+ }+ });++ it('does not treat a failed health probe as success when the stored status is healthy', async () => {+ const request = vi.mocked(fetch).getMockImplementation()!;+ vi.mocked(fetch).mockImplementation((input, init) => String(input).includes('/api/health/check/')+ ? Promise.resolve(Response.json({ keyId: 7, status: 'error' }))+ : request(input, init));+ expect(await main(['keys', 'test', 'groq'])).toBe(1);+ expect(output).toContain('7\tgroq\terror');+ });++ it('rejects malformed key IDs from the gateway before attempting deletion', async () => {+ vi.mocked(fetch).mockResolvedValue(Response.json([{ ...key, id: '../providers' }]));+ await expect(main(['keys', 'remove', 'groq'])).rejects.toThrow('invalid key list');+ expect(fetch).toHaveBeenCalledTimes(1);+ });++ it('counts only enabled chat models on the same custom endpoint', async () => {+ keys = [{ ...key, platform: 'custom', models: [{ id: 1, kind: 'chat' }, { id: 4, kind: 'embedding' }] }];+ vi.mocked(fetch).mockImplementation(async (input) => new URL(String(input)).pathname === '/api/keys'+ ? Response.json(keys)+ : Response.json([+ { id: 1, platform: 'custom', modelId: 'first', enabled: true, keyId: 8 },+ { id: 2, platform: 'custom', modelId: 'other-endpoint', enabled: true, keyId: 9 },+ { id: 4, platform: 'custom', modelId: 'id-shared-with-embedding', enabled: true, keyId: 9 },+ ]));+ await main(['keys', 'list']);+ expect(output).toContain('7\tcustom\t1\tenabled\thealthy');+ });++ it('does not write when the provider identifier is unknown', async () => {+ await expect(main(['keys', 'add', 'missing', '--key', secret])).rejects.toThrow('Unknown provider');+ expect(calls.some(c => c.init.method === 'POST')).toBe(false);+ });++ it('requires a dashboard token rather than using the unified API key', async () => {+ vi.stubEnv('FREELLMAPI_DASHBOARD_TOKEN', '');+ vi.stubEnv('FREELLMAPI_API_KEY', 'unified-secret');+ await expect(main(['keys', 'list'])).rejects.toThrow('FREELLMAPI_DASHBOARD_TOKEN');+ expect(calls).toEqual([]);+ });++ it.each([+ ['keys', 'remove', 'groq', '--id', '7abc'],+ ['keys', 'remove', 'groq', '--id', '0'],+ ['keys', 'list', 'extra'],+ ['keys', 'remove'],+ ['keys', 'remove', 'groq', '--dry-run'],+ ['keys', 'list', '--key', secret],+ ['keys', 'add', 'groq', '--api-key', secret],+ ['keys', 'remove', 'groq', '--model', 'model-a'],+ ['keys', 'remove', 'groq', '--profile', 'work'],+ ['setup-claude', '--token', token],+ ['setup-claude', '--key', secret],+ ['list', '--id', '7'],+ ])('rejects invalid or inapplicable arguments before making requests: %j', async (...args) => {+ await expect(main(args)).rejects.toThrow();+ expect(calls).toEqual([]);+ });++ it('does not print server error bodies containing credentials', async () => {+ vi.mocked(fetch).mockResolvedValue(Response.json({ error: { message: `${secret} ${token}` } }, { status: 401 }));+ await expect(main(['keys', 'list'])).rejects.toThrow('Dashboard authentication failed');+ expect(output).toBe('');+ });++ it('omits secrets from non-authentication failures and transport errors', async () => {+ vi.mocked(fetch).mockResolvedValueOnce(Response.json({ error: secret }, { status: 500 }));+ await expect(main(['keys', 'list'])).rejects.toThrow(/^Dashboard request failed \(HTTP 500\)$/);+ vi.mocked(fetch).mockRejectedValueOnce(new Error(token));+ await expect(main(['keys', 'list'])).rejects.toThrow(/^Could not complete the dashboard request\./);+ expect(output).toBe('');+ });++ it('does not send dashboard credentials to redirects and applies the timeout', async () => {+ const timeout = vi.spyOn(AbortSignal, 'timeout');+ await main(['keys', 'test', 'groq', '--id', '7', '--timeout', '5000']);+ expect(calls[0].init).toMatchObject({ redirect: 'error', signal: expect.any(AbortSignal) });+ expect(timeout).toHaveBeenCalledWith(5000);+ await expect(main(['keys', 'list', '--url', 'http://user:password@localhost:3000'])).rejects.toThrow('without credentials');+ });++ it('shows key-specific help without requiring credentials or making requests', async () => {+ vi.stubEnv('FREELLMAPI_DASHBOARD_TOKEN', '');+ expect(await main(['keys', '--help'])).toBe(0);+ expect(output).toContain('keys add <platform>');+ expect(output).toContain('FREELLMAPI_DASHBOARD_TOKEN');+ expect(calls).toEqual([]);+ });+});diff --git a/cli/src/keys.ts b/cli/src/keys.tsnew file mode 100644index 00000000..b02109f5--- /dev/null+++ b/cli/src/keys.ts@@ -0,0 +1,184 @@+export interface KeyCommandOptions {+ url: string;+ args: string[];+ token?: string;+ key?: string;+ keyId?: number;+ timeoutMs?: number;+ dryRun: boolean;+}++interface KeyRow {+ id: number;+ platform: string;+ enabled: boolean;+ status: string;+ lastHealthError?: string | null;+ modelScope?: string[] | null;+ models?: Array<{ id: number; kind: string }>;+}++interface ModelRow {+ id: number;+ platform: string;+ modelId: string;+ enabled: boolean;+ keyId?: number | null;+}++export function keysHelp(): string {+ return [+ 'Provider key management (dashboard authentication):',+ ' freellmapi keys add <platform> [--key KEY]',+ ' freellmapi keys list',+ ' freellmapi keys remove <platform> [--id ID]',+ ' freellmapi keys test <platform> [--id ID]',+ '',+ 'Options: --url URL, --token TOKEN, --timeout MS (default 30000)',+ 'Use FREELLMAPI_DASHBOARD_TOKEN or --token for the dashboard session token.',+ 'The unified --api-key / FREELLMAPI_API_KEY is not dashboard authentication.',+ 'Omit --key for hidden terminal input. Keyless providers do not prompt.',+ 'remove requires --id when a platform has multiple keys; test checks all matches.',+ 'list shows enabled chat model counts, respecting each key\'s model scope.',+ 'add saves the key, then checks it; failed validation leaves it saved and exits 1.',+ ].join('\n');+}++function gatewayRoot(value: string): string {+ let url: URL;+ try { url = new URL(value.trim()); } catch { throw new Error('--url must be an HTTP(S) gateway URL'); }+ if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {+ throw new Error('--url must be an HTTP(S) URL without credentials, a query, or a fragment');+ }+ return url.href.replace(/\/+$/, '').replace(/\/v1$/i, '');+}++function modelCount(key: KeyRow, models: ModelRow[]): number {+ const customIds = new Set(key.models?.filter(m => m.kind === 'chat').map(m => m.id));+ return models.filter(model => model.enabled && model.platform === key.platform+ && (!key.modelScope?.length || key.modelScope.includes(model.modelId))+ && (key.platform === 'custom' ? customIds.has(model.id) : !model.keyId || model.keyId === key.id)).length;+}++const statuses = new Set(['healthy', 'invalid', 'unknown', 'rate_limited', 'error']);+function statusOf(status: string): string {+ return statuses.has(status) ? status : 'unknown';+}++export async function runKeys(+ options: KeyCommandOptions,+ prompt: () => Promise<string>,+): Promise<number> {+ const [action, rawPlatform, ...extra] = options.args;+ if (!action || !['add', 'list', 'remove', 'test'].includes(action)) {+ throw new Error(`Expected keys add, list, remove, or test.\n\n${keysHelp()}`);+ }+ if (extra.length || (action === 'list' ? rawPlatform !== undefined : !rawPlatform)) {+ throw new Error(`Invalid arguments for keys ${action}.\n\n${keysHelp()}`);+ }+ if (options.dryRun) throw new Error('--dry-run is not supported by keys; no request was made');+ if (options.key !== undefined && action !== 'add') throw new Error('--key is only supported by keys add');+ if (options.keyId !== undefined && action !== 'remove' && action !== 'test') {+ throw new Error('--id is only supported by keys remove and keys test');+ }+ const platform = rawPlatform?.toLowerCase();+ if (platform && !/^[a-z][a-z0-9_-]*$/.test(platform)) throw new Error('Invalid provider platform identifier');+ const token = options.token?.trim();+ if (!token) throw new Error('Set FREELLMAPI_DASHBOARD_TOKEN or pass --token with a dashboard session token');+ const root = gatewayRoot(options.url);+ const timeout = options.timeoutMs ?? 30_000;+ if (!Number.isSafeInteger(timeout) || timeout <= 0 || timeout > 2_147_483_647) {+ throw new Error('--timeout must be a positive integer of at most 2147483647 milliseconds');+ }++ async function request<T>(path: string, method = 'GET', body?: unknown): Promise<T> {+ let response: Response;+ try {+ response = await fetch(`${root}${path}`, {+ method,+ headers: { Authorization: `Bearer ${token}`, ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },+ body: body === undefined ? undefined : JSON.stringify(body),+ signal: AbortSignal.timeout(timeout),+ redirect: 'error',+ cache: 'no-store',+ });+ } catch {+ throw new Error('Could not complete the dashboard request. Check --url, connectivity, and --timeout.');+ }+ // Provider error bodies may contain credentials. Only report the HTTP+ // status, never echo arbitrary response bodies or transport errors.+ if (response.status === 401 || response.status === 403) {+ throw new Error('Dashboard authentication failed. Supply a current dashboard session token with --token or FREELLMAPI_DASHBOARD_TOKEN.');+ }+ if (!response.ok) throw new Error(`Dashboard request failed (HTTP ${response.status})`);+ if (response.status === 204) return undefined as T;+ try { return await response.json() as T; } catch { throw new Error('The gateway returned an invalid JSON response'); }+ }++ async function listKeys(): Promise<KeyRow[]> {+ const rows = await request<KeyRow[]>('/api/keys');+ if (!Array.isArray(rows) || rows.some(row => !row || !Number.isSafeInteger(row.id)+ || row.id <= 0 || typeof row.platform !== 'string')) {+ throw new Error('The gateway returned an invalid key list');+ }+ return rows;+ }++ async function check(id: number, provider: string): Promise<number> {+ const result = await request<{ keyId: number; status: string }>(`/api/health/check/${id}`, 'POST');+ if (!result || result.keyId !== id) throw new Error('The gateway returned an invalid health check result');+ // A transport failure preserves the previous status on the server, so+ // HTTP 200 / status=healthy alone cannot prove this check succeeded.+ const current = (await listKeys()).find(row => row.id === id);+ if (!current) throw new Error('The key no longer exists');+ const status = statusOf(result.status === 'healthy' ? current.status : result.status);+ const inconclusive = !!current.lastHealthError && status !== 'invalid';+ process.stdout.write(`${id}\t${provider}\t${inconclusive ? `inconclusive (stored status: ${statusOf(current.status)})` : status}\n`);+ return status === 'healthy' && !inconclusive ? 0 : 1;+ }++ if (action === 'add') {+ const { providers } = await request<{ providers: Array<{ platform: string; keyless?: boolean }> }>('/api/keys/providers');+ const provider = providers.find(p => p.platform === platform);+ if (!provider) {+ throw new Error(platform === 'custom'+ ? 'Custom endpoints require URL and model registration; add them in the dashboard.'+ : 'Unknown provider platform. Use the provider identifier shown in the dashboard.');+ }+ const value = (options.key ?? (provider.keyless ? '' : await prompt())).trim();+ if (!value && !provider.keyless) throw new Error('A provider API key is required');+ const saved = await request<{ id: number }>('/api/keys', 'POST', { platform, key: value });+ if (!Number.isSafeInteger(saved.id) || saved.id <= 0) throw new Error('The gateway did not return a valid saved key ID');+ process.stdout.write(`Saved ${platform} key ${saved.id}. Checking it now; the key remains saved if validation fails.\n`);+ return check(saved.id, platform!);+ }++ const rows = await listKeys();+ if (action === 'list') {+ if (!rows.length) {+ process.stdout.write('No provider keys configured.\n');+ return 0;+ }+ const models = await request<ModelRow[]>('/api/models');+ if (!Array.isArray(models)) throw new Error('The gateway returned an invalid model list');+ process.stdout.write('ID\tPLATFORM\tMODELS\tENABLED\tSTATUS\n');+ for (const row of rows) {+ const provider = /^[a-z][a-z0-9_-]*$/.test(row.platform) ? row.platform : 'unknown';+ process.stdout.write(`${row.id}\t${provider}\t${modelCount(row, models)}\t${row.enabled ? 'enabled' : 'disabled'}\t${statusOf(row.status)}\n`);+ }+ return 0;+ }++ const selected = rows.filter(row => row.platform === platform && (options.keyId === undefined || row.id === options.keyId));+ if (!selected.length) throw new Error('No matching key found for that platform and ID');+ if (action === 'remove') {+ if (selected.length > 1) throw new Error('Multiple keys match. Run keys list and specify one with --id.');+ await request(`/api/keys/${selected[0].id}`, 'DELETE');+ process.stdout.write(`Removed ${platform} key ${selected[0].id}.\n`);+ return 0;+ }++ let exitCode = 0;+ for (const row of selected) exitCode = Math.max(exitCode, await check(row.id, platform!));+ return exitCode;+}diff --git a/server/src/__tests__/routes/cli-keys.test.ts b/server/src/__tests__/routes/cli-keys.test.tsnew file mode 100644index 00000000..8a4831d4--- /dev/null+++ b/server/src/__tests__/routes/cli-keys.test.ts@@ -0,0 +1,86 @@+import type { Server } from 'node:http';+import type { AddressInfo } from 'node:net';+import express from 'express';+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';+import { main } from '../../../../cli/src/index.js';+import { getDb, initDb } from '../../db/index.js';+import { decrypt } from '../../lib/crypto.js';+import { requireAuth } from '../../middleware/requireAuth.js';+import { resolveProvider } from '../../providers/index.js';+import { healthRouter } from '../../routes/health.js';+import { keysRouter } from '../../routes/keys.js';+import { modelsRouter } from '../../routes/models.js';+import { mintDashboardToken } from '../helpers/auth.js';++// Exercise the CLI against real authenticated routes and encrypted storage.+// Only the upstream provider probe is replaced; no external credentials or calls.+describe('CLI provider keys through the dashboard API', () => {+ let server: Server;+ let url: string;+ let token: string;+ let output: string;+ const secret = 'gsk_cli_integration_secret==';+ const provider = resolveProvider('groq')!;++ beforeAll(async () => {+ vi.stubEnv('ENCRYPTION_KEY', '0'.repeat(64));+ initDb(':memory:');+ token = mintDashboardToken();+ const app = express();+ app.use(express.json());+ app.use('/api/keys', requireAuth, keysRouter);+ app.use('/api/health', requireAuth, healthRouter);+ app.use('/api/models', requireAuth, modelsRouter);+ server = app.listen(0, '127.0.0.1');+ await new Promise<void>(resolve => server.once('listening', resolve));+ url = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;+ });++ beforeEach(() => {+ getDb().prepare('DELETE FROM api_keys').run();+ output = '';+ vi.spyOn(process.stdout, 'write').mockImplementation(chunk => { output += String(chunk); return true; });+ vi.spyOn(provider, 'validateKey').mockResolvedValue(true);+ });++ afterEach(() => { vi.restoreAllMocks(); });+ afterAll(async () => {+ await new Promise<void>((resolve, reject) => server.close(error => error ? reject(error) : resolve()));+ vi.unstubAllEnvs();+ });++ const run = (...args: string[]) => main(['--url', url, '--token', token, 'keys', ...args]);++ it('adds, validates, lists, and removes a key without returning its credentials', async () => {+ expect(await run('add', 'groq', '--key', secret)).toBe(0);+ const row = getDb().prepare('SELECT * FROM api_keys').get() as {+ id: number; encrypted_key: string; iv: string; auth_tag: string; status: string;+ };+ expect(decrypt(row.encrypted_key, row.iv, row.auth_tag)).toBe(secret);+ expect(row.status).toBe('healthy');+ expect(provider.validateKey).toHaveBeenCalledWith(secret, expect.objectContaining({ keyId: row.id }));+ expect(await run('list')).toBe(0);+ expect(output).toContain('PLATFORM\tMODELS');+ expect(output).toContain('groq');+ expect(await run('remove', 'groq', '--id', String(row.id))).toBe(0);+ expect(getDb().prepare('SELECT * FROM api_keys').all()).toEqual([]);+ expect(output).not.toContain(secret);+ expect(output).not.toContain(token);+ });++ it('recognizes an inconclusive check despite the server preserving healthy status', async () => {+ await run('add', 'groq', '--key', secret);+ vi.mocked(provider.validateKey).mockRejectedValueOnce(new Error('network unavailable'));+ vi.spyOn(console, 'error').mockImplementation(() => {});+ expect(await run('test', 'groq')).toBe(1);+ expect(output).toContain('inconclusive (stored status: healthy)');+ expect(getDb().prepare('SELECT status FROM api_keys').get()).toEqual({ status: 'healthy' });+ });++ it('rejects a unified proxy key as dashboard authentication', async () => {+ const unified = getDb().prepare("SELECT value FROM settings WHERE key = 'unified_api_key'").get() as { value: string };+ await expect(main(['keys', 'list', '--url', url, '--token', unified.value]))+ .rejects.toThrow('Dashboard authentication failed');+ expect(output).toBe('');+ });+});