@nocobase/plugin-ai 2.1.0-beta.46 → 2.1.0-beta.48

package/dist/ai/docs/nocobase/api/cli/app/restart.md

@@ -20,7 +20,6 @@ nb app restart [flags]
 | --- | --- | --- |
 | `--env`, `-e` | string | CLI env name to restart; uses the current env if omitted |
 | `--yes`, `-y` | boolean | When an explicitly passed `--env` targets a different env than the current env, skip the interactive confirmation prompt |
-| `--daemon`, `-d` / `--no-daemon` | boolean | Whether to run in daemon mode after stopping; enabled by default |
 | `--verbose` | boolean | Show underlying stop and start command output |
 
 ## Examples
@@ -28,14 +27,13 @@ nb app restart [flags]
 ```bash
 nb app restart
 nb app restart --env local
-nb app restart --env local --no-daemon
 nb app restart --env local --verbose
 nb app restart --env local-docker
 ```
 
 If you explicitly pass `--env` and it differs from the current env, the CLI asks for confirmation first. In non-interactive terminals or AI agent sessions, add `--yes` yourself or run `nb env use <name>` first and try again.
 
-By default, when applicable, the CLI first runs `nb license plugins sync --skip-if-no-license` to synchronize the commercial plugins allowed by the current license. Then local envs automatically complete any required install or upgrade preparation before starting again, and Docker envs complete that step before recreating the container. Whenever the CLI needs to wait for readiness, it checks `__health_check`: it prints one waiting line first, then one progress line every 10 seconds until the app becomes available or times out. If you pass `--no-daemon` for a local env, the app runs in the foreground, so the CLI does not keep waiting for the readiness check after startup.
+By default, when applicable, the CLI first runs `nb license plugins sync --skip-if-no-license` to synchronize the commercial plugins allowed by the current license. Then local envs automatically complete any required install or upgrade preparation before starting again, and Docker envs complete that step before recreating the container. Whenever the CLI needs to wait for readiness, it checks `__health_check`: it prints one waiting line first, then one progress line every 10 seconds until the app becomes available or times out.
 
 ## Related Commands
 

package/dist/ai/docs/nocobase/api/cli/app/start.md

@@ -20,7 +20,6 @@ nb app start [flags]
 | --- | --- | --- |
 | `--env`, `-e` | string | CLI env name to start; uses the current env if omitted |
 | `--yes`, `-y` | boolean | When an explicitly passed `--env` targets a different env than the current env, skip the interactive confirmation prompt |
-| `--daemon`, `-d` / `--no-daemon` | boolean | Whether to run in daemon mode; enabled by default |
 | `--verbose` | boolean | Show underlying local or Docker command output |
 
 ## Examples
@@ -28,18 +27,13 @@ nb app start [flags]
 ```bash
 nb app start
 nb app start --env local
-nb app start --env local --daemon
-nb app start --env local --no-daemon
 nb app start --env local --verbose
 nb app start --env local-docker
 ```
 
 If you explicitly pass `--env` and it differs from the current env, the CLI asks for confirmation first. In non-interactive terminals or AI agent sessions, add `--yes` yourself or run `nb env use <name>` first and try again.
 
-By default, when applicable, the CLI first runs `nb license plugins sync --skip-if-no-license` to synchronize the commercial plugins allowed by the current license. Then local envs automatically complete any required install or upgrade preparation before starting in daemon mode, and Docker envs recreate the app container from saved env config. Whenever the CLI needs to wait for readiness, it checks `__health_check`: it prints one waiting line first, then one progress line every 10 seconds until the app becomes available or times out.
-
-If you pass `--no-daemon` for a local env, the app runs in the foreground. In that case, the CLI does not keep waiting for the readiness check after startup.
-
+By default, when applicable, the CLI first runs `nb license plugins sync --skip-if-no-license` to synchronize the commercial plugins allowed by the current license. Then local envs automatically complete any required install or upgrade preparation before starting, and Docker envs recreate the app container from saved env config. Whenever the CLI needs to wait for readiness, it checks `__health_check`: it prints one waiting line first, then one progress line every 10 seconds until the app becomes available or times out.
 ## Related Commands
 
 - [`nb app stop`](./stop.md)

