@nocobase/cli 2.1.0-beta.24 → 2.1.0-beta.26

package/README.md

@@ -336,6 +336,23 @@ nb api resource get --resource users --filter-by-tk 1 -e app1
 nb api resource create --resource users --values '{"nickname":"Ada"}' -e app1
 ```
 
+Create and download a backup:
+
+```bash
+nb api backup create -e app1
+nb api backup status --name backup_20260430_120000_1234.nbdata -e app1
+nb api backup download --name backup_20260430_120000_1234.nbdata --output ./backup.nbdata -e app1
+```
+
+Restore or run a migration package:
+
+```bash
+nb api backup restore-upload --file ./backup.nbdata -e app1
+nb api migration rules create --name default --user-defined-rule schema-only --system-defined-rule overwrite-first -e app1
+nb api migration create --rule-id 1 --title release-20260430 -e app1
+nb api migration execute --file ./migration.nbdata -e app1
+```
+
 Use `-j, --json-output` to print raw JSON when available:
 
 ```bash
@@ -350,9 +367,11 @@ Available API command topics:
 | `nb api api-keys` | Manage API keys for HTTP API access. |
 | `nb api app` | Manage application resources. |
 | `nb api authenticators` | Manage user authentication, including password auth, SMS auth, SSO protocols, and extensible providers. |
+| `nb api backup` | Create, download, remove, and restore backups. |
 | `nb api data-modeling` | Manage data sources, collections, and database modeling resources. |
 | `nb api file-manager` | Manage file storage services, file collections, and attachment fields. |
 | `nb api flow-surfaces` | Compose and mutate page, tab, block, field, and action surfaces. |
+| `nb api migration` | Create, check, execute, and inspect migration packages. |
 | `nb api pm` | Manage plugins through API commands. |
 | `nb api resource` | Work with generic collection resources. |
 | `nb api system-settings` | Adjust system title, logo, language, and other global settings. |

package/dist/commands/app/down.js

@@ -92,21 +92,26 @@ function builtinDbContainerName(runtime) {
         return undefined;
     }
     const dbDialect = String(runtime.env.config.dbDialect ?? 'postgres').trim() || 'postgres';
-    const workspaceName = runtime.workspaceName;
-    return buildDockerDbContainerName(runtime.envName, dbDialect, workspaceName);
+    return buildDockerDbContainerName(runtime.envName, dbDialect, runtime.dockerContainerPrefix || runtime.workspaceName);
 }
 function managedDockerNetworkName(runtime) {
-    return runtime.workspaceName?.trim() || undefined;
+    return runtime.dockerNetworkName?.trim() || runtime.workspaceName?.trim() || undefined;
 }
