Skip to content

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.md
index 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.md
index 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.
+
## Safety
Every generator is non-destructive: it merges into your existing configuration
diff --git a/cli/package.json b/cli/package.json
index 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.ts
index 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: CliOptio
const 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: CliOptio
options.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: CliOptio
else 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: CliOptio
return { 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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('');
+ });
+});