package/dist/ai/docs/nocobase/api/cli/config/delete.md

@@ -1,7 +1,7 @@
 ---
-title: 'nb config delete'
-description: 'nb config delete command reference: delete an explicitly set CLI configuration item.'
-keywords: 'nb config delete,NocoBase CLI,delete configuration'
+title: "nb config delete"
+description: "nb config delete command reference: delete an explicitly set CLI configuration item."
+keywords: "nb config delete,NocoBase CLI,delete configuration"
 ---
 
 # nb config delete
@@ -16,8 +16,8 @@ nb config delete <key>
 
 ## Parameters
 
-| Parameter | Type   | Description                                                                                                                             |
-| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| Parameter | Type | Description |
+| --- | --- | --- |
 | `<key>` | string | Configuration item name. See [`nb config`](./index.md) for supported values |
 
 ## Examples
@@ -29,6 +29,8 @@ nb config delete docker.network
 nb config delete docker.container-prefix
 nb config delete proxy.nb-cli-root
 nb config delete proxy.upstream-host
+nb config delete proxy.nginx-driver
+nb config delete proxy.caddy-driver
 nb config delete bin.nginx
 nb config delete bin.git
 ```

package/dist/ai/docs/nocobase/api/cli/config/get.md

@@ -1,7 +1,7 @@
 ---
-title: 'nb config get'
-description: 'nb config get command reference: read the effective value of a CLI configuration item.'
-keywords: 'nb config get,NocoBase CLI,read configuration'
+title: "nb config get"
+description: "nb config get command reference: read the effective value of a CLI configuration item."
+keywords: "nb config get,NocoBase CLI,read configuration"
 ---
 
 # nb config get
@@ -16,8 +16,8 @@ nb config get <key>
 
 ## Parameters
 
-| Parameter | Type   | Description                                                                                                                             |
-| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| Parameter | Type | Description |
+| --- | --- | --- |
 | `<key>` | string | Configuration item name. See [`nb config`](./index.md) for supported values |
 
 ## Examples
@@ -30,6 +30,8 @@ nb config get docker.network
 nb config get docker.container-prefix
 nb config get proxy.nb-cli-root
 nb config get proxy.upstream-host
+nb config get proxy.nginx-driver
+nb config get proxy.caddy-driver
 nb config get bin.nginx
 nb config get bin.git
 ```

package/dist/ai/docs/nocobase/api/cli/config/index.md

@@ -1,34 +1,44 @@
 ---
-title: 'nb config'
-description: 'nb config command reference: manage the default configuration items of the NocoBase CLI.'
-keywords: 'nb config,NocoBase CLI,configuration,default configuration'
+title: "nb config"
+description: "nb config command reference: manage default configuration items for the NocoBase CLI."
+keywords: "nb config,NocoBase CLI,configuration,default configuration"
 ---
 
 # nb config
 
-Manage the default CLI configuration. The current configuration items mainly fall into these groups:
+Manage default CLI configuration values. The currently supported keys are mainly grouped like this:
 
 - CLI itself: `locale`, `update.policy`, `license.pkg-url`
 - Docker runtime: `docker.network`, `docker.container-prefix`
 - External executables: `bin.docker`, `bin.caddy`, `bin.git`, `bin.nginx`, `bin.yarn`
-- Proxy generation: `proxy.nb-cli-root`, `proxy.upstream-host`
+- Proxy generation: `proxy.nb-cli-root`, `proxy.upstream-host`, `proxy.nginx-driver`, `proxy.caddy-driver`
 
-## Common configuration items
+Most projects only need a few of these keys. In practice, the most common ones are:
 
-| Configuration item | Default value | Description |
+- `update.policy`
+- `docker.network`
+- `docker.container-prefix`
+- `bin.nginx` or `bin.caddy`
+- `proxy.nginx-driver` or `proxy.caddy-driver`
+
+## Common configuration keys
+
+| Key | Default | Description |
 | --- | --- | --- |
