doomain 0.1.15 → 0.1.16

package/README.md

@@ -1,6 +1,6 @@
 # Doomain
 
-Doomain links a Vercel project to a custom domain from your terminal.
+Doomain links Vercel projects and first-time Clerk production instances to custom domains from your terminal.
 
 It handles the boring parts of custom-domain setup: selecting the Vercel project, finding the right DNS zone, adding the domain to Vercel, writing the Vercel DNS records, waiting for public DNS propagation, and asking Vercel to verify the domain.
 
@@ -16,6 +16,7 @@ Use the interactive wizard when working by hand. Use explicit commands with `--j
 - Safety checks before replacing DNS records that point elsewhere.
 - DNS propagation and Vercel verification wait loop.
 - DNS provider support for Spaceship, Namecheap, Cloudflare, and Hostinger.
+- First-time Clerk production setup with automatic CNAME configuration.
 
 ## Install
 
@@ -86,6 +87,17 @@ Apply it:
 doomain link app.example.com --project my-vercel-project --json
 ```
 
+Set up a Clerk application's first production instance and primary domain:
+
+```bash
+doomain auth clerk --platform-api-key "$CLERK_PLATFORM_API_KEY" --app app_123 --json
+doomain clerk domains add example.com --app app_123 --json
+```
+
+Create a Platform API key from the Clerk Dashboard API keys page. Platform keys start with `ak_`; Clerk instance secret keys (`sk_`) cannot create a production instance.
+
+This Clerk command intentionally aborts when the application already has a production instance. Change existing production domains manually in the Clerk Dashboard or with Clerk CLI.
+
 If JSON mode returns `DNS_TARGET_CONFLICT`, the current DNS target appears to point to another project or site. Re-run with `--force` only when you intend to replace that DNS target.
 
 ## Provider Setup
@@ -142,7 +154,7 @@ doomain providers connect cloudflare \
   --credential accountId=your_cloudflare_account_id
 ```
 
-Cloudflare records created for Vercel `A`, `AAAA`, and `CNAME` targets are set to `proxied: false` so Vercel can validate the domain.
+Cloudflare records created for Vercel or Clerk `A`, `AAAA`, and `CNAME` targets are set to `proxied: false` so the service can validate the domain.
 
 ### Hostinger
 
@@ -209,6 +221,27 @@ Use `-p` as shorthand for `--project`:
 doomain link app.example.com -p my-app
 ```
 
+## Clerk Production Domains
+
+`doomain clerk domains add` mirrors Clerk CLI's initial production deployment API. It creates a production instance by cloning the application's development instance, sets the requested primary domain, writes every CNAME returned by Clerk, and optionally waits for Clerk's DNS, SSL, and email DNS status.
+
+```bash
+doomain clerk domains add example.com --app app_123
+```
+
+Use `--dry-run` to verify that the application has no production instance and that Doomain can resolve the DNS zone. Clerk only returns the exact CNAME records after production is created, so they are not included in the dry-run result.
+
+If a production instance already exists, the command returns `CLERK_PRODUCTION_EXISTS` without changing DNS. Doomain does not automate production-domain migrations because Clerk domain changes can cause downtime and require publishable-key, OAuth redirect, and deployment updates.
+
+After creation, the result includes Clerk CLI follow-up commands. Run them to link the local project, pull production keys, finish production OAuth configuration, and verify provisioning:
+
+```bash
+clerk link --app app_123
+clerk env pull --app app_123 --instance prod
+clerk deploy
+clerk deploy status
+```
+
 ## What Gets Created
 
 For apex/root domains, Doomain creates Vercel's apex `A` record:
@@ -306,6 +339,7 @@ doomain providers list --json
 doomain providers status --no-verify --json
 doomain domains list --provider cloudflare --domain example.com --json
 doomain projects list --search my-app --json
+doomain clerk domains add example.com --app app_123 --json
 doomain schema --json
 doomain schema link --json
 ```
@@ -376,6 +410,28 @@ doomain auth logout vercel --json
 
 If `VERCEL_TOKEN` or `VERCEL_TEAM_ID` are still set, they continue to override local config.
 
+### `doomain auth clerk`
+
+Saves and verifies a Clerk Platform API key and default application id.
+
+```bash
+doomain auth clerk --platform-api-key ak_123 --app app_123
+```
+
+### `doomain auth logout clerk`
+
+Removes saved Clerk credentials. `CLERK_PLATFORM_API_KEY` and `CLERK_APPLICATION_ID` continue to override local config when set.
+
+### `doomain clerk domains add <domain>`
+
+Creates the application's first Clerk production instance and primary domain, then configures Clerk's returned CNAME records.
+
+```bash
+doomain clerk domains add example.com --app app_123
+doomain clerk domains add example.com --app app_123 --dry-run --json
+doomain clerk domains add example.com --app app_123 --no-wait --json
+```
+
 ### `doomain providers list`
 
 Lists supported DNS providers.
@@ -491,6 +547,13 @@ VERCEL_TOKEN
 VERCEL_TEAM_ID
 ```
 