-async function confirmDownAll(envName, yes) {
+async function confirmDownAll(envName, yes, options) {
     if (yes) {
         return true;
     }
+    const usedCurrentEnv = options?.explicitEnv === false;
     if (!isInteractiveTerminal()) {
+        if (usedCurrentEnv) {
+            throw new Error(`\`nb app down --all\` is using the current env "${envName}". Re-run with --env ${envName} --yes to delete everything for that env in non-interactive mode.`);
+        }
         throw new Error(`\`nb app down --all\` needs confirmation. Re-run with --yes to delete everything for "${envName}" in non-interactive mode.`);
     }
     const answer = await p.confirm({
-        message: `Delete everything for "${envName}"? This removes the app, managed containers, storage data, and the saved CLI env config.`,
+        message: usedCurrentEnv
+            ? `Delete everything for current env "${envName}"? This removes the app, managed containers, storage data, and the saved CLI env config.`
+            : `Delete everything for "${envName}"? This removes the app, managed containers, storage data, and the saved CLI env config.`,
         active: 'yes',
         inactive: 'no',
         initialValue: false,
@@ -153,6 +158,7 @@ export default class AppDown extends Command {
     async run() {
         const { flags } = await this.parse(AppDown);
         const requestedEnv = flags.env?.trim() || undefined;
+        const explicitEnv = Boolean(requestedEnv);
         const removeData = Boolean(flags.all);
         const removeEnvConfig = Boolean(flags.all);
         const runtime = await resolveManagedAppRuntime(requestedEnv);
@@ -176,7 +182,7 @@ export default class AppDown extends Command {
         if (flags.all) {
             let confirmed = false;
             try {
-                confirmed = await confirmDownAll(runtime.envName, flags.yes);
+                confirmed = await confirmDownAll(runtime.envName, flags.yes, { explicitEnv });
             }
             catch (error) {
                 this.error(error instanceof Error ? error.message : String(error));

package/dist/commands/app/logs.js

@@ -39,7 +39,7 @@ export default class AppLogs extends Command {
         follow: Flags.boolean({
             char: 'f',
             description: 'Keep streaming new log lines',
-            default: true,
+            default: false,
             allowNo: true,
         }),
     };
@@ -65,7 +65,7 @@ export default class AppLogs extends Command {
             ].join('\n'));
         }
         const tail = String(flags.tail ?? 100);
-        const follow = flags.follow !== false;
+        const follow = flags.follow === true;
         printInfo(follow
             ? `Showing logs for "${runtime.envName}" (press Ctrl+C to stop).`
             : `Showing recent logs for "${runtime.envName}".`);

package/dist/commands/app/start.js

@@ -10,7 +10,7 @@ import { Command, Flags } from '@oclif/core';
 import { formatMissingManagedAppEnvMessage, resolveManagedAppRuntime, runLocalNocoBaseCommand, startDockerContainer, } from '../../lib/app-runtime.js';
 import { AppHealthCheckError, formatAppUrl, isAppReady, resolveManagedAppApiBaseUrl, waitForAppReady, } from '../../lib/app-health.js';
 import { ensureBuiltinDbReady, ensureSavedLocalSource, recreateSavedDockerApp, } from '../../lib/app-managed-resources.js';
-import { failTask, printInfo, startTask, succeedTask } from '../../lib/ui.js';
+import { announceTargetEnv, failTask, printInfo, startTask, succeedTask } from '../../lib/ui.js';
 function argvHasToken(argv, tokens) {
     return tokens.some((token) => argv.includes(token));
 }
@@ -107,6 +107,7 @@ export default class AppStart extends Command {
                 'Use a local or Docker env if you need CLI-managed start and stop right now.',
             ].join('\n'));
         }
+        announceTargetEnv(runtime.envName);
         if (runtime.kind === 'docker') {
             const unsupportedFlags = [
                 flags.quickstart ? '--quickstart' : undefined,

package/dist/commands/app/stop.js

@@ -8,7 +8,7 @@
  */
 import { Command, Flags } from '@oclif/core';
 import { formatMissingManagedAppEnvMessage, resolveManagedAppRuntime, runLocalNocoBaseCommand, stopDockerContainer, } from '../../lib/app-runtime.js';
-import { failTask, startTask, succeedTask } from '../../lib/ui.js';
+import { announceTargetEnv, failTask, startTask, succeedTask } from '../../lib/ui.js';
 function formatStopFailure(envName, message) {
     if (/does not exist/i.test(message)) {
         return [
@@ -65,6 +65,7 @@ export default class AppStop extends Command {
                 'Use a local or Docker env if you need CLI-managed stop right now.',
             ].join('\n'));
         }
+        announceTargetEnv(runtime.envName);
         if (runtime.kind === 'docker') {
             startTask(`Stopping NocoBase for "${runtime.envName}"...`);
             try {

package/dist/commands/app/upgrade.js

@@ -7,12 +7,13 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 import { Command, Flags } from '@oclif/core';
+import { upsertEnv } from '../../lib/auth-store.js';
 import { formatMissingManagedAppEnvMessage, resolveManagedAppRuntime, runLocalNocoBaseCommand, startDockerContainer, stopDockerContainer, } from '../../lib/app-runtime.js';
 import { resolveConfiguredEnvPath } from '../../lib/cli-home.js';
-import { commandOutput, commandSucceeds, run } from '../../lib/run-npm.js';
-import { failTask, printInfo, startTask, stopTask, succeedTask, updateTask } from '../../lib/ui.js';
+import { deriveBuiltinDbConnection } from '../../lib/builtin-db.js';
+import { commandSucceeds, run } from '../../lib/run-npm.js';
+import { announceTargetEnv, failTask, printInfo, startTask, stopTask, succeedTask, updateTask } from '../../lib/ui.js';
 const DEFAULT_DOCKER_REGISTRY = 'nocobase/nocobase';
-const DEFAULT_DOWNLOAD_VERSION = 'alpha';
 const DOCKER_APP_STORAGE_DESTINATION = '/app/nocobase/storage';
 const APP_HEALTH_CHECK_INTERVAL_MS = 2_000;
 const APP_HEALTH_CHECK_TIMEOUT_MS = 600_000;
@@ -92,27 +93,6 @@ function formatDockerStartFailure(envName, message) {
         `Details: ${message}`,
     ].join('\n');
 }
-function parseDockerImageRef(imageRef) {
-    const cleaned = trimValue(imageRef).replace(/@.+$/, '');
-    if (!cleaned) {
-        return {
-            dockerRegistry: DEFAULT_DOCKER_REGISTRY,
-            version: DEFAULT_DOWNLOAD_VERSION,
-        };
-    }
-    const lastSlash = cleaned.lastIndexOf('/');
-    const lastColon = cleaned.lastIndexOf(':');
-    if (lastColon > lastSlash) {
-        return {
-            dockerRegistry: cleaned.slice(0, lastColon),
-            version: cleaned.slice(lastColon + 1) || DEFAULT_DOWNLOAD_VERSION,
-        };
-    }
-    return {
-        dockerRegistry: cleaned,
-        version: 'latest',
-    };
-}
 function normalizeDockerPlatform(value) {
     const text = String(value ?? '').trim();
     if (!text || text === 'auto') {
@@ -215,52 +195,14 @@ async function ensureDockerNetwork(name) {
         stdio: 'ignore',
     });
 }
-async function inspectDockerContainerEnv(name) {
-    const output = await commandOutput('docker', [
-        'inspect',
-        '--format',
-        '{{range .Config.Env}}{{println .}}{{end}}',
-        name,
-    ], {
-        errorName: 'docker inspect',
-    });
-    const env = {};
-    for (const line of output.split(/\r?\n/)) {
-        const index = line.indexOf('=');
-        if (index <= 0) {
-            continue;
-        }
-        env[line.slice(0, index)] = line.slice(index + 1);
-    }
-    return env;
-}
-async function inspectDockerContainerImage(name) {
-    return await commandOutput('docker', [
-        'inspect',
-        '--format',
-        '{{.Config.Image}}',
-        name,
-    ], {
-        errorName: 'docker inspect',
-    });
-}
-async function inspectDockerStoragePath(name) {
-    return await commandOutput('docker', [
-        'inspect',
-        '--format',
-        `{{range .Mounts}}{{if eq .Destination "${DOCKER_APP_STORAGE_DESTINATION}"}}{{println .Source}}{{end}}{{end}}`,
-        name,
-    ], {
-        errorName: 'docker inspect',
-    });
-}
 export default class AppUpgrade extends Command {
     static hidden = false;
-    static description = 'Upgrade the selected NocoBase app. Local npm/git installs refresh the saved source and restart with quickstart; Docker installs refresh the saved image and recreate the app container.';
+    static description = 'Upgrade the selected NocoBase app. Local npm/git installs refresh the saved source and restart with quickstart; Docker installs refresh the saved image and recreate the app container. Use --version to upgrade to a specific saved source version or image tag.';
     static examples = [
         '<%= config.bin %> <%= command.id %>',
         '<%= config.bin %> <%= command.id %> --env local',
         '<%= 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',
     ];
@@ -274,23 +216,49 @@ export default class AppUpgrade extends Command {
             description: 'Restart with the saved local code or Docker image without downloading updates first',
             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: false,
         }),
     };
-    static buildLocalDownloadArgv(runtime) {
+    static resolveUpgradeVersion(runtime, flags) {
+        const requestedVersion = trimValue(flags.version);
+        if (requestedVersion && flags['skip-code-update']) {
+            throw new Error('`--version` and `--skip-code-update` cannot be used together. Use `--version` to download a specific upgrade target, or `--skip-code-update` to restart the saved code/image as-is.');
+        }
+        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 {};
+        }
+        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` or `nb env add` for this env, or pass `--version` to `nb app upgrade`.',
+            ].join('\n'));
+        }
+        return {
+            downloadVersion,
+            persistDownloadVersion: requestedVersion || undefined,
+        };
+    }
+    static buildLocalDownloadArgv(runtime, downloadVersion) {
         const argv = ['-y', '--no-intro', '--source', runtime.source, '--replace'];
-        const version = readEnvValue(runtime.env, 'downloadVersion');
-        const outputDir = readEnvValue(runtime.env, 'appRootPath');
         const gitUrl = readEnvValue(runtime.env, 'gitUrl');
         const npmRegistry = readEnvValue(runtime.env, 'npmRegistry');
-        if (version) {
-            argv.push('--version', version);
-        }
-        if (outputDir) {
-            argv.push('--output-dir', outputDir);
-        }
+        argv.push('--version', downloadVersion, '--output-dir', runtime.projectRoot);
         if (gitUrl) {
             argv.push('--git-url', gitUrl);
         }
@@ -308,6 +276,24 @@ export default class AppUpgrade extends Command {
         }
         return argv;
     }
+    static buildDockerDownloadArgv(runtime, plan) {
+        const argv = [
+            '-y',
+            '--no-intro',
+            '--source',
+            'docker',
+            '--replace',
+            '--docker-registry',
+            plan.dockerRegistry,
+            '--version',
+            plan.downloadVersion,
+        ];
+        const dockerPlatform = normalizeDockerPlatform(runtime.env.config.dockerPlatform);
+        if (dockerPlatform) {
+            argv.push('--docker-platform', dockerPlatform);
+        }
+        return argv;
+    }
     static buildLocalStartArgv(runtime) {
         const argv = ['start', '--quickstart'];
         const appPort = runtime.env.appPort === undefined || runtime.env.appPort === null
@@ -319,43 +305,26 @@ export default class AppUpgrade extends Command {
         argv.push('--daemon');
         return argv;
     }
-    static async buildDockerUpgradePlan(runtime) {
-        const containerExists = await dockerContainerExists(runtime.containerName);
-        let inspectedEnv;
-        const readContainerEnv = async () => {
-            if (!containerExists) {
-                return {};
-            }
-            if (!inspectedEnv) {
-                inspectedEnv = await inspectDockerContainerEnv(runtime.containerName);
-            }
-            return inspectedEnv;
-        };
-        let dockerRegistry = readEnvValue(runtime.env, 'dockerRegistry');
-        let version = readEnvValue(runtime.env, 'downloadVersion');
-        if ((!dockerRegistry || !version) && containerExists) {
-            const imageRef = await inspectDockerContainerImage(runtime.containerName);
-            const parsed = parseDockerImageRef(imageRef);
-            dockerRegistry ||= parsed.dockerRegistry;
-            version ||= parsed.version;
-        }
-        const envVars = await readContainerEnv();
+    static buildDockerUpgradePlan(runtime, downloadVersion) {
+        const dockerRegistry = readEnvValue(runtime.env, 'dockerRegistry') || DEFAULT_DOCKER_REGISTRY;
         const appPort = runtime.env.appPort === undefined || runtime.env.appPort === null
             ? ''
             : trimValue(runtime.env.appPort);
-        let storagePath = readEnvValue(runtime.env, 'storagePath');
-        if (!storagePath && containerExists) {
-            storagePath = trimValue(await inspectDockerStoragePath(runtime.containerName));
-        }
-        const appKey = readEnvValue(runtime.env, 'appKey') || trimValue(envVars.APP_KEY);
-        const timeZone = readEnvValue(runtime.env, 'timezone') || trimValue(envVars.TZ);
-        const dbDialect = readEnvValue(runtime.env, 'dbDialect') || trimValue(envVars.DB_DIALECT);
-        const dbHost = readEnvValue(runtime.env, 'dbHost') || trimValue(envVars.DB_HOST);
-        const dbPort = readEnvValue(runtime.env, 'dbPort') || trimValue(envVars.DB_PORT);
-        const dbDatabase = readEnvValue(runtime.env, 'dbDatabase') || trimValue(envVars.DB_DATABASE);
-        const dbUser = readEnvValue(runtime.env, 'dbUser') || trimValue(envVars.DB_USER);
-        const dbPassword = readEnvValue(runtime.env, 'dbPassword') || trimValue(envVars.DB_PASSWORD);
+        const storagePath = readEnvValue(runtime.env, 'storagePath');
+        const appKey = readEnvValue(runtime.env, 'appKey');
+        const timeZone = readEnvValue(runtime.env, 'timezone');
+        const builtinDbConnection = runtime.env.config.builtinDb ? deriveBuiltinDbConnection(runtime) : undefined;
+        const dbDialect = builtinDbConnection?.dbDialect || readEnvValue(runtime.env, 'dbDialect');
+        const dbHost = builtinDbConnection?.dbHost || readEnvValue(runtime.env, 'dbHost');
+        const dbPort = builtinDbConnection?.dbPort || readEnvValue(runtime.env, 'dbPort');
+        const dbDatabase = readEnvValue(runtime.env, 'dbDatabase');
+        const dbUser = readEnvValue(runtime.env, 'dbUser');
+        const dbPassword = readEnvValue(runtime.env, 'dbPassword');
+        const networkName = trimValue(runtime.dockerNetworkName || runtime.workspaceName);
         const missing = [];
+        if (!networkName) {
+            missing.push('docker.network');
+        }
         if (!storagePath) {
             missing.push('storagePath');
         }
@@ -386,9 +355,7 @@ export default class AppUpgrade extends Command {
         if (missing.length > 0) {
             throw new Error(`The saved Docker settings for "${runtime.envName}" are incomplete. Missing: ${missing.join(', ')}. Re-run \`nb init\` or \`nb env add\` to refresh this env config.`);
         }
-        const resolvedRegistry = dockerRegistry || DEFAULT_DOCKER_REGISTRY;
-        const resolvedVersion = version || DEFAULT_DOWNLOAD_VERSION;
-        const imageRef = `${resolvedRegistry}:${resolvedVersion}`;
+        const imageRef = `${dockerRegistry}:${downloadVersion}`;
         const args = [
             'run',
             '-d',
@@ -397,7 +364,7 @@ export default class AppUpgrade extends Command {
             '--restart',
             'always',
             '--network',
-            runtime.workspaceName,
+            networkName,
         ];
         if (appPort) {
             args.push('-p', `${appPort}:80`);
@@ -405,7 +372,9 @@ export default class AppUpgrade extends Command {
         args.push('-e', `APP_KEY=${appKey}`, '-e', `DB_DIALECT=${dbDialect}`, '-e', `DB_HOST=${dbHost}`, '-e', `DB_PORT=${dbPort}`, '-e', `DB_DATABASE=${dbDatabase}`, '-e', `DB_USER=${dbUser}`, '-e', `DB_PASSWORD=${dbPassword}`, '-e', `TZ=${timeZone}`, '-v', `${storagePath}:${DOCKER_APP_STORAGE_DESTINATION}`, imageRef);
         return {
             containerName: runtime.containerName,
-            networkName: runtime.workspaceName,
+            networkName,
+            dockerRegistry,
+            downloadVersion,
             imageRef,
             appPort: appPort || undefined,
             storagePath,
@@ -420,7 +389,7 @@ export default class AppUpgrade extends Command {
             args,
         };
     }
-    static async upgradeLocal(runCommand, runtime, flags, commandStdio) {
+    static async upgradeLocal(runCommand, runtime, downloadVersion, flags, commandStdio) {
         const displayUrl = formatDisplayUrl(resolveApiBaseUrl(runtime), trimValue(runtime.env.appPort));
         startTask(`Stopping NocoBase for "${runtime.envName}" before upgrade...`);
         try {
@@ -437,7 +406,7 @@ export default class AppUpgrade extends Command {
         if (!flags['skip-code-update'] && (runtime.source === 'npm' || runtime.source === 'git')) {
             startTask(`Refreshing NocoBase files for "${runtime.envName}" from the saved ${runtime.source} source...`);
             try {
-                await runCommand('source:download', AppUpgrade.buildLocalDownloadArgv(runtime));
+                await runCommand('source:download', AppUpgrade.buildLocalDownloadArgv(runtime, downloadVersion));
                 succeedTask(`NocoBase files are up to date for "${runtime.envName}".`);
             }
             catch (error) {
@@ -468,22 +437,16 @@ export default class AppUpgrade extends Command {
             envName: runtime.envName,
             apiBaseUrl: resolveApiBaseUrl(runtime),
         });
-        succeedTask(`NocoBase has been upgraded for "${runtime.envName}"${displayUrl ? ` at ${displayUrl}` : ''}.`);
+        return displayUrl;
     }
-    static async upgradeDocker(runCommand, runtime, flags, commandStdio) {
-        const plan = await AppUpgrade.buildDockerUpgradePlan(runtime);
+    static async upgradeDocker(runCommand, runtime, downloadVersion, flags, commandStdio) {
         const apiBaseUrl = resolveApiBaseUrl(runtime);
-        const displayUrl = formatDisplayUrl(apiBaseUrl, plan.appPort);
         const containerExists = await dockerContainerExists(runtime.containerName);
         if (!flags['skip-code-update']) {
-            const argv = ['-y', '--no-intro', '--source', 'docker', '--replace', '--docker-registry', parseDockerImageRef(plan.imageRef).dockerRegistry, '--version', parseDockerImageRef(plan.imageRef).version];
-            const dockerPlatform = normalizeDockerPlatform(runtime.env.config.dockerPlatform);
-            if (dockerPlatform) {
-                argv.push('--docker-platform', dockerPlatform);
-            }
+            const plan = AppUpgrade.buildDockerUpgradePlan(runtime, downloadVersion);
             startTask(`Refreshing the Docker image for "${runtime.envName}"...`);
             try {
-                await runCommand('source:download', argv);
+                await runCommand('source:download', AppUpgrade.buildDockerDownloadArgv(runtime, plan));
                 succeedTask(`Docker image is ready for "${runtime.envName}".`);
             }
             catch (error) {
@@ -528,6 +491,8 @@ export default class AppUpgrade extends Command {
             }
         }
         else {
+            const plan = AppUpgrade.buildDockerUpgradePlan(runtime, downloadVersion);
+            const displayUrl = formatDisplayUrl(apiBaseUrl, plan.appPort);
             startTask(`Recreating the Docker app container for "${runtime.envName}"...`);
             try {
                 if (containerExists) {
@@ -548,13 +513,32 @@ export default class AppUpgrade extends Command {
                 failTask(`Failed to recreate the Docker app for "${runtime.envName}".`);
                 throw new Error(formatDockerStartFailure(runtime.envName, message));
             }
+            await waitForAppHealthCheck({
+                envName: runtime.envName,
+                apiBaseUrl,
+                containerName: runtime.containerName,
+            });
+            return displayUrl;
         }
         await waitForAppHealthCheck({
             envName: runtime.envName,
             apiBaseUrl,
             containerName: runtime.containerName,
         });
-        succeedTask(`NocoBase has been upgraded for "${runtime.envName}"${displayUrl ? ` at ${displayUrl}` : ''}.`);
+        return formatDisplayUrl(apiBaseUrl, trimValue(runtime.env.appPort));
+    }
+    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);
@@ -579,14 +563,17 @@ export default class AppUpgrade extends Command {
                 'Use a local or Docker env if you need CLI-managed upgrades right now.',
             ].join('\n'));
         }
+        announceTargetEnv(runtime.envName);
         try {
+            const resolvedVersion = AppUpgrade.resolveUpgradeVersion(runtime, parsed);
             const runCommand = this.config.runCommand.bind(this.config);
-            if (runtime.kind === 'docker') {
-                await AppUpgrade.upgradeDocker(runCommand, runtime, parsed, commandStdio);
-            }
-            else {
-                await AppUpgrade.upgradeLocal(runCommand, runtime, parsed, commandStdio);
+            const displayUrl = runtime.kind === 'docker'
+                ? await AppUpgrade.upgradeDocker(runCommand, runtime, resolvedVersion.downloadVersion, parsed, commandStdio)
+                : await AppUpgrade.upgradeLocal(runCommand, runtime, resolvedVersion.downloadVersion, parsed, commandStdio);
+            if (resolvedVersion.persistDownloadVersion) {
+                await AppUpgrade.persistDownloadVersion(runtime, resolvedVersion.persistDownloadVersion);
             }
+            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/config/delete.js

@@ -0,0 +1,30 @@
+/**
+ * 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 { Args, Command } from '@oclif/core';
+import { assertSupportedCliConfigKey, deleteCliConfigValue } from '../../lib/cli-config.js';
+export default class ConfigDelete extends Command {
+    static summary = 'Delete an explicitly configured CLI setting';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> license.pkg-url',
+        '<%= config.bin %> <%= command.id %> docker.network',
+        '<%= config.bin %> <%= command.id %> docker.container-prefix',
+    ];
+    static args = {
+        key: Args.string({
+            description: 'Configuration key',
+            required: true,
+        }),
+    };
+    async run() {
+        const { args } = await this.parse(ConfigDelete);
+        const key = assertSupportedCliConfigKey(args.key);
+        const removed = await deleteCliConfigValue(key);
+        this.log(removed ? `Deleted ${key}` : `${key} was not set`);
+    }
+}

package/dist/commands/config/get.js

@@ -0,0 +1,29 @@
+/**
+ * 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 { Args, Command } from '@oclif/core';
+import { assertSupportedCliConfigKey, getCliConfigValue } from '../../lib/cli-config.js';
+export default class ConfigGet extends Command {
+    static summary = 'Get the effective CLI configuration value for a key';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> license.pkg-url',
+        '<%= config.bin %> <%= command.id %> docker.network',
+        '<%= config.bin %> <%= command.id %> docker.container-prefix',
+    ];
+    static args = {
+        key: Args.string({
+            description: 'Configuration key',
+            required: true,
+        }),
+    };
+    async run() {
+        const { args } = await this.parse(ConfigGet);
+        const key = assertSupportedCliConfigKey(args.key);
+        this.log(await getCliConfigValue(key));
+    }
+}

package/dist/commands/config/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 Config extends Command {
+    static summary = 'Manage CLI configuration defaults';
+    async run() {
+        await this.parse(Config);
+        const Help = await loadHelpClass(this.config);
+        await new Help(this.config, this.config.pjson.oclif.helpOptions ?? this.config.pjson.helpOptions).showHelp([
+            this.id ?? 'config',
+            ...this.argv,
+        ]);
+    }
+}

package/dist/commands/config/list.js

@@ -0,0 +1,29 @@
+/**
+ * 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 } from '@oclif/core';
+import { listExplicitCliConfigValues, SUPPORTED_CLI_CONFIG_KEYS } from '../../lib/cli-config.js';
+import { renderTable } from '../../lib/ui.js';
+export default class ConfigList extends Command {
+    static summary = 'List explicitly configured CLI settings';
+    static examples = [
+        '<%= config.bin %> <%= command.id %>',
+    ];
+    async run() {
+        await this.parse(ConfigList);
+        const values = await listExplicitCliConfigValues();
+        const rows = SUPPORTED_CLI_CONFIG_KEYS
+            .filter((key) => Boolean(values[key]))
+            .map((key) => [key, values[key] ?? '']);
+        if (!rows.length) {
+            this.log('No CLI config values are set.');
+            return;
+        }
+        this.log(renderTable(['Key', 'Value'], rows));
+    }
+}