-| `locale` | Resolved according to the CLI's current rules | Override the language used by the CLI |
-| `update.policy` | `prompt` | Update policy at startup: `prompt`, `auto`, or `off` |
-| `license.pkg-url` | `https://pkg.nocobase.com/` | Override the commercial extension package download URL |
-| `docker.network` | `nocobase` | Default network for Docker applications managed by the CLI |
-| `docker.container-prefix` | `nb` | Default prefix for Docker containers managed by the CLI |
+| `locale` | resolved by the current CLI rules | Override the language used by the CLI |
+| `update.policy` | `prompt` | Startup update policy: `prompt`, `auto`, or `off` |
+| `license.pkg-url` | `https://pkg.nocobase.com/` | Override the download URL for commercial extension packages |
+| `docker.network` | `nocobase` | Default network for CLI-managed Docker apps |
+| `docker.container-prefix` | `nb` | Default prefix for CLI-managed Docker containers |
 | `bin.docker` | `docker` | Override the Docker executable path |
 | `bin.caddy` | `caddy` | Override the Caddy executable path |
 | `bin.git` | `git` | Override the Git executable path |
 | `bin.nginx` | `nginx` | Override the Nginx executable path |
 | `bin.yarn` | `yarn` | Override the Yarn executable path |
-| `proxy.nb-cli-root` | CLI root, usually the current user's home directory | Map the `.nocobase` path to the root path visible to the proxy process |
-| `proxy.upstream-host` | `127.0.0.1` | Host used when the proxy forwards traffic back to the NocoBase app |
+| `proxy.nb-cli-root` | CLI root, usually the current user's home directory | Override the root path visible to the generated proxy config when the proxy process and CLI do not see the same filesystem root |
+| `proxy.upstream-host` | `127.0.0.1` | Override the host used when the proxy forwards traffic back to the NocoBase app |
+| `proxy.nginx-driver` | `local` | Default runtime driver used by `nb proxy nginx` |
+| `proxy.caddy-driver` | `local` | Default runtime driver used by `nb proxy caddy` |
 
 ## Usage
 
@@ -40,10 +50,10 @@ nb config <command>
 
 | Command | Description |
 | --- | --- |
-| [`nb config get`](./get.md)       | Read the effective value of a configuration item               |
-| [`nb config set`](./set.md)       | Set a configuration item                                       |
-| [`nb config delete`](./delete.md) | Delete an explicitly configured item                           |
-| [`nb config list`](./list.md)     | List the configuration items that are currently explicitly set |
+| [`nb config get`](./get.md) | Read the effective value of a configuration key |
+| [`nb config set`](./set.md) | Set a configuration key |
+| [`nb config delete`](./delete.md) | Delete an explicitly set configuration key |
+| [`nb config list`](./list.md) | List the configuration keys that are currently set explicitly |
 
 ## Examples
 
@@ -54,6 +64,8 @@ nb config set update.policy auto
 nb config get proxy.nb-cli-root
 nb config set proxy.nb-cli-root /workspace
 nb config set proxy.upstream-host host.docker.internal
+nb config set proxy.nginx-driver docker
+nb config set proxy.caddy-driver local
 nb config get docker.network
 nb config set docker.network nocobase
 nb config set bin.nginx /usr/sbin/nginx