+Clerk:
+
+```bash
+CLERK_PLATFORM_API_KEY
+CLERK_APPLICATION_ID
+```
+
 Spaceship:
 
 ```bash

package/dist/commands/auth/clerk.d.ts

@@ -0,0 +1,11 @@
+import { Command } from '@oclif/core';
+export default class AuthClerk extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        app: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'platform-api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/auth/clerk.js

@@ -0,0 +1,55 @@
+import { Command, Flags } from '@oclif/core';
+import * as p from '@clack/prompts';
+import { createClerkPlatformClient } from '../../lib/clerk.js';
+import { getConfigPath, maskSecret, updateConfig } from '../../lib/config.js';
+import { jsonFlag } from '../../lib/flags.js';
+import { createOutput, outputError } from '../../lib/output.js';
+function value(input, message) {
+    const resolved = input?.trim();
+    if (!resolved)
+        throw new Error(message);
+    return resolved;
+}
+export default class AuthClerk extends Command {
+    static description = 'Save Clerk Platform API credentials locally.';
+    static examples = ['<%= config.bin %> <%= command.id %> --platform-api-key ak_123 --app app_123 --json'];
+    static flags = {
+        app: Flags.string({ description: 'Default Clerk application id.' }),
+        json: jsonFlag,
+        'platform-api-key': Flags.string({ description: 'Clerk Platform API key (ak_...).' }),
+    };
+    async run() {
+        const { flags } = await this.parse(AuthClerk);
+        const out = createOutput({ json: flags.json });
+        try {
+            let platformApiKey = flags['platform-api-key'] ?? process.env.CLERK_PLATFORM_API_KEY;
+            let appId = flags.app ?? process.env.CLERK_APPLICATION_ID;
+            if (!out.json) {
+                if (!platformApiKey) {
+                    const entered = await p.password({ message: 'Clerk Platform API key' });
+                    if (p.isCancel(entered))
+                        return;
+                    platformApiKey = entered;
+                }
+                if (!appId) {
+                    const entered = await p.text({ message: 'Default Clerk application id' });
+                    if (p.isCancel(entered))
+                        return;
+                    appId = entered;
+                }
+            }
+            platformApiKey = value(platformApiKey, 'Missing Clerk Platform API key. Pass --platform-api-key or set CLERK_PLATFORM_API_KEY.');
+            appId = value(appId, 'Missing Clerk application id. Pass --app or set CLERK_APPLICATION_ID.');
+            if (!platformApiKey.startsWith('ak_'))
+                throw new Error('Clerk Platform API keys must start with ak_.');
+            await createClerkPlatformClient({ platformApiKey }).fetchApplication(appId);
+            await updateConfig((config) => ({ ...config, clerk: { appId, platformApiKey } }));
+            out.result({ clerk: { appId, platformApiKey: maskSecret(platformApiKey) }, configPath: getConfigPath() });
+            out.success(`Clerk credentials saved to ${getConfigPath()}.`);
+        }
+        catch (error) {
+            outputError(out.json, error, 'CLERK_AUTH_FAILED');
+            this.exit(1);
+        }
+    }
+}

package/dist/commands/auth/logout/clerk.d.ts

@@ -0,0 +1,8 @@
+import { Command } from '@oclif/core';
+export default class AuthLogoutClerk extends Command {
+    static description: string;
+    static flags: {
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/auth/logout/clerk.js

@@ -0,0 +1,29 @@
+import { Command } from '@oclif/core';
+import { getConfigPath, updateConfig } from '../../../lib/config.js';
+import { jsonFlag } from '../../../lib/flags.js';
+import { createOutput, outputError } from '../../../lib/output.js';
+export default class AuthLogoutClerk extends Command {
+    static description = 'Remove saved Clerk credentials locally.';
+    static flags = { json: jsonFlag };
+    async run() {
+        const { flags } = await this.parse(AuthLogoutClerk);
+        const out = createOutput({ json: flags.json });
+        try {
+            let removed = false;
+            await updateConfig((config) => {
+                removed = config.clerk !== undefined;
+                const { clerk: _clerk, ...next } = config;
+                return next;
+            });
+            const environmentOverrides = ['CLERK_PLATFORM_API_KEY', 'CLERK_APPLICATION_ID'].filter((key) => process.env[key]);
+            out.result({ configPath: getConfigPath(), environmentOverrides, removed, service: 'clerk' });
+            if (environmentOverrides.length > 0)
+                out.warn(`Clerk environment credentials are still set: ${environmentOverrides.join(', ')}.`);
+            out.success(removed ? `Clerk credentials removed from ${getConfigPath()}.` : 'Clerk credentials were not saved.');
+        }
+        catch (error) {
+            outputError(out.json, error, 'MISSING_CREDENTIALS');
+            this.exit(1);
+        }
+    }
+}

package/dist/commands/clerk/domains/add.d.ts

@@ -0,0 +1,19 @@
+import { Command } from '@oclif/core';
+export default class ClerkDomainsAdd extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        domain: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        account: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        app: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        provider: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        timeout: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        wait: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/clerk/domains/add.js

@@ -0,0 +1,92 @@
+import { Args, Command, Flags } from '@oclif/core';
+import * as p from '@clack/prompts';
+import { addClerkProductionDomain } from '../../../lib/clerk-domain.js';
+import { accountFlag, jsonFlag, providerFlag } from '../../../lib/flags.js';
+import { createOutput, outputError } from '../../../lib/output.js';
+function recordLine(record) {
+    return `${record.type} ${record.name} -> ${record.value}${record.proxied === undefined ? '' : ` (proxied ${record.proxied})`}`;
+}
+function conflictNote(warning) {
+    return [
+        'Existing:',
+        ...warning.conflicts.map((conflict) => `- ${recordLine(conflict.existing)}`),
+        '',
+        'Required by Clerk:',
+        ...warning.desired.map((record) => `- ${recordLine(record)}`),
+    ].join('\n');
+}
+function resultMessage(result) {
+    if (result.clerk.verified)
+        return `${result.domain} is configured and verified for Clerk production.`;
+    return `${result.domain} is configured for Clerk production. Run ${result.nextSteps.at(-1)} to check provisioning.`;
+}
+export default class ClerkDomainsAdd extends Command {
+    static description = 'Create a Clerk production instance with its primary domain and configure DNS.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> example.com --app app_123 --json',
+        '<%= config.bin %> <%= command.id %> example.com --app app_123 --provider cloudflare --no-wait',
+        '<%= config.bin %> <%= command.id %> example.com --app app_123 --dry-run --json',
+    ];
+    static args = {
+        domain: Args.string({ description: 'Production primary domain, for example example.com.', required: true }),
+    };
+    static flags = {
+        account: accountFlag,
+        app: Flags.string({ description: 'Clerk application id. Defaults to CLERK_APPLICATION_ID or saved Clerk config.' }),
+        'dry-run': Flags.boolean({ description: 'Check the Clerk application and DNS zone without creating the production instance.' }),
+        force: Flags.boolean({ description: 'Overwrite DNS records that conflict with Clerk requirements.' }),
+        json: jsonFlag,
+        provider: providerFlag,
+        timeout: Flags.integer({ default: 300, description: 'Wait timeout in seconds.' }),
+        wait: Flags.boolean({ allowNo: true, default: true, description: 'Wait for Clerk DNS, SSL, and email DNS verification.' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(ClerkDomainsAdd);
+        const out = createOutput({ json: flags.json });
+        let spinner;
+        try {
+            if (!out.json && !flags['dry-run']) {
+                p.note(`This creates the first production instance for Clerk application ${flags.app ?? 'the configured app'} and sets ${args.domain} as its primary domain. Existing production instances are never modified.`, 'Clerk production setup');
+                const confirmed = await p.confirm({ message: 'Create the Clerk production instance?', initialValue: false });
+                if (confirmed !== true) {
+                    p.cancel('Cancelled');
+                    return;
+                }
+            }
+            spinner = out.spinner();
+            spinner.start(flags['dry-run'] ? 'Checking Clerk production setup' : 'Creating Clerk production setup');
+            const result = await addClerkProductionDomain({
+                account: flags.account,
+                app: flags.app,
+                confirmDnsOverride: out.json
+                    ? undefined
+                    : async (warning) => {
+                        spinner?.stop('DNS conflict found');
+                        p.note(conflictNote(warning), 'DNS records point elsewhere');
+                        const confirmed = await p.confirm({ message: 'Overwrite these DNS records?', initialValue: false });
+                        if (confirmed === true)
+                            spinner?.start('Continuing Clerk production setup');
+                        return confirmed === true;
+                    },
+                domain: args.domain,
+                dryRun: flags['dry-run'],
+                force: flags.force,
+                progress: out.json ? undefined : (message) => spinner?.message(message),
+                provider: flags.provider,
+                timeoutSeconds: flags.timeout,
+                wait: flags.wait,
+            });
+            spinner.stop(flags['dry-run'] ? 'Clerk production setup is available' : 'Clerk production domain configured');
+            out.result(result);
+            if (!out.json) {
+                p.note(result.nextSteps.map((step) => `- ${step}`).join('\n'), 'Next steps');
+                out.outro(flags['dry-run'] ? `Ready to create Clerk production for ${result.domain}.` : resultMessage(result));
+            }
+        }
+        catch (error) {
+            spinner?.error('Clerk production setup failed');
+            outputError(out.json, error, 'DOMAIN_LINK_FAILED');
+            this.exit(1);
+        }
+    }
+}

package/dist/lib/clerk-domain.d.ts

@@ -0,0 +1,39 @@
+import { type ClerkDomainStatus } from './clerk.js';
+import { type DnsOverrideWarning } from './link-domain.js';
+import type { DnsRecordInput } from './providers/types.js';
+export interface AddClerkDomainInput {
+    account?: string;
+    app?: string;
+    domain?: string;
+    dryRun?: boolean;
+    force?: boolean;
+    provider?: string;
+    wait?: boolean;
+    timeoutSeconds?: number;
+    confirmDnsOverride?: (warning: DnsOverrideWarning) => Promise<boolean>;
+    progress?: (message: string) => void;
+}
+export interface AddClerkDomainResult {
+    account: string;
+    app: string;
+    clerk: {
+        domainId?: string;
+        productionInstanceCreated: boolean;
+        productionInstanceId?: string;
+        status?: ClerkDomainStatus;
+        verified: boolean;
+    };
+    dns: {
+        propagated: boolean;
+        skipped: DnsRecordInput[];
+        updated: boolean;
+    };
+    domain: string;
+    dryRun: boolean;
+    isDefaultAccount: boolean;
+    provider: string;
+    records: DnsRecordInput[];
+    zoneDomain: string;
+    nextSteps: string[];
+}
+export declare function addClerkProductionDomain(input: AddClerkDomainInput): Promise<AddClerkDomainResult>;

package/dist/lib/clerk-domain.js

@@ -0,0 +1,162 @@
+import { createClerkPlatformClient, resolveClerkPlatformConfig } from './clerk.js';
+import { DoomainError } from './errors.js';
+import { resolveProviderTarget, withProviderRecordOptions } from './link-domain.js';
+import { createProvider } from './providers/registry.js';
+import { normalizeDomain } from './validate.js';
+function relativeRecordName(host, zoneDomain) {
+    const normalized = host.trim().toLowerCase().replace(/\.$/, '');
+    if (normalized === zoneDomain)
+        return '@';
+    if (!normalized.endsWith(`.${zoneDomain}`)) {
+        throw new DoomainError('INVALID_INPUT', `Clerk returned DNS host ${host}, which is outside the selected zone ${zoneDomain}.`);
+    }
+    return normalized.slice(0, -(zoneDomain.length + 1));
+}
+function recordsFromTargets(provider, zoneDomain, targets) {
+    return targets.map((target) => withProviderRecordOptions(provider, {
+        name: relativeRecordName(target.host, zoneDomain),
+        ttl: 300,
+        type: 'CNAME',
+        value: target.value.trim().replace(/\.$/, ''),
+    }));
+}
+function productionExistsError(app, instanceId) {
+    return new DoomainError('CLERK_PRODUCTION_EXISTS', `Clerk application ${app} already has a production instance. Configure domain changes manually in Clerk; Doomain will not modify an existing production domain.`, {
+        app,
+        instanceId,
+        recovery: 'Use the Clerk Dashboard Domains page or `clerk deploy` to inspect and configure the existing production instance.',
+        suggestedCommands: [`clerk link --app ${app}`, 'clerk deploy status', 'clerk open domains'],
+    });
+}
+function dnsConflictError(warning, productionInstanceId) {
+    return new DoomainError('DNS_TARGET_CONFLICT', `${warning.domain} has DNS records that conflict with Clerk's required records. Re-run with --force to overwrite them.`, {
+        ...warning,
+        partialState: { productionInstanceCreated: true, productionInstanceId },
+        recovery: 'The Clerk production instance now exists. Resolve the DNS conflict, then finish setup with `clerk deploy`.',
+    });
+}
+function statusComplete(check) {
+    return check?.required === false || check?.status === 'complete';
+}
+async function waitForStatus(client, app, domainId, timeoutSeconds, progress) {
+    await client.triggerDomainDnsCheck(app, domainId).catch((error) => {
+        const conflict = error instanceof DoomainError && JSON.stringify(error.details).toLowerCase().includes('conflict');
+        if (!conflict)
+            throw error;
+    });
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    let status = { status: 'incomplete' };
+    let attempt = 1;
+    while (Date.now() <= deadline) {
+        progress?.(`Checking Clerk DNS, SSL, and email DNS status (attempt ${attempt})`);
+        status = await client.getDomainStatus(app, domainId);
+        if (status.status === 'complete')
+            return status;
+        attempt += 1;
+        if (Date.now() > deadline)
+            break;
+        await new Promise((resolve) => setTimeout(resolve, 5000));
+    }
+    return status;
+}
+export async function addClerkProductionDomain(input) {
+    const domain = normalizeDomain(input.domain ?? '');
+    const config = await resolveClerkPlatformConfig(input.app);
+    const client = createClerkPlatformClient(config);
+    input.progress?.('Checking Clerk application');
+    const application = await client.fetchApplication(config.appId);
+    const production = application.instances.find((instance) => instance.environment_type === 'production');
+    if (production)
+        throw productionExistsError(config.appId, production.instance_id);
+    const development = application.instances.find((instance) => instance.environment_type === 'development');
+    if (!development)
+        throw new DoomainError('PROJECT_NOT_FOUND', `Clerk application ${config.appId} does not have a development instance to clone.`);
+    input.progress?.('Finding the DNS provider and zone');
+    const resolved = await resolveProviderTarget({ account: input.account, domain, provider: input.provider });
+    const provider = await createProvider(resolved.provider, { account: resolved.account });
+    const zone = await provider.getZone(resolved.target.zoneDomain);
+    if (!zone)
+        throw new DoomainError('PROVIDER_ZONE_NOT_FOUND', `${provider.name} does not have a DNS zone for ${resolved.target.zoneDomain}.`);
+    const nextSteps = [
+        `clerk link --app ${config.appId}`,
+        `clerk env pull --app ${config.appId} --instance prod`,
+        'clerk deploy',
+        'clerk deploy status',
+    ];
+    if (input.dryRun) {
+        return {
+            account: resolved.account,
+            app: config.appId,
+            clerk: { productionInstanceCreated: false, verified: false },
+            dns: { propagated: false, skipped: [], updated: false },
+            domain,
+            dryRun: true,
+            isDefaultAccount: resolved.isDefaultAccount,
+            nextSteps,
+            provider: resolved.provider,
+            records: [],
+            zoneDomain: resolved.target.zoneDomain,
+        };
+    }
+    input.progress?.('Creating Clerk production instance and primary domain');
+    const created = await client.createProductionInstance(config.appId, domain, development.instance_id);
+    const clerkDomain = created.active_domain;
+    if (!clerkDomain) {
+        throw new DoomainError('DOMAIN_LINK_FAILED', 'Clerk created the production instance but did not return its primary domain.', {
+            productionInstanceId: created.id,
+        });
+    }
+    const records = recordsFromTargets(resolved.provider, resolved.target.zoneDomain, clerkDomain.cname_targets ?? []);
+    if (records.length === 0) {
+        throw new DoomainError('DOMAIN_LINK_FAILED', 'Clerk created the production instance but did not return any DNS records.', {
+            domainId: clerkDomain.id,
+            productionInstanceId: created.id,
+        });
+    }
+    input.progress?.(`Checking existing DNS records in ${provider.name}`);
+    let forceDns = Boolean(input.force);
+    let dnsPlan = await provider.planChanges(zone, records, { force: forceDns });
+    if (!forceDns && dnsPlan.conflicts.length > 0) {
+        const warning = {
+            account: resolved.account,
+            conflicts: dnsPlan.conflicts,
+            desired: records,
+            domain,
+            provider: resolved.provider,
+            providerName: provider.name,
+            recordName: records[0]?.name ?? '@',
+            zoneDomain: resolved.target.zoneDomain,
+        };
+        forceDns = (await input.confirmDnsOverride?.(warning)) === true;
+        if (!forceDns)
+            throw dnsConflictError(warning, created.id);
+        dnsPlan = await provider.planChanges(zone, records, { force: true });
+    }
+    input.progress?.(`Creating Clerk DNS records in ${provider.name}`);
+    const dnsResult = await provider.applyChanges(zone, dnsPlan, { force: forceDns });
+    const shouldWait = input.wait ?? true;
+    const status = shouldWait
+        ? await waitForStatus(client, config.appId, clerkDomain.id, input.timeoutSeconds ?? 300, input.progress)
+        : undefined;
+    const verified = status?.status === 'complete';
+    const propagated = Boolean(status && statusComplete(status.dns) && statusComplete(status.mail));
+    return {
+        account: resolved.account,
+        app: config.appId,
+        clerk: {
+            domainId: clerkDomain.id,
+            productionInstanceCreated: true,
+            productionInstanceId: created.id,
+            status,
+            verified,
+        },
+        dns: { propagated, skipped: dnsResult.skipped, updated: dnsResult.applied.length > 0 },
+        domain,
+        dryRun: false,
+        isDefaultAccount: resolved.isDefaultAccount,
+        nextSteps,
+        provider: resolved.provider,
+        records,
+        zoneDomain: resolved.target.zoneDomain,
+    };
+}

