instant-cli 1.0.10 → 1.0.11

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> instant-cli@1.0.10 build /home/runner/work/instant/instant/client/packages/cli
+> instant-cli@1.0.11 build /home/runner/work/instant/instant/client/packages/cli
 > rm -rf dist; tsc -p tsconfig.build.json
 

package/__tests__/authClientAddApple.test.ts

@@ -0,0 +1,374 @@
+import { test, expect, describe, vi, beforeEach } from 'vitest';
+import { Effect, Layer, Logger } from 'effect';
+import { FileSystem } from '@effect/platform';
+import { SystemError } from '@effect/platform/Error';
+import { GlobalOpts } from '../src/context/globalOpts.ts';
+import { CurrentApp } from '../src/context/currentApp.ts';
+import { InstantHttpAuthed } from '../src/lib/http.ts';
+
+// -- mocks --
+
+// Prevent src/index.ts side-effect (program.parse) from running.
+// add.ts has `import type` from index.ts, but vitest still evaluates it.
+vi.mock('../src/index.ts', () => ({}));
+
+let prompts: any[] = [];
+let mockPromptReturn: any = '';
+
+vi.mock('../src/ui/lib.ts', async (importOriginal) => {
+  const orig: any = await importOriginal();
+  return {
+    ...orig,
+    renderUnwrap: (prompt: any) => {
+      prompts.push(prompt);
+      return Promise.resolve(mockPromptReturn);
+    },
+  };
+});
+
+let addedClients: any[] = [];
+
+vi.mock('../src/lib/oauth.ts', () => ({
+  getAppsAuth: () =>
+    Effect.succeed({
+      oauth_service_providers: [{ id: 'prov-1', provider_name: 'apple' }],
+      oauth_clients: [],
+    }),
+  addOAuthProvider: () =>
+    Effect.succeed({
+      provider: { id: 'prov-1', provider_name: 'apple' },
+    }),
+  addOAuthClient: (params: any) => {
+    addedClients.push(params);
+    return Effect.succeed({
+      client: {
+        id: 'client-1',
+        client_name: params.clientName,
+        client_id: params.clientId,
+      },
+    });
+  },
+}));
+
+// Lazy import so mocks are in place
+const { authClientAddCmd } = await import('../src/commands/auth/client/add.ts');
+
+// -- helpers --
+
+let logs: string[] = [];
+
+// In-memory filesystem for the private-key file. Keys are paths, values are
+// file contents. Requested paths that aren't present throw SystemError, which
+// the Apple handler maps to BadArgsError.
+let mockFiles: Record<string, string> = {};
+
+const MockFileSystemLayer = FileSystem.layerNoop({
+  readFileString: (path: string) =>
+    path in mockFiles
+      ? Effect.succeed(mockFiles[path])
+      : Effect.fail(
+          new SystemError({
+            reason: 'NotFound',
+            module: 'FileSystem',
+            method: 'readFileString',
+            pathOrDescriptor: path,
+            description: `no such file or directory, open '${path}'`,
+          }),
+        ),
+});
+
+const run = (flags: Map<string, string>, { yes }: { yes: boolean }) =>
+  Effect.runPromise(
+    authClientAddCmd(Object.fromEntries(flags) as any).pipe(
+      Effect.provide(
+        Layer.mergeAll(
+          Layer.succeed(GlobalOpts, { yes }),
+          Layer.succeed(CurrentApp, { appId: 'test-app', source: 'env' }),
+          Layer.succeed(InstantHttpAuthed, {} as any),
+          // Mocked FileSystem so readPrivateKeyFile reads from `mockFiles`.
+          MockFileSystemLayer,
+          Logger.replace(
+            Logger.defaultLogger,
+            Logger.make(({ message }) => {
+              logs.push(String(message));
+            }),
+          ),
+        ),
+      ),
+    ),
+  );
+
+const without = (flags: Map<string, string>, key: string) => {
+  const copy = new Map(flags);
+  copy.delete(key);
+  return copy;
+};
+
+const withEntry = (flags: Map<string, string>, key: string, value: string) =>
+  new Map([...flags, [key, value]]);
+
+const PEM_CONTENTS =
+  '-----BEGIN PRIVATE KEY-----\nabc\n-----END PRIVATE KEY-----\n';
+const PEM_PATH = '/tmp/AuthKey_ABC123.p8';
+
+beforeEach(() => {
+  prompts = [];
+  addedClients = [];
+  logs = [];
+  mockPromptReturn = '';
+  mockFiles = { [PEM_PATH]: PEM_CONTENTS };
+});
+
+// -- flag sets --
+
+const nativeFlags = new Map([
+  ['type', 'apple'],
+  ['name', 'apple-native'],
+  ['services-id', 'com.example.app'],
+]);
+
+const webFlags = new Map([
+  ['type', 'apple'],
+  ['name', 'apple-web'],
+  ['services-id', 'com.example.web'],
+  ['team-id', 'ABCD1234'],
+  ['key-id', 'XYZ789'],
+  ['private-key-file', PEM_PATH],
+]);
+
+// -- native-only (no web flow): build-up with --yes --
+
+describe('native: --yes errors on each missing required flag', () => {
+  test('missing --type', async () => {
+    await run(without(nativeFlags, 'type'), { yes: true });
+    expect(logs.join('\n')).toContain('Missing required value for --type');
+    expect(addedClients).toHaveLength(0);
+  });
+
+  test('missing --name', async () => {
+    await run(without(nativeFlags, 'name'), { yes: true });
+    expect(logs.join('\n')).toContain('Missing required value for --name');
+    expect(addedClients).toHaveLength(0);
+  });
+
+  test('missing --services-id', async () => {
+    await run(without(nativeFlags, 'services-id'), { yes: true });
+    expect(logs.join('\n')).toContain(
+      'Missing required value for --services-id',
+    );
+    expect(addedClients).toHaveLength(0);
+  });
+});
+
+// -- native-only: interactive prompts --
+
+describe('native: interactive prompts for each missing flag', () => {
+  test('missing --type → prompts type selector', async () => {
+    mockPromptReturn = 'apple';
+    await run(without(nativeFlags, 'type'), { yes: false });
+    expect((prompts[0] as any).params.promptText).toBe('Select a client type:');
+  });
+
+  test('missing --name → prompts for name', async () => {
+    mockPromptReturn = 'apple-native';
+    await run(without(nativeFlags, 'name'), { yes: false });
+    expect((prompts[0] as any).props.prompt).toBe('Client Name:');
+  });
+
+  test('missing --services-id → prompts for Services ID', async () => {
+    mockPromptReturn = 'com.example.app';
+    await run(without(nativeFlags, 'services-id'), { yes: false });
+    expect((prompts[0] as any).props.prompt).toContain('Services ID');
+  });
+
+  test('no web-flow flags → prompts to configure web flow', async () => {
+    // mockPromptReturn = '' → confirmation treats as false (defaultValue)
+    await run(nativeFlags, { yes: false });
+    const confirm = prompts.find((p) =>
+      String(p?.props?.promptText ?? '').includes(
+        'Configure web redirect flow?',
+      ),
+    );
+    expect(confirm).toBeDefined();
+    // With default = false, no additional web-flow prompts should appear
+    expect(addedClients).toHaveLength(1);
+    expect(addedClients[0].clientSecret).toBeUndefined();
+  });
+
+  test('configure-web confirm → does not prompt with --yes', async () => {
+    await run(nativeFlags, { yes: true });
+    const confirm = prompts.find((p) =>
+      String(p?.props?.promptText ?? '').includes(
+        'Configure web redirect flow?',
+      ),
+    );
+    expect(confirm).toBeUndefined();
+    expect(addedClients).toHaveLength(1);
+  });
+});
+
+// -- native-only: success --
+
+describe('native: success', () => {
+  test('all required flags → creates client without secret or redirect', async () => {
+    await run(nativeFlags, { yes: true });
+    expect(addedClients).toHaveLength(1);
+    expect(addedClients[0]).toMatchObject({
+      clientName: 'apple-native',
+      clientId: 'com.example.app',
+    });
+    const output = logs.join('\n');
+    expect(output).toContain('Apple OAuth client created: apple-native');
+    expect(output).toContain('ID: client-1');
+    expect(output).toContain('Services ID: com.example.app');
+  });
+});
+
+// -- web flow: build-up with --yes --
+
+describe('web: --yes errors on each missing required flag', () => {
+  test('missing --team-id', async () => {
+    await run(without(webFlags, 'team-id'), { yes: true });
+    expect(logs.join('\n')).toContain('Missing required value for --team-id');
+    expect(addedClients).toHaveLength(0);
+  });
+
+  test('missing --key-id', async () => {
+    await run(without(webFlags, 'key-id'), { yes: true });
+    expect(logs.join('\n')).toContain('Missing required value for --key-id');
+    expect(addedClients).toHaveLength(0);
+  });
+
+  test('missing --private-key-file', async () => {
+    await run(without(webFlags, 'private-key-file'), { yes: true });
+    expect(logs.join('\n')).toContain(
+      'Missing required value for --private-key-file',
+    );
+    expect(addedClients).toHaveLength(0);
+  });
+});
+
+// -- web: interactive prompts --
+
+describe('web: interactive prompts for each missing flag', () => {
+  test('missing --team-id → prompts for Team ID', async () => {
+    mockPromptReturn = 'ABCD1234';
+    await run(without(webFlags, 'team-id'), { yes: false });
+    const p = prompts.find((p: any) =>
+      String(p?.props?.prompt ?? '').includes('Team ID'),
+    );
+    expect(p).toBeDefined();
+  });
+
+  test('missing --key-id → prompts for Key ID', async () => {
+    mockPromptReturn = 'XYZ789';
+    await run(without(webFlags, 'key-id'), { yes: false });
+    const p = prompts.find((p: any) =>
+      String(p?.props?.prompt ?? '').includes('Key ID'),
+    );
+    expect(p).toBeDefined();
+  });
+
+  test('missing --private-key-file → prompts for path', async () => {
+    mockPromptReturn = PEM_PATH;
+    await run(without(webFlags, 'private-key-file'), { yes: false });
+    const p = prompts.find((p: any) =>
+      String(p?.props?.prompt ?? '').includes('Path to .p8 private key file'),
+    );
+    expect(p).toBeDefined();
+  });
+
+  test('custom-redirect-uri → prompts when omitted', async () => {
+    mockPromptReturn = '';
+    await run(webFlags, { yes: false });
+    const p = prompts.find(
+      (p: any) =>
+        p?.props?.placeholder === 'https://yoursite.com/oauth/callback',
+    );
+    expect(p).toBeDefined();
+  });
+
+  test('custom-redirect-uri → skipped with --yes', async () => {
+    await run(webFlags, { yes: true });
+    expect(prompts).toHaveLength(0);
+    expect(addedClients).toHaveLength(1);
+  });
+});
+
+// -- web: success --
+
+describe('web: success', () => {
+  test('all required flags → creates client and prints redirect URL', async () => {
+    await run(webFlags, { yes: true });
+    expect(addedClients).toHaveLength(1);
+    expect(addedClients[0]).toMatchObject({
+      clientName: 'apple-web',
+      clientId: 'com.example.web',
+      clientSecret: PEM_CONTENTS.trim(),
+      redirectTo: 'https://api.instantdb.com/runtime/oauth/callback',
+      meta: { teamId: 'ABCD1234', keyId: 'XYZ789' },
+    });
+    const output = logs.join('\n');
+    expect(output).toContain('Apple OAuth client created: apple-web');
+    expect(output).toContain('Services ID: com.example.web');
+    expect(output).toContain('Team ID: ABCD1234');
+    expect(output).toContain('Key ID: XYZ789');
+    expect(output).toContain(
+      'Add this return URL under your Services ID on developer.apple.com:',
+    );
+    expect(output).toContain(
+      'https://api.instantdb.com/runtime/oauth/callback',
+    );
+    expect(output).not.toContain('Native-only flow configured.');
+  });
+
+  test('with custom-redirect-uri → uses it and prints forwarding instructions', async () => {
+    await run(
+      withEntry(webFlags, 'custom-redirect-uri', 'https://myapp.com/cb'),
+      { yes: true },
+    );
+    expect(addedClients[0].redirectTo).toBe('https://myapp.com/cb');
+    const output = logs.join('\n');
+    expect(output).toContain('https://myapp.com/cb');
+    expect(output).toContain(
+      'https://api.instantdb.com/runtime/oauth/callback with all query parameters',
+    );
+  });
+});
+
+// -- private key file: error paths --
+
+describe('private key file errors', () => {
+  test('file does not exist → BadArgsError', async () => {
+    mockFiles = {}; // remove the PEM
+    await run(webFlags, { yes: true });
+    expect(logs.join('\n')).toContain(
+      `Could not read private key file at ${PEM_PATH}`,
+    );
+    expect(addedClients).toHaveLength(0);
+  });
+
+  test('file is empty → BadArgsError', async () => {
+    mockFiles = { [PEM_PATH]: '   \n  ' };
+    await run(webFlags, { yes: true });
+    expect(logs.join('\n')).toContain(
+      `Private key file at ${PEM_PATH} is empty.`,
+    );
+    expect(addedClients).toHaveLength(0);
+  });
+});
+
+// -- native-only: stray web-only flag rejection --
+
+describe('native: web-only flags rejected when web flow not configured', () => {
+  test('--custom-redirect-uri without web flow → error', async () => {
+    await run(
+      withEntry(nativeFlags, 'custom-redirect-uri', 'https://example.com'),
+      { yes: true },
+    );
+    expect(logs.join('\n')).toContain(
+      '--custom-redirect-uri requires configuring the web redirect flow',
+    );
+    expect(addedClients).toHaveLength(0);
+  });
+});