@@ -61,7 +73,15 @@ nb config set bin.git /usr/bin/git
 nb config delete docker.container-prefix
 ```
 
+## Notes
+
+- `bin.nginx` and `bin.caddy` only affect the `local` driver for `nb proxy nginx` and `nb proxy caddy`
+- `proxy.nginx-driver` and `proxy.caddy-driver` store the default driver used by each provider
+- `proxy.nb-cli-root` and `proxy.upstream-host` are advanced proxy overrides. Most CLI-managed `local` or `docker` envs can use the defaults directly
+- If you only want to switch the active proxy driver, using `nb proxy nginx use` or `nb proxy caddy use` is usually clearer than setting the config key manually
+
 ## Related commands
 
 - [`nb init`](../init.md)
+- [`nb proxy`](../proxy/index.md)
 - [`nb license`](../license/index.md)

package/dist/ai/docs/nocobase/api/cli/config/set.md

@@ -1,12 +1,12 @@
 ---
-title: 'nb config set'
-description: 'nb config set command reference: set a CLI configuration item.'
-keywords: 'nb config set,NocoBase CLI,set configuration'
+title: "nb config set"
+description: "nb config set command reference: set a CLI configuration item."
+keywords: "nb config set,NocoBase CLI,set configuration"
 ---
 
 # nb config set
 
-Set a CLI configuration item. See [`nb config`](./index.md) for the supported configuration keys.
+Set a CLI configuration item. See [`nb config`](./index.md) for supported configuration keys.
 
 ## Usage
 
@@ -16,10 +16,10 @@ nb config set <key> <value>
 
 ## Parameters
 
-| Parameter | Type   | Description                                                                                                                             |
-| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| Parameter | Type | Description |
+| --- | --- | --- |
 | `<key>` | string | Configuration item name. See [`nb config`](./index.md) for supported values |
-| `<value>` | string | Configuration value, cannot be empty                                                                                                    |
+| `<value>` | string | Configuration value, cannot be empty |
 
 ## Examples
 
@@ -35,6 +35,8 @@ nb config set bin.git /usr/bin/git
 nb config set bin.nginx /usr/sbin/nginx
 nb config set proxy.nb-cli-root /workspace
 nb config set proxy.upstream-host host.docker.internal
+nb config set proxy.nginx-driver docker
+nb config set proxy.caddy-driver local
 nb config set bin.yarn yarn
 ```
 

package/dist/ai/docs/nocobase/api/cli/env/index.md

@@ -1,16 +1,16 @@
 ---
-title: 'nb env'
-description: 'nb env command reference: manage NocoBase CLI envs, including adding, viewing the current env, checking status, switching, updating, generating proxy configs, authenticating, and removing.'
-keywords: 'nb env,NocoBase CLI,environment management,env,current env,proxy,authentication,OpenAPI'
+title: "nb env"
+description: "nb env command reference: manage NocoBase CLI envs, including adding, viewing the current env, checking status, switching, updating, authenticating, and removing."
+keywords: "nb env,NocoBase CLI,environment management,env,current env,authentication,OpenAPI"
 ---
 
 # nb env
 
-Manage saved NocoBase CLI envs. An env stores connection and local runtime information such as the API address, authentication info, local app path, and database configuration.
+Manage saved NocoBase CLI envs. An env stores connection details and local runtime information, such as the API address, authentication info, local app path, and database configuration.
 
 Starting from this version, the CLI separates two concepts:
 
-- `current env`: the env currently used by the current shell or agent runtime, isolated by `NB_SESSION_ID` when possible
+- `current env`: the env currently used by the active shell or agent runtime, isolated by `NB_SESSION_ID` when possible
 - `last env`: the last env used globally, used as a fallback when session mode is not enabled
 
 ## Usage
@@ -21,18 +21,17 @@ nb env <command>
 
 ## Subcommands
 
-| Command                          | Description                                                                        |
-| -------------------------------- | ---------------------------------------------------------------------------------- |
-| [`nb env add`](./add.md)         | Save a NocoBase API endpoint and switch to this env                                |
-| [`nb env current`](./current.md) | View the currently effective env                                                   |
-| [`nb env update`](./update.md)   | Update a saved env configuration and automatically handle follow-up sync as needed |
-| [`nb env list`](./list.md)       | List configured envs                                                               |
-| [`nb env status`](./status.md)   | View the status of the current env, a specified env, or all envs                   |
-| [`nb env info`](./info.md)       | View detailed information for a single env                                         |
-| [`nb env proxy`](./proxy/index.md) | Show proxy provider subcommands and generate Nginx or Caddy configs for one managed env |
-| [`nb env remove`](./remove.md)   | Remove the env configuration after stopping the managed runtime                    |
-| [`nb env auth`](./auth.md)       | Perform OAuth login for a saved env                                                |
-| [`nb env use`](./use.md)         | Switch the current env                                                             |
+| Command | Description |
+| --- | --- |
+| [`nb env add`](./add.md) | Save a NocoBase API endpoint and switch to this env |
+| [`nb env current`](./current.md) | View the env that is currently in effect |
+| [`nb env update`](./update.md) | Update a saved env configuration and automatically handle follow-up sync as needed |
+| [`nb env list`](./list.md) | List configured envs |
+| [`nb env status`](./status.md) | View the status of the current env, a specified env, or all envs |
+| [`nb env info`](./info.md) | View detailed information for a single env |
+| [`nb env remove`](./remove.md) | Remove the env configuration after stopping the managed runtime |
+| [`nb env auth`](./auth.md) | Perform OAuth login for a saved env |
+| [`nb env use`](./use.md) | Switch the current env |
 
 ## Examples
 