package/dist/lib/clerk.d.ts

@@ -0,0 +1,56 @@
+export interface ClerkPlatformConfig {
+    appId: string;
+    platformApiKey: string;
+}
+export interface ClerkApplication {
+    application_id: string;
+    name?: string;
+    instances: Array<{
+        environment_type: string;
+        instance_id: string;
+        publishable_key: string;
+    }>;
+}
+export interface ClerkCnameTarget {
+    host: string;
+    required: boolean;
+    value: string;
+}
+export interface ClerkApplicationDomain {
+    cname_targets?: ClerkCnameTarget[];
+    frontend_api_url: string;
+    id: string;
+    is_satellite: boolean;
+    name: string;
+}
+export interface ClerkProductionInstance {
+    active_domain: ClerkApplicationDomain | null;
+    environment_type: 'production';
+    id: string;
+    publishable_key: string;
+}
+export interface ClerkDomainStatus {
+    dns?: {
+        required?: boolean;
+        status: string;
+    };
+    mail?: {
+        required?: boolean;
+        status: string;
+    };
+    ssl?: {
+        required?: boolean;
+        status: string;
+    };
+    status: string;
+}
+export declare function resolveClerkPlatformConfig(appId?: string): Promise<ClerkPlatformConfig>;
+export declare function createClerkPlatformClient(config: {
+    platformApiKey: string;
+}): {
+    fetchApplication(appId: string): Promise<ClerkApplication>;
+    createProductionInstance(appId: string, domain: string, developmentInstanceId: string): Promise<ClerkProductionInstance>;
+    getDomainStatus(appId: string, domainId: string): Promise<ClerkDomainStatus>;
+    triggerDomainDnsCheck(appId: string, domainId: string): Promise<ClerkDomainStatus>;
+};
+export type ClerkPlatformClient = ReturnType<typeof createClerkPlatformClient>;

