@nocobase/plugin-ai 2.1.0-beta.43 → 2.1.0-beta.45

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

@@ -1,16 +1,18 @@
 ---
-title: "nb env remove"
-description: "nb env remove command reference: remove a selected NocoBase CLI env config."
-keywords: "nb env remove,NocoBase CLI,delete environment,remove config"
+title: 'nb env remove'
+description: 'nb env remove command reference: stop managed runtimes before removing env configuration, or fully clean up locally managed resources when needed.'
+keywords: 'nb env remove,NocoBase CLI,delete environment,remove configuration,purge'
 ---
 
 # nb env remove
 
-Remove a configured env. This command only removes the saved CLI env config and does not clean local app directories, containers, or storage data; use [`nb app down`](../app/down.md) when you need to clean local runtime resources.
+Remove a configured env. For local/docker envs, this command first stops the CLI-managed application runtime and built-in database runtime on the current machine, then removes the saved CLI env configuration. For http/ssh envs, this command only removes the saved CLI env configuration.
 
-If the removed env is also the current env, the CLI automatically selects a new current env from the remaining envs. If no envs remain, the current env is cleared.
+If the removed env is the current env, the CLI automatically selects a new current env from the remaining envs; if no envs are available, the current env is cleared.
 
-By default, the command asks for confirmation. To skip confirmation, pass `--yes`. In non-interactive mode, `--yes` is required before the env can be removed.
+By default, the command requires confirmation. In non-interactive mode, you must explicitly pass `--force` to execute it.
+
+To clean up CLI-managed resources on the current machine as thoroughly as possible, pass `--purge`. For local/docker envs, `--purge` also cleans up managed runtime resources, storage data, and downloaded local app files when applicable; for http/ssh envs, `--purge` does not affect external services and only removes the saved CLI env configuration.
 
 ## Usage
 
@@ -20,21 +22,23 @@ nb env remove <name> [flags]
 
 ## Parameters
 
-| Parameter | Type | Description |
-| --- | --- | --- |
-| `<name>` | string | Configured environment name to remove |
-| `--yes`, `-y` | boolean | Skip confirmation and remove the saved CLI env config |
-| `--verbose` | boolean | Show detailed progress |
+| Parameter       | Type    | Description                                                                                                                                                                                        |
+| --------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<name>`        | string  | Name of the configured environment to remove                                                                                                                                                       |
+| `--force`, `-f` | boolean | Skip confirmation for the current remove mode; required in non-interactive mode                                                                                                                    |
+| `--purge`       | boolean | Additionally clean up CLI-managed resources, storage data, and downloaded local app files on the current machine when applicable; for remote API envs, only the saved env configuration is removed |
+| `--verbose`     | boolean | Show detailed progress                                                                                                                                                                             |
 
 ## Examples
 
 ```bash
 nb env remove staging
-nb env remove staging --yes
+nb env remove staging --force
+nb env remove staging --purge --force
 ```
 
-## Related Commands
+## Related commands
 
-- [`nb app down`](../app/down.md)
+- [`nb app stop`](../app/stop.md)
 - [`nb env current`](./current.md)
 - [`nb env list`](./list.md)

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

@@ -1,12 +1,14 @@
 ---
-title: "nb env update"
-description: "nb env update command reference: refresh OpenAPI Schema and runtime command cache for a selected env."
-keywords: "nb env update,NocoBase CLI,OpenAPI,runtime commands,swagger"
+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
 
-Refresh OpenAPI Schema from the NocoBase app and update local runtime command cache. Cache is stored in `.nocobase/versions/<hash>/commands.json`.
+`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.
+
+If you do not provide any configuration parameters, the CLI will also perform a re-sync based on the current env state.
 
 ## Usage
 
@@ -14,27 +16,126 @@ Refresh OpenAPI Schema from the NocoBase app and update local runtime command ca
 nb env update [name] [flags]
 ```
 
-## Parameters
+## 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.                                                                |
+
+## 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.        |
+
+## 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`).                                                                        |
+
+## 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`. |
+
+## Notes
 