@@ -42,7 +41,6 @@ nb env current
 nb env list
 nb env status
 nb env info app1
-nb env proxy nginx --env app1
 nb env update app1
 nb env use app1
 nb env auth app1
@@ -50,9 +48,9 @@ nb env auth app1
 
 ## session mode
 
-Session mode is recommended by default. This allows the `current env` in different terminals, different shells, or different agent runtimes to stay isolated from each other without affecting one another in parallel.
+Session mode is recommended by default. It lets the `current env` in different terminals, shells, or agent runtimes stay isolated from one another instead of interfering in parallel.
 
-If session mode is not enabled, `nb env use` updates the global `last env`, and other sessions without session isolation will also be affected.
+If session mode is not enabled, `nb env use` updates the global `last env`, and other sessions without session isolation are affected as well.
 
 See [`nb session setup`](../session/setup.md) for how to enable it.
 
@@ -61,4 +59,5 @@ See [`nb session setup`](../session/setup.md) for how to enable it.
 - [`nb init`](../init.md)
 - [`nb api`](../api/index.md)
 - [`nb app`](../app/index.md)
+- [`nb proxy`](../proxy/index.md)
 - [`nb session`](../session/index.md)

package/dist/ai/docs/nocobase/api/cli/env/update.md

@@ -1,14 +1,14 @@
 ---
-title: 'nb env update'
-description: 'nb env update command reference: update the saved API, authentication, source code, application, and database configuration.'
-keywords: 'nb env update,NocoBase CLI,env configuration,authentication,database,source code'
+title: "nb env update"
+description: "nb env update command reference: update the saved API, authentication, source code, application, and database configuration."
+keywords: "nb env update,NocoBase CLI,env configuration,authentication,database,source code"
 ---
 
 # nb env update
 
-`nb env update` is used to update the configuration of a saved env. You can use it to adjust the API address, authentication method, source code origin, local app path, port, database parameters, and more. After the update is complete, the CLI will automatically handle the necessary follow-up steps based on the changes.
+`nb env update` updates the configuration of a saved env. You can use it to adjust the API address, authentication method, source origin, local app path, public path, port, database parameters, and more. After the update finishes, the CLI automatically handles any required follow-up steps according to the changes.
 
-If you do not provide any configuration parameters, the CLI will also perform a re-sync based on the current env state.
+If you do not pass any configuration parameters, the CLI still performs a re-sync based on the current env state.
 
 ## Usage
 
@@ -18,112 +18,112 @@ nb env update [name] [flags]
 
 ## Common options
 
-| Option      | Type    | Description                                                                            |
-| ----------- | ------- | -------------------------------------------------------------------------------------- |
-| `[name]`    | string  | The name of the configured environment to update; if omitted, the current env is used. |
-| `--verbose` | boolean | Show detailed progress.                                                                |
+| Option | Type | Description |
+| --- | --- | --- |
+| `[name]` | string | The configured env name to update; if omitted, the current env is used |
+| `--verbose` | boolean | Show detailed progress |
 
 ## API and authentication options
 