package/dist/lib/clerk.js

@@ -0,0 +1,65 @@
+import { loadConfig } from './config.js';
+import { DoomainError } from './errors.js';
+const CLERK_API_URL = 'https://api.clerk.com';
+export async function resolveClerkPlatformConfig(appId) {
+    const config = await loadConfig();
+    const platformApiKey = process.env.CLERK_PLATFORM_API_KEY || config.clerk?.platformApiKey;
+    const resolvedAppId = appId || process.env.CLERK_APPLICATION_ID || config.clerk?.appId;
+    if (!platformApiKey) {
+        throw new DoomainError('MISSING_CREDENTIALS', 'Missing Clerk Platform API key. Run `doomain auth clerk`, set CLERK_PLATFORM_API_KEY, or pass saved credentials.');
+    }
+    if (!platformApiKey.startsWith('ak_')) {
+        throw new DoomainError('INVALID_INPUT', 'Clerk Platform API keys must start with ak_.');
+    }
+    if (!resolvedAppId) {
+        throw new DoomainError('MISSING_ARGUMENT', 'Clerk application is required. Pass --app, set CLERK_APPLICATION_ID, or save it with `doomain auth clerk`.');
+    }
+    return { appId: resolvedAppId, platformApiKey };
+}
+function apiErrorMessage(status, body) {
+    return body?.errors?.[0]?.long_message ?? body?.errors?.[0]?.message ?? body?.error?.message ?? body?.message ?? `Clerk API error (${status}).`;
+}
+function apiErrorCode(body) {
+    return body?.errors?.[0]?.code ?? body?.error?.code ?? body?.code;
+}
+export function createClerkPlatformClient(config) {
+    async function request(path, init = {}) {
+        const response = await fetch(`${CLERK_API_URL}${path}`, {
+            ...init,
+            headers: {
+                Accept: 'application/json',
+                Authorization: `Bearer ${config.platformApiKey}`,
+                ...(init.body ? { 'Content-Type': 'application/json' } : {}),
+                ...(init.headers ?? {}),
+            },
+        });
+        if (!response.ok) {
+            const body = (await response.json().catch(() => undefined));
+            if (response.status === 401 || response.status === 403) {
+                throw new DoomainError('CLERK_AUTH_FAILED', `Clerk Platform API authorization failed. Check CLERK_PLATFORM_API_KEY and its application access. ${apiErrorMessage(response.status, body)}`, body);
+            }
+            if (response.status === 409 && apiErrorCode(body) === 'production_instance_exists') {
+                throw new DoomainError('CLERK_PRODUCTION_EXISTS', 'This Clerk application already has a production instance. Configure domain changes manually in Clerk; Doomain will not modify it.', body);
+            }
+            throw new DoomainError('DOMAIN_LINK_FAILED', apiErrorMessage(response.status, body), body);
+        }
+        return (await response.json());
+    }
+    return {
+        fetchApplication(appId) {
+            return request(`/v1/platform/applications/${encodeURIComponent(appId)}`);
+        },
+        createProductionInstance(appId, domain, developmentInstanceId) {
+            return request(`/v1/platform/applications/${encodeURIComponent(appId)}/instances`, {
+                body: JSON.stringify({ clone_instance_id: developmentInstanceId, domain, environment_type: 'production' }),
+                method: 'POST',
+            });
+        },
+        getDomainStatus(appId, domainId) {
+            return request(`/v1/platform/applications/${encodeURIComponent(appId)}/domains/${encodeURIComponent(domainId)}/status`);
+        },
+        triggerDomainDnsCheck(appId, domainId) {
+            return request(`/v1/platform/applications/${encodeURIComponent(appId)}/domains/${encodeURIComponent(domainId)}/dns_check`, { method: 'POST' });
+        },
+    };
+}