-| Parameter | Type | Description |
-| --- | --- | --- |
-| `[name]` | string | Configured environment name to refresh; uses the current env if omitted |
-| `--verbose` | boolean | Show detailed progress |
-| `--api-base-url` | string | Override the NocoBase API URL and persist it to the target env |
-| `--role` | string | Role override sent as the `X-Role` request header |
-| `--token`, `-t` | string | API key override persisted to the target env |
+:::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.
+
+:::
+
+- 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
+- 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
 
 ## Examples
 
 ```bash
+# Re-sync the current env according to the latest state
 nb env update
+
+# Re-sync the specified env according to the latest state
 nb env update prod
+
+# Update the API address
 nb env update prod --api-base-url http://localhost:13000/api
-nb env update prod --token <token>
+
+# Update the token and switch the authentication method to token
+nb env update prod --access-token <token>
+
+# Switch to basic authentication, save only 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
+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
+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
+nb env update local --app-public-path /nocobase/
+
+# Save a CDN base URL for versioned client assets
+nb env update local --cdn-base-url https://cdn.example.com/nocobase/
+
+# Clear saved fields
+nb env update local --unset git-url --unset username
+nb env update local --unset git-url,username
 ```
 
-## Related Commands
+## Related commands
 
 - [`nb api`](../api/index.md)
+- [`nb env auth`](./auth.md)
 - [`nb env info`](./info.md)
 - [`nb env add`](./add.md)
+- [`nb app restart`](../app/restart.md)
+- [`nb source download`](../source/download.md)

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

@@ -1,21 +1,21 @@
 ---
-title: "NocoBase CLI"
-description: "NocoBase CLI (nb command) reference: initialization, configuration, environment management, app runtime, source, database, plugins, commercial licensing, API, CLI self updates, and Skills management."
-keywords: "NocoBase CLI,nb,command line,command reference,configuration,environment management,plugin management,commercial licensing,API"
+title: 'NocoBase CLI'
+description: 'NocoBase CLI (`nb` command) reference: initialization, backup and restore, configuration, environment management, app runtime, source code, database, plugins, commercial license, API, CLI self-update, and Skills management.'
+keywords: 'NocoBase CLI,nb,command line,command reference,backup,restore,environment management,plugin management,commercial license,API'
 ---
 
 # NocoBase CLI
 
 ## Description
 
-NocoBase CLI (`nb`) is the command-line entry point for initializing, connecting to, and managing NocoBase apps in a local workspace.
+NocoBase CLI (`nb`) is the command-line entry point for NocoBase, used to initialize, connect to, and manage NocoBase applications in a local workspace.
 
-It supports two common setup paths:
+It supports two common initialization paths:
 
-- Connect an existing NocoBase app and save it as a CLI env
-- Install a new NocoBase app from Docker, npm, or Git, then save it as a CLI env
+- Connect to an existing NocoBase application and save it as a CLI env
+- Install a new NocoBase application via Docker, npm, or Git, then save it as a CLI env
 
-When creating a new local app, [`nb init`](./init.md) can also install or update NocoBase AI coding skills. Use `--skip-skills` when you want to skip that step.
+When creating a new local application, [`nb init`](./init.md) can also install or update NocoBase AI coding skills. To skip this step, use `--skip-skills`.
 
 ## Usage
 