-| Option                            | Type   | Description                                                                                                                                                           |
-| --------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--api-base-url`, `-u`            | string | NocoBase API address, including the `/api` prefix.                                                                                                                    |
-| `--auth-type`                     | string | Authentication method: `basic`, `token`, `oauth`.                                                                                                                     |
-| `--access-token`, `--token`, `-t` | string | API key or access token used for `token` authentication. After saving, the authentication method will be switched to `token`.                                         |
-| `--username`                      | string | Username saved for `basic` authentication. Can only be used when the current env uses `basic` authentication, or when `--auth-type basic` is passed at the same time. |
-
-## Source code and download options
-
-| Option                                         | Type    | Description                                                           |
-| ---------------------------------------------- | ------- | --------------------------------------------------------------------- |
-| `--source`                                     | string  | Saved application source: `docker`, `git`, `local`, `npm`.            |
-| `--download-version`, `--version`              | string  | Saved version parameter: Docker tag, npm package version, or Git ref. |
-| `--docker-registry`                            | string  | Docker image registry name, without the tag.                          |
-| `--docker-platform`                            | string  | Docker image platform: `auto`, `linux/amd64`, `linux/arm64`.          |
-| `--git-url`                                    | string  | Git repository URL.                                                   |
-| `--npm-registry`                               | string  | Registry used for npm/Git downloads and dependency installation.      |
-| `--dev-dependencies` / `--no-dev-dependencies` | boolean | Whether to install devDependencies when installing from npm/Git.      |
-| `--build` / `--no-build`                       | boolean | Whether to build automatically after downloading from npm/Git.        |
-| `--build-dts` / `--no-build-dts`               | boolean | Whether to generate TypeScript declaration files during build.        |
+| Option | Type | Description |
+| --- | --- | --- |
+| `--api-base-url`, `-u` | string | NocoBase API URL, including the `/api` prefix |
+| `--auth-type` | string | Authentication method: `basic`, `token`, or `oauth` |
+| `--access-token`, `--token`, `-t` | string | API key or access token used with `token` authentication. Saving it also switches the auth type to `token` |
+| `--username` | string | Username saved for `basic` authentication. Use it only when the current env already uses `basic`, or together with `--auth-type basic` |
+
+## Source and download options
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `--source` | string | Saved app source: `docker`, `git`, `local`, or `npm` |
+| `--download-version`, `--version` | string | Saved version selector: Docker tag, npm package version, or Git ref |
+| `--docker-registry` | string | Docker image registry name, without the tag |
+| `--docker-platform` | string | Docker image platform: `auto`, `linux/amd64`, or `linux/arm64` |
+| `--git-url` | string | Git repository URL |
+| `--npm-registry` | string | Registry used for npm or Git downloads and dependency installation |
+| `--dev-dependencies` / `--no-dev-dependencies` | boolean | Whether to install `devDependencies` for npm or Git sources |
+| `--build` / `--no-build` | boolean | Whether to build automatically after an npm or Git download |
+| `--build-dts` / `--no-build-dts` | boolean | Whether to generate TypeScript declaration files during the build |
 
 ## Application options
 
-| Option       | Type   | Description                                                                                          |
-| ------------ | ------ | ---------------------------------------------------------------------------------------------------- |
-| `--app-path` | string | Application directory. This is now the recommended option for managing local directories by default. |
-| `--app-public-path` | string | Public application path (`APP_PUBLIC_PATH`), such as `/` or `/nocobase/`. |
-| `--app-port` | string | Application HTTP port.                                                                               |
-| `--cdn-base-url` | string | Client asset CDN base URL (`CDN_BASE_URL`). |
-| `--app-key`  | string | Application secret key (`APP_KEY`).                                                                  |
-| `--timezone` | string | Application time zone (`TZ`).                                                                        |
+| Option | Type | Description |
+| --- | --- | --- |
+| `--app-path` | string | Application directory. This is now the preferred way to manage the local app path |
+| `--app-public-path` | string | Public application path (`APP_PUBLIC_PATH`), such as `/` or `/nocobase/` |
+| `--app-port` | string | Application HTTP port |
+| `--cdn-base-url` | string | CDN base URL for client-side static assets (`CDN_BASE_URL`) |
+| `--app-key` | string | Application key (`APP_KEY`) |
+| `--timezone` | string | Application timezone (`TZ`) |
 
 ## Database options
 
-| Option                                     | Type    | Description                                                |
-| ------------------------------------------ | ------- | ---------------------------------------------------------- |
-| `--builtin-db` / `--no-builtin-db`         | boolean | Whether to use the built-in database managed by the CLI.   |
-| `--db-dialect`                             | string  | Database type: `postgres`, `mysql`, `mariadb`, `kingbase`. |
-| `--builtin-db-image`                       | string  | Built-in database container image.                         |
-| `--db-host`                                | string  | Database host address.                                     |
-| `--db-port`                                | string  | Database port.                                             |
-| `--db-database`                            | string  | Database name.                                             |
-| `--db-user`                                | string  | Database username.                                         |
-| `--db-password`                            | string  | Database password.                                         |
-| `--db-schema`                              | string  | Database schema. Usually only used by PostgreSQL.          |
-| `--db-table-prefix`                        | string  | Table prefix.                                              |
-| `--db-underscored` / `--no-db-underscored` | boolean | Whether table names and field names use underscore style.  |
-
-## Configuration cleanup options
-
-| Option    | Type     | Description                                                                                                                                                                    |
-| --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `--unset` | string[] | Clear one or more saved fields by the canonical flag name. Repeated usage is supported, and comma-separated values are also supported, for example `--unset git-url,username`. |
+| Option | Type | Description |
+| --- | --- | --- |
+| `--builtin-db` / `--no-builtin-db` | boolean | Whether to use the built-in database managed by the CLI |
+| `--db-dialect` | string | Database type: `postgres`, `mysql`, `mariadb`, or `kingbase` |
+| `--builtin-db-image` | string | Container image used for the built-in database |
+| `--db-host` | string | Database host |
+| `--db-port` | string | Database port |
+| `--db-database` | string | Database name |
+| `--db-user` | string | Database username |
+| `--db-password` | string | Database password |
+| `--db-schema` | string | Database schema. This is usually used only by PostgreSQL |
+| `--db-table-prefix` | string | Table prefix |
+| `--db-underscored` / `--no-db-underscored` | boolean | Whether table names and field names use underscore naming |
+
+## Configuration cleanup
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `--unset` | string[] | Clear one or more saved fields by flag name. You can repeat the option or pass a comma-separated list, such as `--unset git-url,username` |
 
 ## Notes
 
 :::tip
 
-If you only want the CLI to re-sync according to the latest state of the current env, just run `nb env update` or `nb env update <name>`. No extra parameters are needed.
+If you only want the CLI to re-sync based on the latest state of the current env, simply run `nb env update` or `nb env update <name>` without extra options.
 
 :::
 
-- After the update is complete, the CLI will automatically handle any required follow-up synchronization based on the changes made this time
-- Other options only update the saved env configuration; they do not automatically restart the application or automatically replace local source code or Docker images
-- After modifying settings such as `app-path`, `app-port`, `timezone`, or `db-*`, the CLI will usually prompt you to run `nb app restart --env <name>` afterward; if the change involves the built-in database managed by the CLI, it will prompt you to use `nb app restart --env <name> --with-db`
-- After modifying settings such as `app-port`, `app-public-path`, or `cdn-base-url` that affect reverse-proxy rendering, rerun `nb env proxy nginx` or `nb env proxy caddy` if you already use a generated proxy config
+- After the update is complete, the CLI automatically handles any required follow-up synchronization based on the changes made this time
+- Other options only update the saved env configuration; they do not automatically restart the application or replace local source code or Docker images
+- After modifying settings such as `app-path`, `app-port`, `timezone`, or `db-*`, the CLI usually prompts you to run `nb app restart --env <name>`; if the change involves the built-in database managed by the CLI, it will prompt you to use `nb app restart --env <name> --with-db`
+- After modifying settings such as `app-port`, `app-public-path`, or `cdn-base-url` that affect reverse-proxy output, rerun `nb proxy nginx generate` or `nb proxy caddy generate` if you already use a generated proxy config
 - When updating source settings such as `source`, `download-version`, `docker-registry`, `git-url`, or `npm-registry`, only the saved values are changed. Existing local source code, dependencies, and images are not automatically replaced
 - `--access-token` cannot be used together with `--auth-type basic` or `--auth-type oauth`
-- The same field cannot be used with both `--unset` and an explicit value at the same time. For example, you cannot write both `--unset git-url` and `--git-url ...`
-- If you switch the authentication method to `basic` or `oauth`, or clear the token, you will usually need to run `nb env auth <name>` afterward
+- The same field cannot be used with both `--unset` and an explicit value at the same time. For example, do not use `--unset git-url` together with `--git-url ...`
+- If you switch the authentication method to `basic` or `oauth`, or clear the token, you usually need to run `nb env auth <name>` afterward
 
 ## Examples
 
 ```bash