package/dist/lib/command-schema.js

@@ -14,7 +14,7 @@ export const commandSchemas = [
         ],
         agentHint: 'For agent use, try `doomain link <domain> --json` first. Do not inspect project files, run provider status, or use --dry-run unless the user explicitly asks for a preview. The command infers project/provider and returns structured recovery errors when inference fails.',
         agentInstructions: [
-            'When the user asks to add or link a domain, run `doomain link <domain> --json` first.',
+            'When the user asks to add or link a Vercel domain, run `doomain link <domain> --json` first.',
             'Do not run `providers status`, `projects list`, `--help`, or `--dry-run` before the first link attempt unless the user asks for a preview or diagnosis.',
             'Only run follow-up commands when the JSON error includes a recovery action that requires them.',
         ],
@@ -46,6 +46,33 @@ export const commandSchemas = [
             { name: 'timeout', type: 'integer', description: 'Wait timeout in seconds.', default: 300 },
         ],
     },
+    {
+        name: 'clerk domains add',
+        description: 'Create the first Clerk production instance with its primary domain and configure returned DNS records.',
+        examples: [
+            'doomain clerk domains add example.com --app app_123 --json',
+            'doomain clerk domains add example.com --app app_123 --provider cloudflare --no-wait --json',
+            'doomain clerk domains add example.com --app app_123 --dry-run --json',
+        ],
+        agentHint: 'Use only for first-time Clerk production setup. The command aborts with CLERK_PRODUCTION_EXISTS when production already exists; domain changes must then be completed manually in Clerk.',
+        agentInstructions: [
+            'When the user asks to configure a Clerk production domain for the first time, run `doomain clerk domains add <domain> --app <app_id> --json`.',
+            'Never use this command to migrate or replace an existing Clerk production domain.',
+            'After success, follow the returned nextSteps to pull production keys, finish OAuth setup, and verify provisioning with Clerk CLI.',
+        ],
+        mutates: true,
+        safeForAgents: true,
+        flags: [
+            { name: 'json', type: 'boolean', description: 'Output a single JSON object and never prompt.' },
+            { name: 'app', type: 'string', description: 'Clerk application id. Defaults to CLERK_APPLICATION_ID or saved Clerk config.' },
+            { name: 'provider', type: 'string', description: 'DNS provider id. Inferred from the target domain when omitted.' },
+            { name: 'account', type: 'string', description: 'DNS provider profile/account alias. Defaults to the provider default account.' },
+            { name: 'dry-run', type: 'boolean', description: 'Check application eligibility and DNS zone without creating production.' },
+            { name: 'force', type: 'boolean', description: 'Overwrite DNS records that conflict with Clerk requirements.' },
+            { name: 'wait', type: 'boolean', description: 'Wait for Clerk DNS, SSL, and email DNS verification. Use --no-wait to skip waiting.', default: true },
+            { name: 'timeout', type: 'integer', description: 'Wait timeout in seconds.', default: 300 },
+        ],
+    },
     {
         name: 'schema',
         description: 'Print machine-readable command schemas for agents.',
@@ -132,6 +159,24 @@ export const commandSchemas = [
             { name: 'account', type: 'string', description: 'DNS provider profile/account alias. Defaults to the provider default account.' },
         ],
     },
