@nocobase/cli 2.1.0-beta.9 → 2.1.0-rc.2

package/dist/commands/app/upgrade.js

@@ -0,0 +1,523 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+import { Command, Flags } from '@oclif/core';
+import { getCurrentEnvName, upsertEnv } from '../../lib/auth-store.js';
+import { formatMissingManagedAppEnvMessage, resolveManagedAppRuntime, } from '../../lib/app-runtime.js';
+import { ensureCrossEnvConfirmed, hasExplicitEnvSelection } from '../../lib/env-guard.js';
+import { DEFAULT_DOCKER_REGISTRY } from "../../lib/docker-image.js";
+import { confirm } from "../../lib/inquirer.js";
+import { announceTargetEnv, isInteractiveTerminal, printInfo, printWarning, succeedTask } from '../../lib/ui.js';
+import { resolveAppUrlFromApiBaseUrl } from '../env/shared.js';
+function trimValue(value) {
+    return String(value ?? '').trim();
+}
+function normalizeEnvName(value) {
+    const text = trimValue(value);
+    return text || undefined;
+}
+function formatAppUrl(port) {
+    const value = trimValue(port);
+    return value ? `http://127.0.0.1:${value}` : undefined;
+}
+function formatDisplayUrl(apiBaseUrl, appPort) {
+    const resolvedFromApiBaseUrl = resolveAppUrlFromApiBaseUrl(apiBaseUrl);
+    if (resolvedFromApiBaseUrl) {
+        return resolvedFromApiBaseUrl;
+    }
+    const appUrl = formatAppUrl(appPort);
+    if (appUrl) {
+        return appUrl;
+    }
+    const value = trimValue(apiBaseUrl);
+    return value ? value.replace(/\/api\/?$/, '') : undefined;
+}
+function readEnvValue(env, key) {
+    return trimValue(env.config[key]);
+}
+function normalizeDockerPlatform(value) {
+    const text = trimValue(value);
+    if (!text || text === 'auto') {
+        return undefined;
+    }
+    if (text === 'linux/amd64' || text === 'linux/arm64') {
+        return text;
+    }
+    return undefined;
+}
+function isDownloadableLocalRuntime(runtime) {
+    return runtime.kind === 'local' && (runtime.source === 'npm' || runtime.source === 'git');
+}
+function formatLocalDownloadFailure(envName, source, message) {
+    const sourceLabel = source === 'git' ? 'the saved Git checkout' : 'the saved npm app';
+    return [
+        `Couldn't refresh NocoBase for "${envName}".`,
+        `The CLI was not able to update ${sourceLabel} before restarting it.`,
+        'Check the saved source settings for this env, then try again.',
+        `Details: ${message}`,
+    ].join('\n');
+}
+function formatDockerDownloadFailure(envName, message) {
+    return [
+        `Couldn't refresh the Docker image for "${envName}".`,
+        'The CLI was not able to pull the latest image for this env.',
+        'Check the saved Docker source settings and your Docker network access, then try again.',
+        `Details: ${message}`,
+    ].join('\n');
+}
+function buildManagedActionArgv(envName, flags, options) {
+    const argv = ['--env', envName, '--yes'];
+    if (flags.verbose) {
+        argv.push('--verbose');
+    }
+    if (options?.quickstart) {
+        argv.push('--quickstart');
+    }
+    return argv;
+}
+function shouldSkipDownload(flags) {
+    return Boolean(flags['skip-download'] || flags['skip-code-update']);
+}
+function buildUpgradeCliArgv(envName, flags, options) {
+    const argv = ['--env', envName];
+    if (shouldSkipDownload(flags)) {
+        argv.push('--skip-download');
+    }
+    const version = normalizeEnvName(flags.version);
+    if (version) {
+        argv.push('--version', version);
+    }
+    if (flags.verbose) {
+        argv.push('--verbose');
+    }
+    if (options?.yes ?? flags.yes) {
+        argv.push('--yes');
+    }
+    if (options?.force ?? flags.force) {
+        argv.push('--force');
+    }
+    return argv;
+}
+function buildUpgradeCliCommand(envName, flags, options) {
+    return ['nb', 'app', 'upgrade', ...buildUpgradeCliArgv(envName, flags, options)].join(' ');
+}
+function formatUpgradeOperationSummary(runtime, flags) {
+    const mayRunUpgradeMigrations = 'It may also run upgrade migrations.';
+    if (shouldSkipDownload(flags)) {
+        const sourceLabel = runtime.kind === 'docker'
+            ? 'saved Docker image'
+            : runtime.source === 'local'
+                ? 'saved local app path'
+                : runtime.source === 'git'
+                    ? 'saved Git checkout'
+                    : 'saved npm app';
+        return [
+            'This operation will stop the app, skip source download and commercial plugin sync,',
+            `and start it again with the ${sourceLabel}.`,
+            mayRunUpgradeMigrations,
+        ].join(' ');
+    }
+    if (runtime.kind === 'docker') {
+        return [
+            'This operation will stop the app, replace the saved Docker image,',
+            'sync commercial plugins when applicable, and start the app again.',
+            mayRunUpgradeMigrations,
+        ].join(' ');
+    }
+    if (runtime.source === 'local') {
+        return [
+            'This operation will stop the app, reuse the saved local app path,',
+            'sync commercial plugins when applicable, and start the app again.',
+            mayRunUpgradeMigrations,
+        ].join(' ');
+    }
+    return [
+        'This operation will stop the app, replace the saved source,',
+        'sync commercial plugins when applicable, and start the app again.',
+        mayRunUpgradeMigrations,
+    ].join(' ');
+}
+function formatUpgradePromptSummary(flags) {
+    if (shouldSkipDownload(flags)) {
+        return 'This will stop and restart the app, and may run upgrade migrations.';
+    }
+    return 'This will stop and restart the app, update the saved source or image, and may run upgrade migrations.';
+}
+function formatUpgradeForceRequiredMessage(runtime, flags) {
+    return [
+        `\`nb app upgrade\` needs confirmation in non-interactive mode before upgrading "${runtime.envName}".`,
+        '',
+        formatUpgradeOperationSummary(runtime, flags),
+        '',
+        'Interactive confirmation is unavailable in the current AI agent session, and the agent will not add `--force` on your behalf.',
+        '',
+        'To continue:',
+        `- re-run \`${buildUpgradeCliCommand(runtime.envName, flags, { force: true })}\``,
+        `- or switch to an interactive terminal and re-run \`${buildUpgradeCliCommand(runtime.envName, flags, {
+            force: false,
+        })}\``,
+    ].join('\n');
+}
+function formatMissingUpgradeFlagList(options) {
+    const missingFlags = [
+        options.missingYes ? '`--yes`' : undefined,
+        options.missingForce ? '`--force`' : undefined,
+    ].filter(Boolean);
+    if (missingFlags.length <= 1) {
+        return missingFlags[0] ?? '';
+    }
+    return `${missingFlags[0]} or ${missingFlags[1]}`;
+}
+function formatUpgradeCrossEnvConfirmationRequiredMessage(currentEnv, runtime, flags, options) {
+    return [
+        `Refusing to upgrade env "${runtime.envName}" because the current env is "${currentEnv}" and interactive confirmation is unavailable in the current AI agent session.`,
+        '',
+        formatUpgradeOperationSummary(runtime, flags),
+        '',
+        `For safety, the agent will not switch envs automatically and will not add ${formatMissingUpgradeFlagList(options)} on your behalf.`,
+        '',
+        'To continue:',
+        `- run \`nb env use ${runtime.envName}\` yourself, then re-run \`${buildUpgradeCliCommand(runtime.envName, flags, {
+            yes: false,
+            force: true,
+        })}\``,
+        `- or re-run \`${buildUpgradeCliCommand(runtime.envName, flags, { yes: true, force: true })}\``,
+    ].join('\n');
+}
+function buildLicenseSyncArgv(envName, flags, options) {
+    const argv = ['--env', envName, '--yes', '--skip-if-no-license'];
+    if (flags.verbose) {
+        argv.push('--verbose');
+    }
+    if (options?.version) {
+        argv.push('--version', options.version);
+    }
+    return argv;
+}
+function buildEnvUpdateArgv(envName, flags) {
+    const argv = [envName];
+    if (flags.verbose) {
+        argv.push('--verbose');
+    }
+    return argv;
+}
+function formatEnvUpdateWarning(envName, message) {
+    return [
+        `NocoBase was upgraded for "${envName}", but the CLI could not refresh the saved env runtime.`,
+        `Run \`nb env update ${envName}\` to refresh it manually.`,
+        `Details: ${message}`,
+    ].join(' ');
+}
+async function runWithSuppressedTargetEnvLog(task) {
+    const previousTargetEnv = process.env.NB_SKIP_TARGET_ENV_LOG;
+    process.env.NB_SKIP_TARGET_ENV_LOG = '1';
+    try {
+        return await task();
+    }
+    finally {
+        if (previousTargetEnv === undefined) {
+            delete process.env.NB_SKIP_TARGET_ENV_LOG;
+        }
+        else {
+            process.env.NB_SKIP_TARGET_ENV_LOG = previousTargetEnv;
+        }
+    }
+}
+async function runWithSuppressedStartSuccessLog(task) {
+    const previousStartSuccess = process.env.NB_SKIP_APP_START_SUCCESS_LOG;
+    process.env.NB_SKIP_APP_START_SUCCESS_LOG = '1';
+    try {
+        return await task();
+    }
+    finally {
+        if (previousStartSuccess === undefined) {
+            delete process.env.NB_SKIP_APP_START_SUCCESS_LOG;
+        }
+        else {
+            process.env.NB_SKIP_APP_START_SUCCESS_LOG = previousStartSuccess;
+        }
+    }
+}
+export default class AppUpgrade extends Command {
+    static hidden = false;
+    static description = 'Upgrade the selected NocoBase app. The CLI stops the current app, optionally replaces the saved source or image, then starts the app again. Use --version to upgrade to a specific saved source version or image tag.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %>',
+        '<%= config.bin %> <%= command.id %> --force',
+        '<%= config.bin %> <%= command.id %> --env local',
+        '<%= config.bin %> <%= command.id %> --env local --force',
+        '<%= config.bin %> <%= command.id %> --env local -s',
+        '<%= config.bin %> <%= command.id %> --env local --version beta',
+        '<%= config.bin %> <%= command.id %> --env local --verbose',
+        '<%= config.bin %> <%= command.id %> --env local-docker -s',
+    ];
+    static flags = {
+        env: Flags.string({
+            char: 'e',
+            description: 'CLI env name to upgrade. Defaults to the current env when omitted',
+        }),
+        yes: Flags.boolean({
+            char: 'y',
+            description: 'Confirm using --env when it targets a different env than the current env',
+            default: false,
+        }),
+        force: Flags.boolean({
+            char: 'f',
+            description: 'Skip the upgrade confirmation prompt',
+            default: false,
+        }),
+        'skip-download': Flags.boolean({
+            char: 's',
+            description: 'Restart with the saved local source or Docker image without downloading updates first',
+            required: false,
+        }),
+        'skip-code-update': Flags.boolean({
+            hidden: true,
+            deprecated: true,
+            description: 'Deprecated alias for --skip-download',
+            required: false,
+        }),
+        version: Flags.string({
+            description: 'Override the saved downloadVersion for this upgrade. When the upgrade succeeds, the new version is saved back to the env config.',
+            required: false,
+        }),
+        verbose: Flags.boolean({
+            description: 'Show raw output from the underlying local or Docker commands',
+            default: true,
+        }),
+    };
+    static resolveUpgradeVersion(runtime, flags) {
+        const requestedVersion = trimValue(flags.version);
+        if (runtime.kind === 'local' && runtime.source === 'local') {
+            if (requestedVersion) {
+                throw new Error([
+                    `Env "${runtime.envName}" is managed from an existing local app path.`,
+                    'This source does not support `nb app upgrade --version` because the CLI does not manage that code checkout.',
+                    'Update the local app path yourself, then run `nb app upgrade` to restart it.',
+                ].join('\n'));
+            }
+            return {};
+        }
+        if (shouldSkipDownload(flags)) {
+            return {
+                persistDownloadVersion: requestedVersion || undefined,
+            };
+        }
+        const savedVersion = readEnvValue(runtime.env, 'downloadVersion');
+        const downloadVersion = requestedVersion || savedVersion;
+        if (!downloadVersion) {
+            throw new Error([
+                `Env "${runtime.envName}" does not have a saved \`downloadVersion\`.`,
+                'This env cannot be upgraded until a source version is explicit.',
+                `Re-run \`nb init --ui --env ${runtime.envName}\` for this env, or pass \`--version\` to \`nb app upgrade\`.`,
+            ].join('\n'));
+        }
+        return {
+            downloadVersion,
+            persistDownloadVersion: requestedVersion || undefined,
+        };
+    }
+    static buildLocalDownloadArgv(runtime, downloadVersion, options) {
+        const argv = ['-y', '--no-intro', '--source', runtime.source, '--replace'];
+        if (options?.verbose) {
+            argv.push('--verbose');
+        }
+        argv.push('--version', downloadVersion, '--output-dir', runtime.projectRoot);
+        const gitUrl = readEnvValue(runtime.env, 'gitUrl');
+        if (gitUrl) {
+            argv.push('--git-url', gitUrl);
+        }
+        const npmRegistry = readEnvValue(runtime.env, 'npmRegistry');
+        if (npmRegistry) {
+            argv.push('--npm-registry', npmRegistry);
+        }
+        if (runtime.env.config.devDependencies === true) {
+            argv.push('--dev-dependencies');
+        }
+        if (runtime.env.config.build === false) {
+            argv.push('--no-build');
+        }
+        if (runtime.env.config.buildDts === true) {
+            argv.push('--build-dts');
+        }
+        return argv;
+    }
+    static buildDockerDownloadArgv(runtime, downloadVersion, options) {
+        const argv = ['-y', '--no-intro'];
+        if (options?.verbose) {
+            argv.push('--verbose');
+        }
+        argv.push('--source', 'docker', '--replace', '--docker-registry', readEnvValue(runtime.env, 'dockerRegistry') || DEFAULT_DOCKER_REGISTRY, '--version', downloadVersion);
+        const dockerPlatform = normalizeDockerPlatform(runtime.env.config.dockerPlatform);
+        if (dockerPlatform) {
+            argv.push('--docker-platform', dockerPlatform);
+        }
+        return argv;
+    }
+    static async persistDownloadVersion(runtime, downloadVersion) {
+        const { name: _name, ...envConfig } = runtime.env.config;
+        try {
+            await upsertEnv(runtime.envName, {
+                ...envConfig,
+                downloadVersion,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`NocoBase was upgraded for "${runtime.envName}", but the CLI could not save \`downloadVersion=${downloadVersion}\`. Details: ${message}`);
+        }
+    }
+    async run() {
+        const { flags } = await this.parse(AppUpgrade);
+        const parsed = flags;
+        const requestedEnv = normalizeEnvName(parsed.env);
+        const explicitEnvSelection = Boolean(requestedEnv && hasExplicitEnvSelection(this.argv));
+        const runtime = await resolveManagedAppRuntime(requestedEnv);
+        if (!runtime) {
+            this.error(formatMissingManagedAppEnvMessage(requestedEnv));
+        }
+        if (runtime.kind === 'http') {
+            this.error([
+                `Can't upgrade "${runtime.envName}" from this machine.`,
+                'This env only has an API connection, so there is no saved local app or Docker runtime to upgrade here.',
+                'If you want a local NocoBase AI environment that the CLI can upgrade, run `nb init --ui` first.',
+            ].join('\n'));
+        }
+        if (runtime.kind === 'ssh') {
+            this.error([
+                `Can't upgrade "${runtime.envName}" yet.`,
+                'SSH env support is reserved but not implemented yet.',
+                'Use a local or Docker env if you need CLI-managed upgrades right now.',
+            ].join('\n'));
+        }
+        const interactiveTerminal = isInteractiveTerminal();
+        if (explicitEnvSelection) {
+            if (!interactiveTerminal) {
+                const currentEnv = normalizeEnvName(await getCurrentEnvName());
+                if (currentEnv && currentEnv !== requestedEnv) {
+                    const missingYes = !parsed.yes;
+                    const missingForce = !parsed.force;
+                    if (missingYes || missingForce) {
+                        this.error(formatUpgradeCrossEnvConfirmationRequiredMessage(currentEnv, runtime, parsed, {
+                            missingYes,
+                            missingForce,
+                        }));
+                    }
+                }
+            }
+            else {
+                const confirmed = await ensureCrossEnvConfirmed({
+                    command: this,
+                    requestedEnv,
+                    yes: parsed.yes,
+                });
+                if (!confirmed) {
+                    return;
+                }
+            }
+        }
+        if (!interactiveTerminal) {
+            if (!parsed.force) {
+                this.error(formatUpgradeForceRequiredMessage(runtime, parsed));
+            }
+        }
+        else if (!parsed.force) {
+            let confirmed = false;
+            try {
+                confirmed = await confirm({
+                    message: `Upgrade "${runtime.envName}"? ${formatUpgradePromptSummary(parsed)}`,
+                    default: false,
+                });
+            }
+            catch {
+                return;
+            }
+            if (!confirmed) {
+                return;
+            }
+        }
+        announceTargetEnv(runtime.envName);
+        try {
+            const resolvedVersion = AppUpgrade.resolveUpgradeVersion(runtime, parsed);
+            const skipDownload = shouldSkipDownload(parsed);
+            const runCommand = this.config.runCommand.bind(this.config);
+            await runWithSuppressedTargetEnvLog(async () => {
+                await runCommand('app:stop', buildManagedActionArgv(runtime.envName, parsed));
+            });
+            if (skipDownload) {
+                printInfo(`Skipping source download for "${runtime.envName}" (--skip-download).`);
+                printInfo(`Skipping commercial plugin sync for "${runtime.envName}" (--skip-download).`);
+            }
+            else if (runtime.kind === 'local' && runtime.source === 'local') {
+                printInfo(`Skipping source download for "${runtime.envName}" because this env is managed from an existing local app path.`);
+            }
+            else {
+                const downloadVersion = resolvedVersion.downloadVersion;
+                if (!downloadVersion) {
+                    throw new Error(`Missing downloadVersion for "${runtime.envName}".`);
+                }
+                try {
+                    if (runtime.kind === 'docker') {
+                        await runCommand('source:download', AppUpgrade.buildDockerDownloadArgv(runtime, downloadVersion, {
+                            verbose: parsed.verbose,
+                        }));
+                    }
+                    else if (isDownloadableLocalRuntime(runtime)) {
+                        await runCommand('source:download', AppUpgrade.buildLocalDownloadArgv(runtime, downloadVersion, {
+                            verbose: parsed.verbose,
+                        }));
+                    }
+                    else {
+                        throw new Error(`Skipping source download for "${runtime.envName}" because this env is managed from an existing local app path.`);
+                    }
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    if (runtime.kind === 'docker') {
+                        throw new Error(formatDockerDownloadFailure(runtime.envName, message));
+                    }
+                    if (isDownloadableLocalRuntime(runtime)) {
+                        throw new Error(formatLocalDownloadFailure(runtime.envName, runtime.source, message));
+                    }
+                    throw new Error(message);
+                }
+            }
+            if (!skipDownload) {
+                await runWithSuppressedTargetEnvLog(async () => {
+                    await runCommand('license:plugins:sync', buildLicenseSyncArgv(runtime.envName, parsed, {
+                        version: resolvedVersion.persistDownloadVersion,
+                    }));
+                });
+            }
+            await runWithSuppressedTargetEnvLog(async () => {
+                const startArgv = buildManagedActionArgv(runtime.envName, parsed, { quickstart: true });
+                startArgv.push('--no-sync-licensed-plugins');
+                await runWithSuppressedStartSuccessLog(async () => {
+                    await runCommand('app:start', startArgv);
+                });
+            });
+            if (resolvedVersion.persistDownloadVersion) {
+                await AppUpgrade.persistDownloadVersion(runtime, resolvedVersion.persistDownloadVersion);
+            }
+            try {
+                await runWithSuppressedTargetEnvLog(async () => {
+                    await runCommand('env:update', buildEnvUpdateArgv(runtime.envName, parsed));
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                printWarning(formatEnvUpdateWarning(runtime.envName, message));
+            }
+            const displayUrl = formatDisplayUrl(runtime.env.baseUrl, runtime.env.appPort === undefined || runtime.env.appPort === null ? undefined : String(runtime.env.appPort));
+            succeedTask(`NocoBase has been upgraded for "${runtime.envName}"${displayUrl ? ` at ${displayUrl}` : ''}.`);
+        }
+        catch (error) {
+            this.error(error instanceof Error ? error.message : String(error));
+        }
+    }
+}

package/dist/commands/backup/create.js

@@ -0,0 +1,147 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+import { Command, Flags } from '@oclif/core';
+import { BACKUP_CREATE_TIMEOUT_MS, BACKUP_POLL_INTERVAL_MS, BACKUP_RUNTIME_COMMANDS, buildBackupEnvArgv, ensureBackupRuntimeCommands, resolveBackupCreateOutputPath, resolveBackupTargetEnv, runBackupCliJsonCommand, sleep, } from '../../lib/backup.js';
+import { ensureCrossEnvConfirmed, hasExplicitEnvSelection } from '../../lib/env-guard.js';
+import { announceTargetEnv, failTask, startTask, succeedTask, updateTask } from '../../lib/ui.js';
+function formatBackupCreateTimeoutError(envName, name) {
+    return [
+        `Backup "${name}" did not finish in time for "${envName}".`,
+        `Waited ${Math.floor(BACKUP_CREATE_TIMEOUT_MS / 1000)}s but it still reports \`inProgress: true\`.`,
+    ].join(' ');
+}
+function readBackupCreateResult(response) {
+    const name = String(response.data?.name ?? '').trim();
+    if (!name) {
+        throw new Error('Backup creation did not return a backup name.');
+    }
+    return {
+        name,
+        inProgress: Boolean(response.data?.inProgress),
+    };
+}
+function readBackupInProgress(response, name) {
+    const status = response.data?.[name];
+    if (!status || typeof status !== 'object') {
+        throw new Error(`Backup status did not include "${name}".`);
+    }
+    return Boolean(status.inProgress);
+}
+function readDownloadOutput(response) {
+    const output = String(response.data?.output ?? '').trim();
+    return output || undefined;
+}
+export default class BackupCreate extends Command {
+    static summary = 'Create a backup through the selected env and download it locally';
+    static examples = [
+        '<%= config.bin %> <%= command.id %>',
+        '<%= config.bin %> <%= command.id %> --output ./fixtures/base.nbdump',
+        '<%= config.bin %> <%= command.id %> --env e2e --output ./fixtures',
+    ];
+    static flags = {
+        env: Flags.string({
+            char: 'e',
+            description: 'CLI env name to back up. Defaults to the current env when omitted',
+        }),
+        yes: Flags.boolean({
+            char: 'y',
+            description: 'Confirm using --env when it targets a different env than the current env',
+            default: false,
+        }),
+        output: Flags.string({
+            char: 'o',
+            description: 'Download path. When omitted, save to the current directory using the remote backup filename',
+        }),
+        'json-output': Flags.boolean({
+            char: 'j',
+            description: 'Print the final backup result as JSON',
+            default: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(BackupCreate);
+        const requestedEnv = flags.env?.trim() || undefined;
+        const explicitEnvSelection = Boolean(requestedEnv && hasExplicitEnvSelection(this.argv));
+        const jsonOutput = Boolean(flags['json-output']);
+        if (explicitEnvSelection) {
+            const confirmed = await ensureCrossEnvConfirmed({
+                command: this,
+                requestedEnv,
+                yes: flags.yes,
+            });
+            if (!confirmed) {
+                return;
+            }
+        }
+        const { envName, env } = await resolveBackupTargetEnv(requestedEnv);
+        const envArgv = buildBackupEnvArgv({
+            requestedEnv,
+            explicitEnvSelection,
+            yes: flags.yes,
+        });
+        if (!jsonOutput) {
+            announceTargetEnv(envName);
+        }
+        await ensureBackupRuntimeCommands({
+            envName,
+            env,
+            commandIds: [
+                BACKUP_RUNTIME_COMMANDS.create,
+                BACKUP_RUNTIME_COMMANDS.status,
+                BACKUP_RUNTIME_COMMANDS.download,
+            ],
+            quiet: jsonOutput,
+        });
+        try {
+            if (!jsonOutput) {
+                startTask(`Creating backup for "${envName}"...`);
+            }
+            const createResponse = await runBackupCliJsonCommand(['api', 'backup', 'create', ...envArgv], { errorName: 'nb api backup create' });
+            const { name, inProgress } = readBackupCreateResult(createResponse);
+            const outputPath = await resolveBackupCreateOutputPath(flags.output, name);
+            const startedAt = Date.now();
+            let pending = inProgress;
+            while (pending) {
+                const now = Date.now();
+                const elapsedMs = now - startedAt;
+                if (elapsedMs >= BACKUP_CREATE_TIMEOUT_MS) {
+                    throw new Error(formatBackupCreateTimeoutError(envName, name));
+                }
+                const elapsedSeconds = Math.max(1, Math.floor(elapsedMs / 1000));
+                if (!jsonOutput) {
+                    updateTask(`Waiting for backup "${name}" to finish for "${envName}"... (${elapsedSeconds}s elapsed)`);
+                }
+                await sleep(BACKUP_POLL_INTERVAL_MS);
+                const statusResponse = await runBackupCliJsonCommand(['api', 'backup', 'status', '--name', name, ...envArgv], { errorName: 'nb api backup status' });
+                pending = readBackupInProgress(statusResponse, name);
+            }
+            if (!jsonOutput) {
+                updateTask(`Downloading backup "${name}" for "${envName}"...`);
+            }
+            const downloadResponse = await runBackupCliJsonCommand(['api', 'backup', 'download', '--name', name, '--output', outputPath, ...envArgv], { errorName: 'nb api backup download' });
+            const savedPath = readDownloadOutput(downloadResponse) ?? outputPath;
+            const result = {
+                env: envName,
+                name,
+                output: savedPath,
+            };
+            if (jsonOutput) {
+                this.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            succeedTask(`Backup saved to ${savedPath}`);
+        }
+        catch (error) {
+            if (!jsonOutput) {
+                failTask(`Failed to create backup for "${envName}".`);
+            }
+            throw error;
+        }
+    }
+}

package/dist/commands/backup/index.js

@@ -0,0 +1,20 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+import { Command, loadHelpClass } from '@oclif/core';
+export default class Backup extends Command {
+    static summary = 'Create or restore NocoBase backups';
+    async run() {
+        await this.parse(Backup);
+        const Help = await loadHelpClass(this.config);
+        await new Help(this.config, this.config.pjson.oclif.helpOptions ?? this.config.pjson.helpOptions).showHelp([
+            this.id ?? 'backup',
+            ...this.argv,
+        ]);
+    }
+}