-# Re-sync the current env according to the latest state
+# Re-sync the current env based on its latest saved state
 nb env update
 
-# Re-sync the specified env according to the latest state
+# Re-sync a specific env
 nb env update prod
 
-# Update the API address
+# Update the API URL
 nb env update prod --api-base-url http://localhost:13000/api
 
-# Update the token and switch the authentication method to token
+# Update the token and switch auth type to token
 nb env update prod --access-token <token>
 
-# Switch to basic authentication, save only the username, and run nb env auth later
+# Switch to basic auth, save the username, and run nb env auth later
 nb env update prod --auth-type basic --username admin
 
-# Adjust the source origin and version, only updating the saved configuration
+# Update the saved source and version without replacing local code yet
 nb env update local --source git --git-url git@github.com:nocobase/nocobase.git --download-version next
 
-# Adjust the application port and time zone, then restart the application later
+# Adjust the app port and timezone, then restart later
 nb env update local --app-port 13080 --timezone Asia/Shanghai
 
-# Adjust the public application path. After that, you usually also need to regenerate the proxy config
+# Adjust the public path and regenerate the proxy afterward if needed
 nb env update local --app-public-path /nocobase/
 
-# Save a CDN base URL for versioned client assets
+# Save the CDN base URL for client assets
 nb env update local --cdn-base-url https://cdn.example.com/nocobase/
 
 # Clear saved fields