+    {
+        name: 'auth clerk',
+        description: 'Save and verify Clerk Platform API credentials locally.',
+        examples: ['doomain auth clerk --platform-api-key ak_123 --app app_123 --json', 'doomain auth clerk'],
+        flags: [
+            { name: 'json', type: 'boolean', description: 'Output a single JSON object and never prompt.' },
+            { name: 'platform-api-key', type: 'string', description: 'Clerk Platform API key (ak_...).' },
+            { name: 'app', type: 'string', description: 'Default Clerk application id.' },
+        ],
+    },
+    {
+        name: 'auth logout clerk',
+        description: 'Remove saved Clerk credentials locally.',
+        examples: ['doomain auth logout clerk --json'],
+        flags: [
+            { name: 'json', type: 'boolean', description: 'Output a single JSON object and never prompt.' },
+        ],
+    },
     {
         name: 'auth vercel',
         description: 'Save Vercel credentials locally.',
@@ -204,7 +249,7 @@ async function configuredProviders() {
     }));
 }
 function withProviderConnections(schema, providers) {
-    if (schema.name !== 'link')
+    if (schema.name !== 'link' && schema.name !== 'clerk domains add')
         return schema;
     return { ...schema, configuredProviders: providers };
 }

package/dist/lib/config.d.ts