@@ -23,48 +23,50 @@ When creating a new local app, [`nb init`](./init.md) can also install or update
 nb [command]
 ```
 
-The root command mainly displays help and dispatches execution to command groups or standalone commands.
+The root command itself is mainly used to display help and dispatch invocations to command groups or standalone commands.
 
-## Topics
+## Command groups (Topics)
 
-`nb --help` shows the following topics:
+The following command groups are shown in `nb --help`:
 
-| Topic | Description |
-| --- | --- |
-| [`nb api`](./api/index.md) | Work with NocoBase API. |
-| [`nb app`](./app/index.md) | Manage NocoBase app runtimes: start, stop, restart, logs, and upgrades. |
-| [`nb config`](./config/index.md) | Manage CLI configuration defaults. |
-| [`nb db`](./db/index.md) | Manage the built-in database for the selected env. |
-| [`nb env`](./env/index.md) | Manage NocoBase project environments, current env, status, details, and command runtimes. |
-| [`nb license`](./license/index.md) | Manage commercial licensing and licensed plugins. |
-| [`nb plugin`](./plugin/index.md) | Manage plugins in the selected NocoBase env. |
-| [`nb scaffold`](./scaffold/index.md) | Generate NocoBase plugin development scaffolds. |
-| [`nb self`](./self/index.md) | Inspect or update the NocoBase CLI itself. |
-| [`nb session`](./session/index.md) | Configure `NB_SESSION_ID` so current env is isolated per shell or agent runtime. |
-| [`nb skills`](./skills/index.md) | Inspect or synchronize NocoBase AI coding skills for the current workspace. |
-| [`nb source`](./source/index.md) | Work with the local NocoBase source project: download, develop, build, and test. |
+| Command group                        | Description                                                                                   |
+| ------------------------------------ | --------------------------------------------------------------------------------------------- |
+| [`nb api`](./api/index.md)           | Call NocoBase APIs through the CLI.                                                           |
+| [`nb app`](./app/index.md)           | Manage the application runtime: start, stop, restart, logs, and upgrade.                      |
+| [`nb backup`](./backup/index.md)     | Create backups and download them locally, or restore a local backup file to the target env.   |
+| [`nb config`](./config/index.md)     | Manage CLI default configuration.                                                             |
+| [`nb db`](./db/index.md)             | Manage the built-in database of the selected env.                                             |
+| [`nb env`](./env/index.md)           | Manage NocoBase project environments, the current env, status, details, and runtime commands. |
+| [`nb license`](./license/index.md)   | Manage commercial licenses and licensed plugins.                                              |
+| [`nb plugin`](./plugin/index.md)     | Manage plugins in the selected NocoBase env.                                                  |
+| [`nb scaffold`](./scaffold/index.md) | Generate scaffolding for NocoBase plugin development.                                         |
+| [`nb self`](./self/index.md)         | Check or update NocoBase CLI itself.                                                          |
+| [`nb session`](./session/index.md)   | Configure `NB_SESSION_ID` so the current env is isolated by shell or agent runtime.           |
+| [`nb skills`](./skills/index.md)     | Check or sync NocoBase AI coding skills in the current workspace.                             |
+| [`nb source`](./source/index.md)     | Manage local source projects: download, develop, build, and test.                             |
 
 ## Commands
 
-Standalone commands exposed directly by the root command:
+Standalone commands currently exposed directly by the root command:
 
-| Command | Description |
-| --- | --- |
-| [`nb init`](./init.md) | Set up NocoBase so coding agents can connect and work with it. |
+| Command                | Description                                                |
+| ---------------------- | ---------------------------------------------------------- |
+| [`nb init`](./init.md) | Initialize NocoBase so coding agents can connect and work. |
 
-## Display help text
+## Viewing help
 
-Show help for the root command:
+View help for the root command:
 
 ```bash
 nb --help
 ```
 
-Show help for a command or command group:
+View help for a command or command group:
 
 ```bash
 nb init --help
 nb app --help
+nb backup --help
 nb config --help
 nb api resource --help
 nb license --help
@@ -72,25 +74,25 @@ nb license --help
 
 ## Examples
 
-Interactive setup:
+Interactive initialization:
 
 ```bash
 nb init
 ```
 
-Browser-based setup:
+Initialize using a browser form:
 
 ```bash
 nb init --ui
 ```
 
-Create a Docker-based app non-interactively:
+Create a Docker application non-interactively:
 
 ```bash
 nb init --env app1 --yes --source docker --version alpha
 ```
 
