@flui-cloud/cli 0.0.1

package/lib/cli/src/commands/env/diag-ca.js

@@ -0,0 +1,192 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const chalk_1 = __importDefault(require("chalk"));
+const ora_1 = __importDefault(require("ora"));
+const nest_app_1 = require("../../lib/nest-app");
+const nip_base_domain_util_1 = require("../../lib/nip-base-domain.util");
+const cli_observability_cluster_service_1 = require("../../services/cli-observability-cluster.service");
+const cli_ssh_service_1 = require("../../services/cli-ssh.service");
+const context_banner_1 = require("../../lib/context-banner");
+class EnvDiagCA extends core_1.Command {
+    async run() {
+        (0, context_banner_1.printContextBanner)();
+        const spinner = (0, ora_1.default)('Connecting to cluster...').start();
+        try {
+            const app = await (0, nest_app_1.getNestApp)();
+            const observabilityService = app.get(cli_observability_cluster_service_1.CliObservabilityClusterService);
+            const sshService = app.get(cli_ssh_service_1.CliSshService);
+            const cluster = await observabilityService.getObservabilityCluster();
+            if (!this.assertClusterReady(cluster, spinner)) {
+                return;
+            }
+            spinner.succeed('Connected to cluster');
+            console.log(chalk_1.default.cyan('\n🔍 CA Diagnostic Report\n'));
+            console.log(chalk_1.default.dim('─'.repeat(80)));
+            this.checkLocalCaFiles();
+            await this.checkKubernetesSecret(sshService, cluster.masterIpAddress, spinner);
+            await this.checkApiPodEnvironment(sshService, cluster.masterIpAddress, spinner);
+            await this.checkApiCaStatusEndpoint(sshService, cluster, spinner);
+            this.printSummary();
+            await (0, nest_app_1.closeNestApp)();
+        }
+        catch (error) {
+            spinner.fail('Diagnostic failed');
+            console.log(chalk_1.default.red(`\n❌ Error: ${error.message}\n`));
+            await (0, nest_app_1.closeNestApp)();
+            this.exit(1);
+        }
+    }
+    assertClusterReady(cluster, spinner) {
+        if (!cluster) {
+            spinner.fail('No observability cluster found');
+            console.log(chalk_1.default.yellow('\n⚠️  No observability cluster exists.\n'));
+            console.log(chalk_1.default.dim('Create one with:'));
+            console.log(`   ${chalk_1.default.cyan('flui env create')}\n`);
+            return false;
+        }
+        if (!cluster.masterIpAddress) {
+            spinner.fail('Master IP not available');
+            console.log(chalk_1.default.red('\n❌ Master node does not have an IP address yet\n'));
+            return false;
+        }
+        return true;
+    }
+    checkLocalCaFiles() {
+        console.log(chalk_1.default.bold('\n1. CLI CA Files:'));
+        const fs = require('node:fs');
+        const path = require('node:path');
+        const os = require('node:os');
+        const caDir = path.join(os.homedir(), '.flui', 'ca');
+        const caPrivateKeyPath = path.join(caDir, 'ca_key');
+        const caPublicKeyPath = path.join(caDir, 'ca_key.pub');
+        const hasPrivateKey = fs.existsSync(caPrivateKeyPath);
+        const hasPublicKey = fs.existsSync(caPublicKeyPath);
+        console.log(`   Private Key: ${hasPrivateKey ? chalk_1.default.green('✓ Found') : chalk_1.default.red('✗ Missing')} (${caPrivateKeyPath})`);
+        console.log(`   Public Key:  ${hasPublicKey ? chalk_1.default.green('✓ Found') : chalk_1.default.red('✗ Missing')} (${caPublicKeyPath})`);
+        if (hasPublicKey) {
+            const publicKey = fs.readFileSync(caPublicKeyPath, 'utf-8').trim();
+            console.log(chalk_1.default.dim(`   Preview: ${publicKey.substring(0, 50)}...`));
+        }
+    }
+    async checkKubernetesSecret(sshService, masterIp, spinner) {
+        console.log(chalk_1.default.bold('\n2. Kubernetes Secret (flui-secrets):'));
+        spinner.start('Checking Kubernetes secret...');
+        try {
+            const secretCheckCmd = `kubectl get secret flui-secrets -n default -o jsonpath='{.data}' 2>&1`;
+            const secretOutput = await sshService.sshExec(masterIp, secretCheckCmd);
+            const hasPriv = secretOutput.includes('SSH_CA_PRIVATE_KEY');
+            const hasPub = secretOutput.includes('SSH_CA_PUBLIC_KEY');
+            spinner.succeed('Kubernetes secret checked');
+            console.log(`   SSH_CA_PRIVATE_KEY: ${hasPriv ? chalk_1.default.green('✓ Present') : chalk_1.default.red('✗ Missing')}`);
+            console.log(`   SSH_CA_PUBLIC_KEY:  ${hasPub ? chalk_1.default.green('✓ Present') : chalk_1.default.red('✗ Missing')}`);
+            if (!hasPriv || !hasPub) {
+                console.log(chalk_1.default.yellow('\n   ⚠️  CA keys missing from Kubernetes secret!'));
+                console.log(chalk_1.default.dim('   This is required for the API to access SSH.'));
+            }
+        }
+        catch (error) {
+            spinner.fail('Failed to check Kubernetes secret');
+            console.log(chalk_1.default.red(`   Error: ${error.message}`));
+        }
+    }
+    async checkApiPodEnvironment(sshService, masterIp, spinner) {
+        console.log(chalk_1.default.bold('\n3. API Pod Environment Variables:'));
+        spinner.start('Checking API pod...');
+        try {
+            const getPodCmd = `kubectl get pods -n default -l app=flui-api -o jsonpath='{.items[0].metadata.name}' 2>&1`;
+            const podName = (await sshService.sshExec(masterIp, getPodCmd)).trim();
+            if (!podName ||
+                podName.includes('error') ||
+                podName.includes('No resources')) {
+                spinner.warn('API pod not found');
+                console.log(chalk_1.default.yellow('   API pod not found or not running'));
+                return;
+            }
+            const checkEnvCmd = `kubectl exec -n default ${podName} -- env | grep SSH_CA 2>&1 || echo "NOT_FOUND"`;
+            const envOutput = await sshService.sshExec(masterIp, checkEnvCmd);
+            spinner.succeed(`API pod found: ${podName}`);
+            this.reportApiPodEnv(envOutput);
+        }
+        catch (error) {
+            spinner.fail('Failed to check API pod');
+            console.log(chalk_1.default.red(`   Error: ${error.message}`));
+        }
+    }
+    reportApiPodEnv(envOutput) {
+        const hasPriv = envOutput.includes('SSH_CA_PRIVATE_KEY=');
+        const hasPub = envOutput.includes('SSH_CA_PUBLIC_KEY=');
+        console.log(`   SSH_CA_PRIVATE_KEY env: ${hasPriv ? chalk_1.default.green('✓ Set') : chalk_1.default.red('✗ Not Set')}`);
+        console.log(`   SSH_CA_PUBLIC_KEY env:  ${hasPub ? chalk_1.default.green('✓ Set') : chalk_1.default.red('✗ Not Set')}`);
+        if (hasPub) {
+            const pubKeyMatch = /SSH_CA_PUBLIC_KEY=(\S+)/.exec(envOutput);
+            if (pubKeyMatch) {
+                console.log(chalk_1.default.dim(`   Preview: ${pubKeyMatch[1].substring(0, 50)}...`));
+            }
+        }
+        if (!hasPriv || !hasPub) {
+            console.log(chalk_1.default.yellow('\n   ⚠️  CA environment variables not set in API pod!'));
+            console.log(chalk_1.default.dim('   The API pod may need to be restarted to pick up the secret.'));
+            console.log(chalk_1.default.dim('   Restart command: kubectl rollout restart deployment flui-api -n default'));
+        }
+    }
+    async checkApiCaStatusEndpoint(sshService, cluster, spinner) {
+        console.log(chalk_1.default.bold('\n4. API CA Status Endpoint:'));
+        spinner.start('Checking API CA status...');
+        try {
+            const baseDomain = (0, nip_base_domain_util_1.buildNipBaseDomain)(cluster.masterIpAddress, cluster.nipHostnameToken);
+            const apiUrl = `https://api.${baseDomain}/api/v1/access/ca/status`;
+            const apiResponse = await sshService.sshExec(cluster.masterIpAddress, `curl -s -f ${apiUrl} 2>&1`);
+            this.reportApiCaResponse(apiResponse, spinner);
+        }
+        catch (error) {
+            spinner.fail('Failed to check API CA status');
+            console.log(chalk_1.default.red(`   Error: ${error.message}`));
+        }
+    }
+    reportApiCaResponse(apiResponse, spinner) {
+        if (apiResponse.includes('"accessible":true')) {
+            spinner.succeed('API can access CA');
+            console.log(chalk_1.default.green('   ✓ API reports CA is accessible'));
+            try {
+                const j = JSON.parse(apiResponse);
+                console.log(chalk_1.default.dim(`   Source: ${j.source || 'unknown'}`));
+                console.log(chalk_1.default.dim(`   Has Private Key: ${j.hasPrivateKey ? 'Yes' : 'No'}`));
+                console.log(chalk_1.default.dim(`   Has Public Key: ${j.hasPublicKey ? 'Yes' : 'No'}`));
+            }
+            catch {
+                /* */
+            }
+        }
+        else if (apiResponse.includes('404')) {
+            spinner.warn('API CA status endpoint not available');
+            console.log(chalk_1.default.yellow('   ⚠️  The /access/ca/status endpoint is not available'));
+            console.log(chalk_1.default.dim('   This endpoint may not exist in the current API version.'));
+        }
+        else {
+            spinner.fail('API cannot access CA');
+            console.log(chalk_1.default.red('   ✗ API reports CA is not accessible'));
+            console.log(chalk_1.default.dim(`   Response: ${apiResponse.substring(0, 200)}`));
+        }
+    }
+    printSummary() {
+        console.log(chalk_1.default.dim('\n' + '─'.repeat(80)));
+        console.log(chalk_1.default.bold('\n📋 Summary & Recommendations:\n'));
+        console.log(chalk_1.default.dim('If CA keys are missing from the Kubernetes secret:'));
+        console.log(chalk_1.default.cyan('   1. The cluster creation may have failed to patch the secret'));
+        console.log(chalk_1.default.cyan('   2. Re-run cluster creation or manually patch the secret'));
+        console.log(chalk_1.default.dim('\nIf secret has keys but API pod environment does not:'));
+        console.log(chalk_1.default.cyan('   1. Restart the API pod to pick up the secret:'));
+        console.log(chalk_1.default.cyan('      kubectl rollout restart deployment flui-api -n default'));
+        console.log(chalk_1.default.dim('\nIf environment is set but API still cannot access CA:'));
+        console.log(chalk_1.default.cyan('   1. Check API logs for errors:'));
+        console.log(chalk_1.default.cyan('      kubectl logs -n default -l app=flui-api --tail=50'));
+        console.log('');
+    }
+}
+EnvDiagCA.description = 'Diagnose CA configuration on the cluster';
+EnvDiagCA.examples = ['<%= config.bin %> <%= command.id %>'];
+exports.default = EnvDiagCA;