@@ -6,6 +6,10 @@ export interface VercelConfig {
     token?: string;
     teamId?: string;
 }
+export interface ClerkConfig {
+    appId?: string;
+    platformApiKey?: string;
+}
 export interface ProviderAccountConfig {
     credentials?: Record<string, string>;
     settings?: Record<string, unknown>;
@@ -19,6 +23,7 @@ export interface SpaceshipProviderConfig extends ProviderConfig {
     domains?: string[];
 }
 export interface DoomainConfig {
+    clerk?: ClerkConfig;
     vercel?: VercelConfig;
     providers?: {
         spaceship?: SpaceshipProviderConfig;

package/dist/lib/errors.d.ts

@@ -1,4 +1,4 @@
-export type DoomainErrorCode = 'CONFIG_NOT_FOUND' | 'DNS_TARGET_CONFLICT' | 'DOMAIN_LINK_FAILED' | 'DOMAIN_ALREADY_ASSIGNED' | 'DOMAIN_VERIFY_FAILED' | 'INVALID_INPUT' | 'MISSING_ARGUMENT' | 'MISSING_CREDENTIALS' | 'PROVIDER_API_ERROR' | 'PROVIDER_AUTH_FAILED' | 'PROVIDER_PERMISSION_DENIED' | 'PROVIDER_NOT_FOUND' | 'PROVIDER_RATE_LIMITED' | 'PROVIDER_RECORD_CONFLICT' | 'PROVIDER_UNSUPPORTED_RECORD' | 'PROVIDER_ZONE_AMBIGUOUS' | 'PROVIDER_ZONE_NOT_FOUND' | 'PROJECT_NOT_FOUND' | 'VERCEL_AUTH_FAILED' | 'VERCEL_PROJECT_NOT_LINKED';
+export type DoomainErrorCode = 'CONFIG_NOT_FOUND' | 'CLERK_AUTH_FAILED' | 'CLERK_PRODUCTION_EXISTS' | 'DNS_TARGET_CONFLICT' | 'DOMAIN_LINK_FAILED' | 'DOMAIN_ALREADY_ASSIGNED' | 'DOMAIN_VERIFY_FAILED' | 'INVALID_INPUT' | 'MISSING_ARGUMENT' | 'MISSING_CREDENTIALS' | 'PROVIDER_API_ERROR' | 'PROVIDER_AUTH_FAILED' | 'PROVIDER_PERMISSION_DENIED' | 'PROVIDER_NOT_FOUND' | 'PROVIDER_RATE_LIMITED' | 'PROVIDER_RECORD_CONFLICT' | 'PROVIDER_UNSUPPORTED_RECORD' | 'PROVIDER_ZONE_AMBIGUOUS' | 'PROVIDER_ZONE_NOT_FOUND' | 'PROJECT_NOT_FOUND' | 'VERCEL_AUTH_FAILED' | 'VERCEL_PROJECT_NOT_LINKED';
 export declare class DoomainError extends Error {
     readonly code: DoomainErrorCode;
     readonly details?: unknown;

package/dist/lib/link-domain.d.ts

@@ -59,6 +59,21 @@ export interface LinkDomainResult extends LinkDomainPlan {
         verified: boolean;
     };
 }
+export interface ResolvedDnsTarget {
+    provider: string;
+    providerInferred: boolean;
+    account: string;
+    accountInferred: boolean;
+    isDefaultAccount: boolean;
+    target: {
+        fullDomain: string;
+        isApex: boolean;
+        recordName: string;
+        zoneDomain: string;
+    };
+}
+export declare function resolveProviderTarget(input: Pick<LinkDomainInput, 'account' | 'apex' | 'domain' | 'provider' | 'subdomain'>): Promise<ResolvedDnsTarget>;
+export declare function withProviderRecordOptions(provider: string, record: DnsRecordInput): DnsRecordInput;
 export declare function verificationRecords(raw: unknown, zoneDomain: string): DnsRecordInput[];
 export declare function createLinkPlan(input: LinkDomainInput): Promise<LinkDomainPlan>;
 export declare function linkDomain(input: LinkDomainInput): Promise<LinkDomainResult>;

package/dist/lib/link-domain.js

@@ -248,7 +248,7 @@ async function loadConfiguredProviderZones(providerId, accountInput) {
         searched: results.map((result) => result.search),
     };
 }
-async function resolveProviderTarget(input) {
+export async function resolveProviderTarget(input) {
     const requested = resolveRequestedDomain({
         apex: input.apex,
         domain: await resolveConfiguredDomain(input.domain),
@@ -288,7 +288,7 @@ async function resolveProviderTarget(input) {
         target: targetFromZone(requested.fullDomain, selected.zone.name),
     };
 }
-function withProviderRecordOptions(provider, record) {
+export function withProviderRecordOptions(provider, record) {
     if (provider !== 'cloudflare' || !['A', 'AAAA', 'CNAME'].includes(record.type))
         return record;
     return { ...record, proxied: false };

package/oclif.manifest.json

@@ -225,6 +225,51 @@
         "wizard.js"
       ]
     },
+    "auth:clerk": {
+      "aliases": [],
+      "args": {},
+      "description": "Save Clerk Platform API credentials locally.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --platform-api-key ak_123 --app app_123 --json"
+      ],
+      "flags": {
+        "app": {
+          "description": "Default Clerk application id.",
+          "name": "app",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "json": {
+          "description": "Output a single JSON object and never prompt.",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "platform-api-key": {
+          "description": "Clerk Platform API key (ak_...).",
+          "name": "platform-api-key",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "auth:clerk",
+      "pluginAlias": "doomain",
+      "pluginName": "doomain",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "auth",
+        "clerk.js"
+      ]
+    },
     "auth:vercel": {
       "aliases": [],
       "args": {},
@@ -639,6 +684,35 @@
         "verify.js"
       ]
     },
+    "auth:logout:clerk": {
+      "aliases": [],
+      "args": {},
+      "description": "Remove saved Clerk credentials locally.",
+      "flags": {
+        "json": {
+          "description": "Output a single JSON object and never prompt.",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "auth:logout:clerk",
+      "pluginAlias": "doomain",
+      "pluginName": "doomain",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "auth",
+        "logout",
+        "clerk.js"
+      ]
+    },
     "auth:logout:vercel": {
       "aliases": [],
       "args": {},
@@ -671,7 +745,94 @@
         "logout",
         "vercel.js"
       ]
+    },
+    "clerk:domains:add": {
+      "aliases": [],
+      "args": {
+        "domain": {
+          "description": "Production primary domain, for example example.com.",
+          "name": "domain",
+          "required": true
+        }
+      },
+      "description": "Create a Clerk production instance with its primary domain and configure DNS.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> example.com --app app_123 --json",
+        "<%= config.bin %> <%= command.id %> example.com --app app_123 --provider cloudflare --no-wait",
+        "<%= config.bin %> <%= command.id %> example.com --app app_123 --dry-run --json"
+      ],
+      "flags": {
+        "account": {
+          "description": "DNS provider profile/account alias. Defaults to the provider default account.",
+          "name": "account",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "app": {
+          "description": "Clerk application id. Defaults to CLERK_APPLICATION_ID or saved Clerk config.",
+          "name": "app",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "dry-run": {
+          "description": "Check the Clerk application and DNS zone without creating the production instance.",
+          "name": "dry-run",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "force": {
+          "description": "Overwrite DNS records that conflict with Clerk requirements.",
+          "name": "force",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "json": {
+          "description": "Output a single JSON object and never prompt.",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "provider": {
+          "description": "DNS provider id. Inferred from the target domain when omitted.",
+          "name": "provider",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "timeout": {
+          "description": "Wait timeout in seconds.",
+          "name": "timeout",
+          "default": 300,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "wait": {
+          "description": "Wait for Clerk DNS, SSL, and email DNS verification.",
+          "name": "wait",
+          "allowNo": true,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "clerk:domains:add",
+      "pluginAlias": "doomain",
+      "pluginName": "doomain",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "clerk",
+        "domains",
+        "add.js"
+      ]
     }
   },
-  "version": "0.1.15"
+  "version": "0.1.16"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "doomain",
-  "description": "Link your vercel project and domain in seconds",
-  "version": "0.1.15",
+  "description": "Configure Vercel and Clerk production domains in seconds",
+  "version": "0.1.16",
   "author": "Crafter Station",
   "packageManager": "bun@1.3.13",
   "bin": {
@@ -39,7 +39,8 @@
   "keywords": [
     "dns",
     "domains",
-    "vercel"
+    "vercel",
+    "clerk"
   ],
   "license": "MIT",
   "main": "dist/index.js",
@@ -56,6 +57,9 @@
       "auth": {
         "description": "Manage authentication"
       },
+      "clerk": {
+        "description": "Configure Clerk production domains"
+      },
       "domains": {
         "description": "Inspect DNS domains"
       },