package/dist/ai/docs/nocobase/api/cli/index.md

@@ -191,7 +191,6 @@ This file is generated or refreshed by [`nb env update`](./env/update.md) and is
 ## Related links
 
 - [Quick Start](../../ai/quick-start.mdx)
-- [Install, Upgrade, and Migration](../../ai/install-upgrade-migration.mdx)
 - [Global Environment Variables](../app/env.md)
 - [AI Builder](../../ai-builder/index.md)
 - [Plugin Development](../../plugin-development/index.md)

package/dist/ai/docs/nocobase/api/cli/init.md

@@ -38,6 +38,27 @@ nb init --env app1 --resume
 
 `--resume` only applies to initialization flows where the env configuration has already been saved, and `--env` must be passed explicitly.
 
+## Preparing an env without installing the app yet
+
+`--prepare-only` is intended for flows where the env should be prepared first, then the license is activated, and only after that the app is installed and started.
+
+If you want to save the env config, prepare the source files or image, and get the database ready first, but delay the actual app installation and first startup, you can use:
+
+```bash
+nb init --env app1 --prepare-only
+nb init --env app1 --prepare-only --ui
+nb init --env app1 --prepare-only --yes
+```
+
+This mode is available for local installation flows, including the `--ui` wizard. It is not available for remote connection flows. It saves the env as a prepared env, so you can continue later with a flow such as:
+
+```bash
+nb license activate --env app1
+nb app start --env app1
+```
+
+`nb app start` will then complete the first installation and switch the env from the prepared state to the normal installed state.
+
 ## Installation directory layout
 
 You can view the full path with `nb env info app1 --field app.appPath`.
@@ -104,6 +125,7 @@ The “Default” below means the value or behavior that `nb init` usually uses
 | `--ui-port`     | integer | `0`                                                                          | Port for the `--ui` local service; `0` means automatic assignment                      |
 | `--locale`      | string  | Follows `NB_LOCALE`, CLI config, or system locale; final fallback is `en-US` | Language for CLI prompts and the local setup UI: `en-US` or `zh-CN`                    |
 | `--resume`      | boolean | `false`                                                                      | Continue the last unfinished initialization and reuse the saved workspace env config   |
+| `--prepare-only` | boolean | `false`                                                                     | Save and prepare a local installation env, including `--ui` flows, without installing or starting the app yet |
 
 ### Connecting to an existing app
 
@@ -180,6 +202,14 @@ nb init --ui
 nb init --ui --ui-port 3000
 ```
 
+### Prepare first, then activate the license and start later
+
+```bash
+nb init --env app1 --prepare-only
+nb license activate --env app1
+nb app start --env app1
+```
+
 ### Install a new local app in non-interactive mode
 
 If you do not specify `--source`, Docker is usually used as the install source.