package/__tests__/authClientAddGithub.test.ts

@@ -1,5 +1,6 @@
 import { test, expect, describe, vi, beforeEach } from 'vitest';
 import { Effect, Layer, Logger } from 'effect';
+import { NodeContext } from '@effect/platform-node';
 import { GlobalOpts } from '../src/context/globalOpts.ts';
 import { CurrentApp } from '../src/context/currentApp.ts';
 import { InstantHttpAuthed } from '../src/lib/http.ts';
@@ -63,6 +64,8 @@ const run = (flags: Map<string, string>, { yes }: { yes: boolean }) =>
           Layer.succeed(GlobalOpts, { yes }),
           Layer.succeed(CurrentApp, { appId: 'test-app', source: 'env' }),
           Layer.succeed(InstantHttpAuthed, {} as any),
+          // Provides FileSystem (required by the Apple handler).
+          NodeContext.layer,
           Logger.replace(
             Logger.defaultLogger,
             Logger.make(({ message }) => {

package/__tests__/authClientAddGoogle.test.ts

@@ -1,5 +1,6 @@
 import { test, expect, describe, vi, beforeEach } from 'vitest';
 import { Effect, Layer, Logger } from 'effect';
+import { NodeContext } from '@effect/platform-node';
 import { GlobalOpts } from '../src/context/globalOpts.ts';
 import { CurrentApp } from '../src/context/currentApp.ts';
 import { InstantHttpAuthed } from '../src/lib/http.ts';
@@ -63,6 +64,8 @@ const run = (flags: Map<string, string>, { yes }: { yes: boolean }) =>
           Layer.succeed(GlobalOpts, { yes }),
           Layer.succeed(CurrentApp, { appId: 'test-app', source: 'env' }),
           Layer.succeed(InstantHttpAuthed, {} as any),
+          // Provides FileSystem (required by the Apple handler).
+          NodeContext.layer,
           Logger.replace(
             Logger.defaultLogger,
             Logger.make(({ message }) => {

package/__tests__/e2e/cli.e2e.test.ts

@@ -291,7 +291,7 @@ export default _schema;
         await project2.cleanup();
       }
     });
-  }, 40_000);
+  }, 50_000);
 
   describe('push perms', () => {
     it('exits with code 1 when no perms file exists', async () => {

package/dist/commands/auth/client/add.d.ts

@@ -1,8 +1,9 @@
 import { Effect } from 'effect';
+import { FileSystem } from '@effect/platform';
 import { GlobalOpts } from '../../../context/globalOpts.ts';
 export declare const authClientAddCmd: (opts: {
     type?: string | undefined;
     name?: string | undefined;
     app?: string | undefined;
-} & Record<string, unknown>) => Effect.Effect<void | undefined, import("../../../lib/ui.ts").UIError | import("../../../lib/http.ts").InstantHttpError | import("effect/Cause").TimeoutException | import("@effect/platform/HttpClientError").RequestError | import("effect/ParseResult").ParseError | import("@effect/platform/HttpClientError").ResponseError, GlobalOpts | import("../../../lib/http.ts").InstantHttpAuthed | import("../../../context/currentApp.ts").CurrentApp>;
+} & Record<string, unknown>) => Effect.Effect<void | undefined, import("../../../lib/ui.ts").UIError | import("../../../lib/http.ts").InstantHttpError | import("effect/Cause").TimeoutException | import("@effect/platform/HttpClientError").RequestError | import("effect/ParseResult").ParseError | import("@effect/platform/HttpClientError").ResponseError, GlobalOpts | FileSystem.FileSystem | import("../../../lib/http.ts").InstantHttpAuthed | import("../../../context/currentApp.ts").CurrentApp>;
 //# sourceMappingURL=add.d.ts.map

package/dist/commands/auth/client/add.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../../../src/commands/auth/client/add.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAyB,MAAM,QAAQ,CAAC;AAGvD,OAAO,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAqX5D,eAAO,MAAM,gBAAgB;;;;qdA0D5B,CAAC"}
+{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../../../src/commands/auth/client/add.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAyB,MAAM,QAAQ,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C,OAAO,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AA0lB5D,eAAO,MAAM,gBAAgB;;;;6eAyD5B,CAAC"}

package/dist/commands/auth/client/add.js

@@ -1,13 +1,14 @@
 import { Effect, Match, Option, Schema } from 'effect';
+import { FileSystem } from '@effect/platform';
 import { BadArgsError } from "../../../errors.js";
 import { GlobalOpts } from "../../../context/globalOpts.js";
-import { optOrPrompt, runUIEffect, stripFirstBlankLine, validateRequired, } from "../../../lib/ui.js";
+import { optOrPrompt, optOrPromptBoolean, runUIEffect, stripFirstBlankLine, validateRequired, } from "../../../lib/ui.js";
 import { addOAuthClient, addOAuthProvider, getAppsAuth, } from "../../../lib/oauth.js";
-import { GOOGLE_AUTHORIZATION_ENDPOINT, GOOGLE_DEFAULT_CALLBACK_URL, GOOGLE_DISCOVERY_ENDPOINT, GOOGLE_TOKEN_ENDPOINT, } from '@instantdb/platform';
+import { GOOGLE_AUTHORIZATION_ENDPOINT, GOOGLE_DEFAULT_CALLBACK_URL, GOOGLE_DISCOVERY_ENDPOINT, GOOGLE_TOKEN_ENDPOINT, APPLE_AUTHORIZATION_ENDPOINT, APPLE_DEFAULT_CALLBACK_URL, APPLE_DISCOVERY_ENDPOINT, APPLE_TOKEN_ENDPOINT, } from '@instantdb/platform';
 import { UI } from "../../../ui/index.js";
 import chalk from 'chalk';
 import boxen from 'boxen';
-const ClientTypeSchema = Schema.Literal('google', 'github');
+const ClientTypeSchema = Schema.Literal('google', 'github', 'apple');
 const GoogleAppTypeSchema = Schema.Literal('web', 'ios', 'android', 'button-for-web');
 const selectGoogleAppType = (value) => Effect.gen(function* () {
     const { yes } = yield* GlobalOpts;
@@ -262,6 +263,184 @@ ${chalk.dim('Your URI must forward to https://api.instantdb.com/runtime/oauth/ca
         ...redirectMessages,
     ].join('\n'), { dimBorder: true, padding: { right: 1, left: 1 } }));
 });
+const readPrivateKeyFile = Effect.fn('readPrivateKeyFile')(function* (path) {
+    const fs = yield* FileSystem.FileSystem;
+    // Strip shell-escape backslashes so paths like "file\ (2).p8" resolve correctly.
+    // Only on POSIX — Windows uses backslashes as path separators.
+    const normalizedPath = process.platform === 'win32' ? path : path.replace(/\\(.)/g, '$1');
+    const contents = yield* fs.readFileString(normalizedPath, 'utf8').pipe(Effect.mapError((e) => new BadArgsError({
+        message: `Could not read private key file at ${normalizedPath}: ${e.message}`,
+    })));
+    const trimmed = contents.trim();
+    if (!trimmed) {
+        return yield* BadArgsError.make({
+            message: `Private key file at ${normalizedPath} is empty.`,
+        });
+    }
+    return trimmed;
+});
+const handleAppleClient = Effect.fn(function* (opts) {
+    const { yes } = yield* GlobalOpts;
+    const { auth, provider } = yield* getOrCreateProvider('apple');
+    const usedClientNames = new Set((auth.oauth_clients ?? []).map((client) => client.client_name));
+    const suggestedClientName = findName('apple', usedClientNames);
+    const clientName = yield* optOrPrompt(opts.name, {
+        simpleName: '--name',
+        required: true,
+        skipIf: false,
+        prompt: {
+            prompt: 'Client Name:',
+            defaultValue: suggestedClientName,
+            placeholder: suggestedClientName,
+            validate: validateRequired,
+            modifyOutput: UI.modifiers.piped([UI.modifiers.dimOnComplete]),
+        },
+    });
+    if (usedClientNames.has(clientName || '')) {
+        return yield* BadArgsError.make({
+            message: `The unique name '${clientName}' is already in use.`,
+        });
+    }
+    const servicesId = yield* optOrPrompt(opts['services-id'], {
+        simpleName: '--services-id',
+        required: true,
+        skipIf: false,
+        prompt: {
+            prompt: `Services ID ${chalk.dim('(from https://developer.apple.com/account/resources/identifiers/list/serviceId)')}`,
+            modifyOutput: UI.modifiers.piped([
+                UI.modifiers.topPadding,
+                UI.modifiers.dimOnComplete,
+            ]),
+            validate: validateRequired,
+        },
+    });
+    // If any web-flow flag is provided, enable web flow; otherwise ask
+    // (non-interactively with --yes we default to native-only).
+    const anyWebFlagProvided = Boolean(opts['team-id'] || opts['key-id'] || opts['private-key-file']);
+    const configureWeb = anyWebFlagProvided
+        ? true
+        : yes
+            ? false
+            : yield* optOrPromptBoolean(undefined, {
+                simpleName: '--configure-web',
+                required: false,
+                skipIf: false,
+                prompt: {
+                    promptText: 'Configure web redirect flow? ' +
+                        chalk.dim('(requires Team ID, Key ID, and a .p8 private key from Apple)'),
+                    defaultValue: false,
+                },
+            });
+    const skipWeb = !configureWeb;
+    const webSkipMessage = 'requires configuring the web redirect flow (also provide --team-id, --key-id, and --private-key-file).';
+    const teamId = yield* optOrPrompt(opts['team-id'], {
+        simpleName: '--team-id',
+        required: true,
+        skipIf: skipWeb,
+        skipMessage: `--team-id ${webSkipMessage}`,
+        prompt: {
+            prompt: `Team ID ${chalk.dim('(from https://developer.apple.com/account#MembershipDetailsCard)')}`,
+            validate: validateRequired,
+            modifyOutput: UI.modifiers.piped([
+                UI.modifiers.topPadding,
+                UI.modifiers.dimOnComplete,
+            ]),
+        },
+    });
+    const keyId = yield* optOrPrompt(opts['key-id'], {
+        simpleName: '--key-id',
+        required: true,
+        skipIf: skipWeb,
+        skipMessage: `--key-id ${webSkipMessage}`,
+        prompt: {
+            prompt: `Key ID ${chalk.dim('(from https://developer.apple.com/account/resources/authkeys/list)')}`,
+            validate: validateRequired,
+            modifyOutput: UI.modifiers.piped([
+                UI.modifiers.topPadding,
+                UI.modifiers.dimOnComplete,
+            ]),
+        },
+    });
+    const privateKeyPath = yield* optOrPrompt(opts['private-key-file'], {
+        simpleName: '--private-key-file',
+        required: true,
+        skipIf: skipWeb,
+        skipMessage: `--private-key-file ${webSkipMessage}`,
+        prompt: {
+            prompt: `Path to .p8 private key file ${chalk.dim('(downloaded from Apple)')}`,
+            validate: validateRequired,
+            modifyOutput: UI.modifiers.piped([
+                UI.modifiers.topPadding,
+                UI.modifiers.dimOnComplete,
+            ]),
+        },
+    });
+    const privateKey = privateKeyPath
+        ? yield* readPrivateKeyFile(privateKeyPath)
+        : undefined;
+    const customRedirectUri = yield* optOrPrompt(opts['custom-redirect-uri'], {
+        required: false,
+        simpleName: '--custom-redirect-uri',
+        skipIf: skipWeb,
+        skipMessage: `--custom-redirect-uri ${webSkipMessage}`,
+        prompt: {
+            prompt: '',
+            placeholder: 'https://yoursite.com/oauth/callback',
+            modifyOutput: UI.modifiers.piped([
+                (output, status) => {
+                    if (status === 'idle') {
+                        return (`\nCustom redirect URI (optional):
+${chalk.dim('With a custom redirect URI, users will see "Redirecting to yoursite.com..." for a more branded experience.')}
+${chalk.dim('Your URI must forward to https://api.instantdb.com/runtime/oauth/callback with all query parameters preserved.')}\n\n` +
+                            stripFirstBlankLine(output));
+                    }
+                    return `\nCustom redirect URI (optional):\n${stripFirstBlankLine(output)}`;
+                },
+                UI.modifiers.dimOnComplete,
+            ]),
+        },
+    });
+    if (!clientName) {
+        return yield* BadArgsError.make({ message: 'Client name is required.' });
+    }
+    const redirectUri = privateKey
+        ? customRedirectUri || APPLE_DEFAULT_CALLBACK_URL
+        : undefined;
+    const meta = {};
+    if (teamId !== undefined)
+        meta.teamId = teamId;
+    if (keyId !== undefined)
+        meta.keyId = keyId;
+    const response = yield* addOAuthClient({
+        providerId: provider.id,
+        clientName,
+        clientId: servicesId,
+        clientSecret: privateKey,
+        authorizationEndpoint: APPLE_AUTHORIZATION_ENDPOINT,
+        tokenEndpoint: APPLE_TOKEN_ENDPOINT,
+        discoveryEndpoint: APPLE_DISCOVERY_ENDPOINT,
+        redirectTo: redirectUri,
+        ...(Object.keys(meta).length > 0 ? { meta } : {}),
+    });
+    const summaryLines = [
+        `Apple OAuth client created: ${response.client.client_name}`,
+        `ID: ${response.client.id}`,
+        `Services ID: ${response.client.client_id ?? servicesId}`,
+    ];
+    if (privateKey) {
+        summaryLines.push(`Team ID: ${teamId}`);
+        summaryLines.push(`Key ID: ${keyId}`);
+        summaryLines.push(chalk.bold(`\nAdd this return URL under your Services ID on developer.apple.com:\n${redirectUri}\n`));
+        if (customRedirectUri) {
+            summaryLines.push(`Your custom redirect must forward to ${chalk.bold(APPLE_DEFAULT_CALLBACK_URL)} with all query parameters preserved.`);
+            summaryLines.push(`You can test it by visiting: ${chalk.bold(redirectUri + '?test-redirect=true')}`);
+        }
+    }
+    yield* Effect.log(boxen(summaryLines.join('\n'), {
+        dimBorder: true,
+        padding: { right: 1, left: 1 },
+    }));
+});
 export const authClientAddCmd = Effect.fn(function* (opts) {
     const { yes } = yield* GlobalOpts;
     if (!opts.type && yes) {
@@ -273,8 +452,8 @@ export const authClientAddCmd = Effect.fn(function* (opts) {
         options: [
             { label: 'Google', value: 'google' },
             { label: 'GitHub', value: 'github' },
+            { label: 'Apple', value: 'apple' },
             // TODO: implement
-            // { label: 'Apple', value: 'apple' },
             // { label: 'LinkedIn', value: 'linkedin' },
             // { label: 'Clerk', value: 'clerk' },
             // { label: 'Firebase', value: 'firebase' },
@@ -282,10 +461,9 @@ export const authClientAddCmd = Effect.fn(function* (opts) {
         promptText: 'Select a client type:',
         modifyOutput: UI.modifiers.piped([UI.modifiers.dimOnComplete]),
     }))), Effect.andThen((s) => Schema.decodeUnknown(ClientTypeSchema)(s)), Effect.catchTag('ParseError', () => BadArgsError.make({
-        message: 'Invalid client type, must be one of: google, apple, github, linkedin, clerk, firebase',
+        message: `Invalid client type, must be one of: ${ClientTypeSchema.literals.join(', ')}`,
     })));
-    yield* Match.value(clientType).pipe(Match.withReturnType(), Match.when('google', () => handleGoogleClient(opts)), Match.when('github', () => handleGithubClient(opts)), 
-    // Match.when('apple', () => Effect.logError('Not Implemented')),
+    yield* Match.value(clientType).pipe(Match.withReturnType(), Match.when('google', () => handleGoogleClient(opts)), Match.when('github', () => handleGithubClient(opts)), Match.when('apple', () => handleAppleClient(opts)), 
     // Match.when('clerk', () => Effect.logError('Not Implemented')),
     // Match.when('firebase', () => Effect.logError('Not Implemented')),
     // Match.when('linkedin', () => Effect.logError('Not Implemented')),