package/lib/cli/src/commands/env/export-config.d.ts

@@ -0,0 +1,39 @@
+import { Command } from '@oclif/core';
+export default class EnvExportConfig extends Command {
+    static readonly description: string;
+    static readonly examples: string[];
+    static readonly flags: {
+        'dry-run': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        backup: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        force: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        'no-dashboard': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        'api-path': import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'dashboard-path': import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'certificate-mode': import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        email: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        save: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+    /**
+     * Resolve every preference this command consumes (email, dashboardPath, certificateMode)
+     * through the layered config: flag > env > project-local > user > default > prompt.
+     *
+     * Prompted values are persisted to the active profile only when --save is set;
+     * otherwise they are used for this run and forgotten (no surprise side effects).
+     *
+     * `skipDashboard` shortcuts the dashboard-only preferences when --no-dashboard is set.
+     */
+    private resolvePreferences;
+    /**
+     * Patch the dashboard's config.json with the localhost API endpoints + cluster auth +
+     * the resolved certificateMode. Caller is responsible for resolving inputs.
+     */
+    private syncDashboardConfig;
+    /**
+     * Prompt for a missing preference value, validating against the schema.
+     * Used only when every other layer (flag, env, project, user, default) failed to provide a value.
+     */
+    private promptForPreference;
+    private resolveIssuer;
+    private resolveJwks;
+}

package/lib/cli/src/commands/env/export-config.js

@@ -0,0 +1,386 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const chalk_1 = __importDefault(require("chalk"));
+const ora_1 = __importDefault(require("ora"));
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const nest_app_1 = require("../../lib/nest-app");
+const cli_observability_cluster_service_1 = require("../../services/cli-observability-cluster.service");
+const cli_endpoint_resolver_service_1 = require("../../services/cli-endpoint-resolver.service");
+const config_storage_1 = require("../../lib/config-storage");
+const cluster_entity_1 = require("../../../../src/modules/infrastructure/clusters/entities/cluster.entity");
+const env_file_1 = require("../../lib/utils/env-file");
+const preferences_resolver_1 = require("../../config/preferences-resolver");
+const preferences_echo_1 = require("../../config/preferences-echo");
+const prompts_1 = require("../../lib/prompts");
+const preferences_schema_1 = require("../../config/preferences-schema");
+const context_banner_1 = require("../../lib/context-banner");
+class EnvExportConfig extends core_1.Command {
+    async run() {
+        const { flags } = await this.parse(EnvExportConfig);
+        (0, context_banner_1.printContextBanner)();
+        let spinner = (0, ora_1.default)('Reading cluster configuration...').start();
+        try {
+            const app = await (0, nest_app_1.getNestApp)();
+            const observabilityService = app.get(cli_observability_cluster_service_1.CliObservabilityClusterService);
+            const resolver = app.get(cli_endpoint_resolver_service_1.CliEndpointResolverService);
+            const cluster = await observabilityService.getObservabilityCluster();
+            if (!cluster) {
+                spinner.fail('No observability cluster found');
+                console.log(chalk_1.default.yellow('\n⚠️  No observability cluster exists.\n'));
+                console.log(chalk_1.default.dim('Create one with:'));
+                console.log(`   ${chalk_1.default.cyan('flui env create')}\n`);
+                return;
+            }
+            if (cluster.status !== cluster_entity_1.ClusterStatus.READY) {
+                spinner.fail(`Cluster is not ready (status: ${cluster.status})`);
+                console.log(chalk_1.default.yellow('\n⚠️  Cluster must be in READY status to export configuration.\n'));
+                return;
+            }
+            const masterIp = cluster.masterIpAddress;
+            if (!masterIp) {
+                spinner.fail('Master IP address not available');
+                return;
+            }
+            spinner.succeed('Cluster configuration loaded');
+            spinner = (0, ora_1.default)('Resolving endpoints from cluster...').start();
+            const endpoints = await resolver.resolveEndpoints(masterIp, cluster.nipHostnameToken);
+            spinner.succeed('Endpoints resolved');
+            // ADMIN_EMAIL and SSH_CA_PUBLIC_KEY live in flui-secrets but reading
+            // them here would require kube-API access (closed by the new firewall
+            // policy). They are written to .env.local by `flui dev creds`, which
+            // reaches the secret over SSH+kubectl. Here we fall back to the
+            // 'email' preference and skip the public CA key.
+            const adminEmail = '';
+            const sshCaPublicKey = '';
+            const authMode = endpoints.authMode === 'unknown' ? 'local' : endpoints.authMode;
+            const resolvedIssuer = this.resolveIssuer(endpoints);
+            const resolvedJwks = this.resolveJwks(endpoints, resolvedIssuer);
+            // Display configuration
+            console.log(chalk_1.default.cyan('\n📋 Exporting Cluster Configuration\n'));
+            console.log(`   ${chalk_1.default.bold('Cluster:')}    ${cluster.name}`);
+            console.log(`   ${chalk_1.default.bold('Master IP:')}  ${masterIp}`);
+            console.log(`   ${chalk_1.default.bold('Status:')}     ${cluster.status}\n`);
+            console.log(chalk_1.default.cyan('⚙️  Configuration to export (endpoints only):\n'));
+            console.log(`   DB_HOST=127.0.0.1   ${chalk_1.default.dim('# via `flui dev tunnel`')}`);
+            console.log(`   DB_PORT=5432`);
+            console.log(`   DB_USERNAME=fluicloud`);
+            console.log(`   DB_NAME=fluicloud`);
+            console.log(`   REDIS_HOST=127.0.0.1`);
+            console.log(`   REDIS_PORT=6379`);
+            console.log(`   KUBECONFIG_SERVER_OVERRIDE=https://127.0.0.1:6443`);
+            console.log(`   GRAFANA_URL=http://localhost:3001        ${chalk_1.default.dim('# via `flui dev tunnel --ports grafana`')}`);
+            console.log(`   PROMETHEUS_ENDPOINT=http://localhost:9090 ${chalk_1.default.dim('# via `flui dev tunnel --ports vmsingle`')}`);
+            console.log(`   LOKI_ENDPOINT=http://localhost:3100       ${chalk_1.default.dim('# via `flui dev tunnel --ports loki`')}`);
+            if (resolvedIssuer || authMode === 'oidc') {
+                console.log(`   OIDC_ISSUER=${resolvedIssuer || chalk_1.default.dim('(not set)')}`);
+                console.log(`   OIDC_JWKS_URI=${resolvedJwks || chalk_1.default.dim('(not set)')}`);
+                console.log(`   OIDC_AUDIENCE=${endpoints.oidcAudience || chalk_1.default.dim('(set after first Zitadel setup)')}`);
+            }
+            console.log(`   AUTH_MODE=${authMode}`);
+            console.log(`   ADMIN_EMAIL=${adminEmail || chalk_1.default.dim('(not set)')}`);
+            console.log(`   SSH_CA_PUBLIC_KEY=${sshCaPublicKey ? chalk_1.default.green('(present)') : chalk_1.default.dim('(not set)')}`);
+            console.log(chalk_1.default.dim('\n   Secrets (DB/Redis/JWT/SSH CA private/encryption key) are NOT written here.\n' +
+                '   Run `flui dev creds` to populate them in .env.local.\n'));
+            if (flags['dry-run']) {
+                console.log(chalk_1.default.yellow('🔍 Dry run mode - no changes will be made\n'));
+                return;
+            }
+            if (!flags.force) {
+                console.log(chalk_1.default.yellow('⚠️  This will update your .env file.\n'));
+                console.log(chalk_1.default.dim('Use --force to skip this check in automated scripts.\n'));
+            }
+            // Resolve user preferences once and surface them before any write happens.
+            const preferences = await this.resolvePreferences({
+                emailFlag: flags.email,
+                apiPathFlag: flags['api-path'],
+                dashboardPathFlag: flags['dashboard-path'],
+                certificateModeFlag: flags['certificate-mode'],
+                save: flags.save,
+                // Skip the dashboardPath/certificateMode prompts entirely when the user opted out.
+                skipDashboard: flags['no-dashboard'],
+            });
+            spinner = (0, ora_1.default)('Updating .env file...').start();
+            // .env lives next to the resolved apiPath. Defaults to '.' (cwd) so legacy
+            // invocations from inside flui.api keep working without any preference set.
+            const apiDir = path.isAbsolute(preferences.apiPath)
+                ? preferences.apiPath
+                : path.resolve(process.cwd(), preferences.apiPath);
+            const envPath = path.join(apiDir, '.env');
+            const envExamplePath = path.join(apiDir, '.env.example');
+            let envContent = '';
+            if (fs.existsSync(envPath)) {
+                envContent = fs.readFileSync(envPath, 'utf-8');
+            }
+            else if (fs.existsSync(envExamplePath)) {
+                envContent = fs.readFileSync(envExamplePath, 'utf-8');
+                spinner.info('.env not found, using .env.example as template');
+            }
+            else {
+                spinner.warn('No .env or .env.example found, creating new .env');
+            }
+            if (flags.backup && fs.existsSync(envPath)) {
+                const timestamp = new Date()
+                    .toISOString()
+                    .replaceAll(':', '-')
+                    .replace(/\..+/, '');
+                const backupPath = `${envPath}.backup.${timestamp}`;
+                fs.copyFileSync(envPath, backupPath);
+                spinner.succeed(`Backup created: ${path.basename(backupPath)}`);
+            }
+            const envVars = {
+                KUBECONFIG_SERVER_OVERRIDE: 'https://127.0.0.1:6443',
+                DB_HOST: '127.0.0.1',
+                DB_PORT: '5432',
+                DB_USERNAME: 'fluicloud',
+                DB_NAME: 'fluicloud',
+                REDIS_HOST: '127.0.0.1',
+                REDIS_PORT: '6379',
+                GRAFANA_URL: 'http://localhost:3001',
+                PROMETHEUS_ENDPOINT: 'http://localhost:9090',
+                LOKI_ENDPOINT: 'http://localhost:3100',
+                AUTH_MODE: authMode,
+            };
+            if (resolvedIssuer)
+                envVars.OIDC_ISSUER = resolvedIssuer;
+            if (resolvedJwks)
+                envVars.OIDC_JWKS_URI = resolvedJwks;
+            if (endpoints.oidcAudience)
+                envVars.OIDC_AUDIENCE = endpoints.oidcAudience;
+            // ADMIN_EMAIL: prefer the value baked into the cluster's flui-secrets, fall back to
+            // the resolved 'email' preference. Either way the API gets a populated value.
+            const resolvedEmail = adminEmail || preferences.email;
+            if (resolvedEmail)
+                envVars.ADMIN_EMAIL = resolvedEmail;
+            if (sshCaPublicKey)
+                envVars.SSH_CA_PUBLIC_KEY = sshCaPublicKey;
+            const updatedEnv = (0, env_file_1.updateEnvContent)(envContent, envVars);
+            fs.writeFileSync(envPath, updatedEnv, 'utf-8');
+            spinner.succeed('.env file updated successfully');
+            if (!flags['no-dashboard']) {
+                await this.syncDashboardConfig({
+                    dashboardPath: preferences.dashboardPath,
+                    certificateMode: preferences.certificateMode,
+                    authMode,
+                    oidcIssuer: resolvedIssuer,
+                    oidcClientId: endpoints.oidcClientId,
+                    oidcAudience: endpoints.oidcAudience,
+                    backup: flags.backup,
+                });
+            }
+            console.log(chalk_1.default.green('\n✅ Endpoint configuration exported.\n'));
+            console.log(chalk_1.default.dim('Next steps to run the API locally:'));
+            console.log(`   1. ${chalk_1.default.cyan('flui dev creds')}    ${chalk_1.default.dim('# write secrets to .env.local')}`);
+            console.log(`   2. ${chalk_1.default.cyan('flui dev tunnel')}   ${chalk_1.default.dim('# expose cluster services on localhost')}`);
+            console.log(`   3. ${chalk_1.default.cyan('pnpm run start:dev')}\n`);
+        }
+        catch (error) {
+            spinner.fail('Error exporting configuration');
+            console.error(chalk_1.default.red(`\n❌ ${error.message}\n`));
+            this.exit(1);
+        }
+        finally {
+            await (0, nest_app_1.closeNestApp)();
+        }
+    }
+    /**
+     * Resolve every preference this command consumes (email, dashboardPath, certificateMode)
+     * through the layered config: flag > env > project-local > user > default > prompt.
+     *
+     * Prompted values are persisted to the active profile only when --save is set;
+     * otherwise they are used for this run and forgotten (no surprise side effects).
+     *
+     * `skipDashboard` shortcuts the dashboard-only preferences when --no-dashboard is set.
+     */
+    async resolvePreferences(opts) {
+        const storage = new config_storage_1.ConfigStorage();
+        const resolver = new preferences_resolver_1.PreferencesResolver(storage);
+        const echoEntries = [];
+        const out = {};
+        const resolveOne = async (key, explicit) => {
+            const initial = resolver.resolve(key, explicit);
+            if (initial.value !== null) {
+                echoEntries.push(initial);
+                return initial.value;
+            }
+            const prompted = await this.promptForPreference(key);
+            if (opts.save) {
+                storage.setPreference(key, prompted);
+            }
+            echoEntries.push({
+                key,
+                value: prompted,
+                source: opts.save ? 'user' : 'explicit',
+            });
+            return prompted;
+        };
+        out.email = await resolveOne('email', opts.emailFlag);
+        out.apiPath = await resolveOne('apiPath', opts.apiPathFlag);
+        if (!opts.skipDashboard) {
+            out.dashboardPath = await resolveOne('dashboardPath', opts.dashboardPathFlag);
+            out.certificateMode = await resolveOne('certificateMode', opts.certificateModeFlag);
+        }
+        (0, preferences_echo_1.echoPreferences)(echoEntries, resolver);
+        if (!opts.save &&
+            echoEntries.some((e) => e.source === 'explicit' || e.source === 'default')) {
+            console.log(chalk_1.default.dim('  ↳ Pass --save to persist prompted/default values to ~/.flui/profiles/<active>/config.json\n'));
+        }
+        return out;
+    }
+    /**
+     * Patch the dashboard's config.json with the localhost API endpoints + cluster auth +
+     * the resolved certificateMode. Caller is responsible for resolving inputs.
+     */
+    async syncDashboardConfig(opts) {
+        const dashboardPath = opts.dashboardPath;
+        const certificateMode = opts.certificateMode;
+        const absoluteDashboardPath = path.isAbsolute(dashboardPath)
+            ? dashboardPath
+            : path.resolve(process.cwd(), dashboardPath);
+        const configPath = path.join(absoluteDashboardPath, 'src', 'assets', 'config.json');
+        const spinner = (0, ora_1.default)(`Updating dashboard config (${configPath})...`).start();
+        if (!fs.existsSync(configPath)) {
+            spinner.warn(`Dashboard config not found at ${configPath} — skipping. Adjust dashboardPath or pass --no-dashboard.`);
+            return;
+        }
+        let current = {};
+        try {
+            current = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        }
+        catch (err) {
+            spinner.fail(`Dashboard config.json is not valid JSON (${err.message}) — skipping`);
+            return;
+        }
+        if (opts.backup) {
+            const timestamp = new Date()
+                .toISOString()
+                .replaceAll(':', '-')
+                .replace(/\..+/, '');
+            fs.copyFileSync(configPath, `${configPath}.backup.${timestamp}`);
+        }
+        const updated = {
+            ...current,
+            apiBaseUrl: 'http://localhost:3000',
+            wsUrl: 'ws://localhost:3000',
+            authMode: opts.authMode,
+            oidcIssuer: opts.oidcIssuer || current.oidcIssuer || '',
+            oidcClientId: opts.oidcClientId || current.oidcClientId || '',
+            oidcAudience: opts.oidcAudience || current.oidcAudience || '',
+            certificateMode,
+        };
+        fs.writeFileSync(configPath, JSON.stringify(updated, null, 2) + '\n', 'utf-8');
+        spinner.succeed(`Dashboard config updated (authMode=${opts.authMode}, certificateMode=${certificateMode}, oidcClientId=${opts.oidcClientId ? 'set' : '(empty)'})`);
+    }
+    /**
+     * Prompt for a missing preference value, validating against the schema.
+     * Used only when every other layer (flag, env, project, user, default) failed to provide a value.
+     */
+    async promptForPreference(key) {
+        const def = preferences_schema_1.PREFERENCES[key];
+        return (0, prompts_1.promptInput)({
+            message: def.description,
+            default: def.defaultValue,
+            validate: (v) => preferences_resolver_1.PreferencesResolver.validate(key, v),
+        });
+    }
+    resolveIssuer(endpoints) {
+        if (endpoints.zitadel.fqdn)
+            return `https://${endpoints.zitadel.fqdn}`;
+        if (endpoints.oidcIssuer)
+            return endpoints.oidcIssuer;
+        return '';
+    }
+    resolveJwks(endpoints, issuer) {
+        const raw = endpoints.oidcJwksUri;
+        const isInCluster = raw.includes('.svc.cluster.local');
+        if (raw && !isInCluster)
+            return raw;
+        if (issuer)
+            return `${issuer.replace(/\/$/, '')}/oauth/v2/keys`;
+        return '';
+    }
+}
+EnvExportConfig.description = 'Export cluster endpoints (and non-sensitive defaults) to .env for running the API locally.\n' +
+    'Secrets are NOT written by this command — run `flui dev creds` for those, and `flui dev tunnel`\n' +
+    'to expose Postgres/Redis/etc. on localhost.';
+EnvExportConfig.examples = [
+    '<%= config.bin %> <%= command.id %>',
+    '<%= config.bin %> <%= command.id %> --dry-run',
+    '<%= config.bin %> <%= command.id %> --no-backup',
+];
+EnvExportConfig.flags = {
+    'dry-run': core_1.Flags.boolean({
+        description: 'Show what would be changed without modifying .env',
+        default: false,
+    }),
+    backup: core_1.Flags.boolean({
+        description: 'Create backup of existing .env file',
+        default: true,
+        allowNo: true,
+    }),
+    force: core_1.Flags.boolean({
+        description: 'Skip confirmation prompt',
+        default: false,
+    }),
+    'no-dashboard': core_1.Flags.boolean({
+        description: 'Skip updating the dashboard config.json',
+        default: false,
+    }),
+    // Direct overrides for the layered preferences resolver.
+    // Without these, values resolve from env > project file > user config > prompt.
+    'api-path': core_1.Flags.string({
+        description: `Override resolved value for the "apiPath" preference (${preferences_schema_1.PREFERENCES.apiPath.description})`,
+    }),
+    'dashboard-path': core_1.Flags.string({
+        description: `Override resolved value for the "dashboardPath" preference (${preferences_schema_1.PREFERENCES.dashboardPath.description})`,
+    }),
+    'certificate-mode': core_1.Flags.string({
+        description: `Override resolved value for the "certificateMode" preference (one of: ${preferences_schema_1.PREFERENCES.certificateMode.allowedValues.join(', ')})`,
+        options: [...preferences_schema_1.PREFERENCES.certificateMode.allowedValues],
+    }),
+    email: core_1.Flags.string({
+        description: `Override resolved value for the "email" preference (${preferences_schema_1.PREFERENCES.email.description})`,
+    }),
+    save: core_1.Flags.boolean({
+        description: 'Persist any value entered at the interactive prompt to the active profile (~/.flui/profiles/<active>/config.json). Without this flag, prompted values are used only for this run.',
+        default: false,
+    }),
+};
+exports.default = EnvExportConfig;

package/lib/cli/src/commands/env/force-ready.d.ts

@@ -0,0 +1,10 @@
+import { Command } from '@oclif/core';
+export default class EnvForceReady extends Command {
+    static readonly description = "Force observability cluster status to READY (use when cluster is working but stuck in ERROR or CREATING state)";
+    static readonly examples: string[];
+    static readonly flags: {
+        force: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        'skip-health-checks': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}