-Connect an existing app:
+Connect to an existing application:
 
 ```bash
 nb env add app1 --api-base-url http://localhost:13000/api
@@ -98,7 +100,7 @@ nb env current
 nb env status
 ```
 
-Start the app and refresh runtime commands:
+Resync env status after starting the application:
 
 ```bash
 nb app start -e app1
@@ -111,7 +113,7 @@ Call an API:
 nb api resource list --resource users -e app1
 ```
 
-View CLI default config:
+View CLI default configuration:
 
 ```bash
 nb config list
@@ -125,59 +127,71 @@ nb license status -e app1
 nb license plugins list -e app1
 ```
 
+Create and download a backup:
+
+```bash
+nb backup create -e app1 --output ./backups
+```
+
+Restore a local backup:
+
+```bash
+nb backup restore -e app1 --file ./backups/backup_20260520_190408_8397.nbdata --yes --force
+```
+
 ## Environment variables
 
 The following environment variables affect CLI behavior:
 
-| Variable | Description |
-| --- | --- |
-| `NB_CLI_ROOT` | Root directory where the CLI stores `.nocobase` config and local app files. Defaults to the current user's home directory. |
-| `NB_LOCALE` | Language for CLI prompts and the local setup UI. Supported values are `en-US` and `zh-CN`. |
-| `NB_SESSION_ID` | Session ID for the current shell or agent runtime. When set, `nb env use` and `nb env current` are isolated per session. |
+| Variable        | Description                                                                                                                               |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `NB_CLI_ROOT`   | Root directory where the CLI stores `.nocobase` configuration and local application files. Defaults to the current user's home directory. |
+| `NB_LOCALE`     | CLI prompt language and local initialization UI language. Supports `en-US` and `zh-CN`.                                                   |
+| `NB_SESSION_ID` | Session ID for the current shell or agent runtime. When set, `nb env use` and `nb env current` are isolated by session.                   |
 
 Example:
 
 ```bash
 export NB_CLI_ROOT=/your/workspace
-export NB_LOCALE=en-US
+export NB_LOCALE=zh-CN
 ```
 
 ## Configuration files
 
-Default config file:
+Default configuration file:
 
 ```text
 ~/.nocobase/config.json
 ```
 
-After setting `NB_CLI_ROOT=/your/workspace`, the config file path becomes:
+After setting `NB_CLI_ROOT=/your/workspace`, the configuration file path becomes:
 
 ```text
 /your/workspace/.nocobase/config.json
 ```
 
-The CLI also keeps compatibility with legacy project config under the current working directory.
+The CLI is also compatible with reading legacy project configuration in the current working directory.
 
-Current env session cache is stored in:
+The session-level cache for the current env is stored in:
 
 ```text
 .nocobase/sessions/<NB_SESSION_ID>.json
 ```
 
-The globally last-used env is stored in the `lastEnv` field in `config.json`. When `NB_SESSION_ID` is not set, the CLI falls back to that global value.
+The globally last-used env is stored in the `lastEnv` field of `config.json`. When `NB_SESSION_ID` is not set, the CLI falls back to this global value.
 
-Runtime command cache is stored in:
+The runtime command cache is stored in:
 
 ```text
 .nocobase/versions/<hash>/commands.json
 ```
 
-This file is generated or refreshed by [`nb env update`](./env/update.md) and caches runtime commands synchronized from the target app.
+This file is generated or refreshed by [`nb env update`](./env/update.md) and is used to cache runtime commands synchronized from the target application.
 
 ## Related links
 
 - [Quick Start](../../ai/quick-start.mdx)
 - [Install, Upgrade, and Migration](../../ai/install-upgrade-migration.mdx)
-- [Environment Variables](../app/env.md)
+- [Global Environment Variables](../app/env.md)
 - [AI Builder](../../ai-builder/index.md)
 - [Plugin Development](../../plugin-development/index.md)