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

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

@@ -1,12 +1,16 @@
 ---
-title: "nb init"
-description: "nb init command reference: initialize NocoBase, connect an existing app or install a new app, and save it as a CLI env."
-keywords: "nb init,NocoBase CLI,initialization,env,Docker,npm,Git"
+title: 'nb init'
+description: 'nb init command reference: install a new app, take over an existing local app, or connect to a remote app and save it as a CLI env.'
+keywords: 'nb init,NocoBase CLI,initialize,env,Docker,npm,Git,remote connection'
 ---
 
 # nb init
 
-Initialize the current workspace so coding agents can connect to and use NocoBase. `nb init` can connect an existing app or install a new app from Docker, npm, or Git.
+Initialize the current workspace so the coding agent can connect to and use NocoBase.
+
+`nb init` can install a new local NocoBase app, or save the connection information of an existing app.
+
+In addition, `nb init` also synchronizes NocoBase AI coding skills by default. You only need to add `--skip-skills` if you already manage skills yourself, or if you are running in CI or an offline environment.
 
 ## Usage
 
@@ -14,85 +18,263 @@ Initialize the current workspace so coding agents can connect to and use NocoBas
 nb init [flags]
 ```
 
-## Notes
+## Interactive modes
 
-`nb init` supports three prompt modes:
+`nb init` supports three interactive modes:
 
-- Default mode: fill in setup details step by step in the terminal.
-- `--ui`: open a local browser form for the setup wizard.
-- `--yes`: skip prompts and use flags plus defaults. This mode requires `--env <envName>` and creates a new local app.
+- `nb init`: complete the setup step by step in the terminal
+- `nb init --ui`: open a local browser form and complete setup with a visual wizard
+- `nb init --yes --env app1`: skip prompts and use flags directly; parameters not explicitly passed will use default values
 
-By default, `nb init` installs or updates NocoBase AI coding skills during initialization or resume. Use `--skip-skills` to skip this step when skills are managed separately, or when running in CI or offline environments.
+`--yes` mode is suitable for scripts, CI/CD, or other non-interactive scenarios. In this mode, `--env <envName>` is required. Generally, it installs a new local app by default; if you do not specify `--source`, it uses `docker` as the default install source.
 
-If initialization is interrupted after env configuration has been saved, resume it with:
+## Resuming interrupted initialization
+
+Installation flows save the env configuration first, then perform download, database, and app installation. If the process fails midway, you can continue with:
 
 ```bash
 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.
+
+## Installation directory layout
+
+You can view the full path with `nb env info app1 --field app.appPath`.
+
+By default, the CLI organizes local files under `app-path` using the following convention:
+
+```text
+<app-path>/
+├── source/   # Default directory for app source code or downloaded content
+├── storage/  # Runtime data directory
+└── .env      # Optional app environment variable file
+```
+
+Typically:
+
+- `source/` mainly corresponds to the local app directory for npm / Git envs. For Docker envs, the CLI also keeps this default path derivation, but most of the time you do not need to care about it manually
+- `storage/` is used for runtime data, such as built-in database data, plugins, logs, and more
+- `.env` is an optional app environment variable file. You only need to add it in `<app-path>/.env` when you want to customize environment variables; if this file exists, Docker, npm, and Git install sources will all read it by default
+
+This represents the CLI's default directory convention. Depending on the install source, plugins, and runtime stage, the actual generated directory contents may not be exactly the same.
+
+## Notes
+
+:::warning Notes
+
+- `--ui` cannot be used together with `--yes`
+- `--ui` also cannot be used together with `--resume`
+- `--ui-host` and `--ui-port` can only be used together with `--ui`
+- `--skip-auth` cannot be used together with `--access-token` or `--token`
+
+:::
+
+## Quickly locate by Steps
+
+The Steps shown are not exactly the same for different setup paths. For example, when connecting to an existing app, you usually only use `Getting started` and `Remote connection`.
+
+If you are following the local UI wizard step by step, you can first use the table below to quickly locate the relevant section:
+
+| Step                      | Main related parameters                                                                                                                                                                                           |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Getting started`         | `--env`、`--yes`、`--ui`、`--locale`、`--verbose`、`--skip-skills`、`--resume`                                                                                                                                    |
+| `App environment`         | `--lang`、`--app-path`、`--app-port`、`--force`                                                                                                                                                                   |
+| `App source and version`  | `--source`、`--version`、`--skip-download`、`--git-url`、`--docker-registry`、`--docker-platform`、`--npm-registry`、`--replace`、`--dev-dependencies`、`--output-dir`、`--docker-save`、`--build`、`--build-dts` |
+| `Configure the database`  | `--builtin-db`、`--db-dialect`、`--builtin-db-image`、`--db-host`、`--db-port`、`--db-database`、`--db-user`、`--db-password`、`--db-schema`、`--db-table-prefix`、`--db-underscored`                             |
+| `Create an admin account` | `--root-username`、`--root-email`、`--root-password`、`--root-nickname`                                                                                                                                           |
+| `Remote connection`       | `--api-base-url`、`--auth-type`、`--access-token`、`--username`、`--password`、`--skip-auth`                                                                                                                      |
+
 ## Parameters
 
-| Parameter | Type | Description |
-| --- | --- | --- |
-| `--yes`, `-y` | boolean | Skip prompts and use flags plus defaults |
-| `--env`, `-e` | string | Env name for this setup; required with `--yes` and `--resume` |
-| `--ui` | boolean | Open the browser-based setup wizard; cannot be used with `--yes` |
-| `--verbose` | boolean | Show verbose command output |
-| `--skip-skills` | boolean | Skip installing or updating NocoBase AI coding skills during init |
-| `--ui-host` | string | Local service bind address for `--ui`, default `127.0.0.1` |
-| `--ui-port` | integer | Local service port for `--ui`; `0` means auto-assign |
-| `--locale` | string | CLI prompt and UI language: `en-US` or `zh-CN` |
-| `--api-base-url`, `-u` | string | NocoBase API URL, including the `/api` prefix |
-| `--auth-type`, `-a` | string | Authentication type: `token` or `oauth` |
-| `--access-token`, `-t` | string | API key or access token used with `token` authentication |
-| `--resume` | boolean | Reuse saved workspace env config and continue initialization |
-| `--lang`, `-l` | string | Language for the installed NocoBase app |
-| `--force`, `-f` | boolean | Reconfigure an existing env and replace conflicting runtime resources when needed |
-| `--app-root-path` | string | Local npm/Git app source directory, default `./<envName>/source/` |
-| `--app-port` | string | Local app port, default `13000`; `--yes` mode auto-selects an available port |
-| `--storage-path` | string | Directory for uploaded files and managed database data, default `./<envName>/storage/` |
-| `--root-username` | string | Initial admin username |
-| `--root-email` | string | Initial admin email |
-| `--root-password` | string | Initial admin password |
-| `--root-nickname` | string | Initial admin nickname |
-| `--builtin-db`, `--no-builtin-db` | boolean | Whether to create a CLI-managed built-in database |
-| `--db-dialect` | string | Database dialect: `postgres`, `mysql`, `mariadb`, or `kingbase` |
-| `--builtin-db-image` | string | Built-in database container image |
-| `--db-host` | string | Database host |
-| `--db-port` | string | Database port |
-| `--db-database` | string | Database name |
-| `--db-user` | string | Database user |
-| `--db-password` | string | Database password |
-| `--skip-download` | boolean | Skip downloading app files or pulling the Docker image before installation, and reuse existing local resources |
-| `--source`, `-s` | string | How to obtain NocoBase: `docker`, `npm`, or `git` |
-| `--version`, `-v` | string | Version parameter: npm version, Docker image tag, or Git ref |
-| `--replace`, `-r` | boolean | Replace the target directory if it already exists |
-| `--dev-dependencies`, `-D` | boolean | Whether npm/Git installs devDependencies |
-| `--output-dir`, `-o` | string | Download target directory, or directory for the Docker tarball |
-| `--git-url` | string | Git repository URL |
-| `--docker-registry` | string | Docker image repository name without tag |
-| `--docker-platform` | string | Docker image platform: `auto`, `linux/amd64`, or `linux/arm64` |
-| `--docker-save`, `--no-docker-save` | boolean | Whether to save the pulled Docker image as a tarball |
-| `--npm-registry` | string | Registry used for npm/Git downloads and dependency installation |
-| `--build`, `--no-build` | boolean | Whether to build after npm/Git dependency installation |
-| `--build-dts` | boolean | Whether to generate TypeScript declaration files during npm/Git build |
+There are many parameters, so it is clearer to break them down by usage scenario.
+
+The “Default” below means the value or behavior that `nb init` usually uses when you omit that parameter.
+
+### Basics and interaction
+
+| Parameter       | Type    | Default                                                                      | Description                                                                            |
+| --------------- | ------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `--yes`, `-y`   | boolean | `false`                                                                      | Skip prompts and use flags and default values                                          |
+| `--env`, `-e`   | string  | None                                                                         | The env name to save for this initialization; required in `--yes` and `--resume` modes |
+| `--ui`          | boolean | `false`                                                                      | Open the local browser wizard; cannot be used with `--yes` or `--resume`               |
+| `--verbose`     | boolean | `false`                                                                      | Show detailed command output                                                           |
+| `--skip-skills` | boolean | `false`                                                                      | Skip syncing NocoBase AI coding skills                                                 |
+| `--ui-host`     | string  | `127.0.0.1`                                                                  | Bind address for the `--ui` local service                                              |
+| `--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   |
+
+### Connecting to an existing app
+
+| Parameter              | Type    | Default | Description                                                                                                                                        |
+| ---------------------- | ------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--api-base-url`, `-u` | string  | None    | API base URL; must include the `/api` prefix                                                                                                       |
+| `--auth-type`, `-a`    | string  | `oauth` | Authentication method: `basic`, `token`, or `oauth`. In most cases, the default `oauth` is fine; in some CI/CD scenarios, `basic` can also be used |
+| `--access-token`, `-t` | string  | None    | API key or access token used for `token` authentication                                                                                            |
+| `--username`           | string  | None    | Username used for `basic` authentication                                                                                                           |
+| `--password`           | string  | None    | Password used for `basic` authentication                                                                                                           |
+| `--skip-auth`          | boolean | `false` | Save the env and auth method first, then complete login later with `nb env auth`                                                                   |
+
+### Basic parameters for local installation
+
+| Parameter         | Type    | Default                             | Description                                                                       |
+| ----------------- | ------- | ----------------------------------- | --------------------------------------------------------------------------------- |
+| `--lang`, `-l`    | string  | `en-US`                             | UI language of the newly installed app                                            |
+| `--force`, `-f`   | boolean | `false`                             | Reconfigure an existing env and replace conflicting runtime resources when needed |
+| `--app-path`      | string  | `./<envName>/`                      | Local npm/Git app directory                                                       |
+| `--app-port`      | string  | `13000`                             | Local app HTTP port; in `--yes` mode, an available port is selected automatically |
+| `--root-username` | string  | `nocobase` (`--yes` mode)           | Initial admin username                                                            |
+| `--root-email`    | string  | `admin@nocobase.com` (`--yes` mode) | Initial admin email                                                               |
+| `--root-password` | string  | `admin123` (`--yes` mode)           | Initial admin password                                                            |
+| `--root-nickname` | string  | `Super Admin` (`--yes` mode)        | Initial admin display name                                                        |
+
+### Database parameters
+
+| Parameter                                  | Type    | Default                                                               | Description                                                       |
+| ------------------------------------------ | ------- | --------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `--builtin-db` / `--no-builtin-db`         | boolean | `true`                                                                | Whether to create and connect a CLI-managed built-in database     |
+| `--db-dialect`                             | string  | `postgres`                                                            | Database type: `postgres`, `mysql`, `mariadb`, `kingbase`         |
+| `--builtin-db-image`                       | string  | Follows `--db-dialect` and locale                                     | Built-in database container image                                 |
+| `--db-host`                                | string  | `postgres` for built-in databases; `127.0.0.1` for external databases | Database host address                                             |
+| `--db-port`                                | string  | `postgres=5432`、`mysql=3306`、`mariadb=3306`、`kingbase=54321`       | Database port                                                     |
+| `--db-database`                            | string  | `nocobase`; `kingbase` for KingbaseES                                 | Database name                                                     |
+| `--db-user`                                | string  | `nocobase`                                                            | Database username                                                 |
+| `--db-password`                            | string  | `nocobase`                                                            | Database password                                                 |
+| `--db-schema`                              | string  | None                                                                  | Database schema; only used by PostgreSQL                          |
+| `--db-table-prefix`                        | string  | None                                                                  | Database table prefix                                             |
+| `--db-underscored` / `--no-db-underscored` | boolean | `false`                                                               | Whether database table names and field names use underscore style |
+
+### Download and source code parameters
+
+| Parameter                                            | Type    | Default                                                                                          | Description                                                                              |
+| ---------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| `--skip-download`                                    | boolean | `false`                                                                                          | Skip download and reuse an existing local app directory or Docker image                  |
+| `--source`, `-s`                                     | string  | `docker`                                                                                         | How to obtain NocoBase: `docker`, `npm`, or `git`                                        |
+| `--version`, `-v`                                    | string  | `beta`                                                                                           | Version parameter: npm package version, Docker image tag, or Git ref                     |
+| `--replace`, `-r`                                    | boolean | `false`                                                                                          | Replace when the target directory already exists                                         |
+| `--dev-dependencies`, `-D` / `--no-dev-dependencies` | boolean | `false`                                                                                          | Whether to install devDependencies for npm/Git installs                                  |
+| `--output-dir`, `-o`                                 | string  | Derived from `--app-path` for npm/Git; `./nocobase-<version>` for Docker + `--docker-save`       | Download target directory, or the tarball save directory when `--docker-save` is enabled |
+| `--git-url`                                          | string  | `https://github.com/nocobase/nocobase.git`                                                       | Git repository URL                                                                       |
+| `--docker-registry`                                  | string  | `nocobase/nocobase`; under `zh-CN` locale, `registry.cn-shanghai.aliyuncs.com/nocobase/nocobase` | Docker image repository name, without tag                                                |
+| `--docker-platform`                                  | string  | `auto`                                                                                           | Docker image platform: `auto`, `linux/amd64`, `linux/arm64`                              |
+| `--docker-save` / `--no-docker-save`                 | boolean | `false`                                                                                          | Whether to additionally save the Docker image as a tarball after pulling                 |
+| `--npm-registry`                                     | string  | Empty                                                                                            | Registry used for npm/Git download and dependency installation                           |
+| `--build` / `--no-build`                             | boolean | `true`                                                                                           | Whether to build after installing npm/Git dependencies                                   |
+| `--build-dts`                                        | boolean | `false`                                                                                          | Whether to generate TypeScript declaration files during npm/Git builds                   |
 
 ## Examples
 
+The most common usage patterns are as follows.
+
+### Complete the setup step by step in the terminal
+
 ```bash
 nb init
+```
+
+### Open the local browser wizard
+
+```bash
 nb init --ui
+nb init --ui --ui-port 3000
+```
+
+### Install a new local app in non-interactive mode
+
+If you do not specify `--source`, Docker is usually used as the install source.
+
+```bash
 nb init --env app1 --yes
-nb init --env app1 --yes --skip-skills
-nb init --env app1 --resume
-nb init --env app1 --resume --skip-skills
+nb init --env app1 --yes --source docker --version latest
+nb init --env app1 --yes --source docker --version beta
 nb init --env app1 --yes --source docker --version alpha
-nb init --env app1 --yes --source npm --version alpha --app-port 13080
-nb init --env app1 --yes --source git --version fix/cli-v2
-nb init --ui --ui-port 3000
+nb init --env app1 --yes --source docker --version main \
+  --docker-registry registry.cn-beijing.aliyuncs.com/nocobase/nocobase
+nb init --env app1 --yes --source npm --version latest
+nb init --env app1 --yes --source npm --version beta
+nb init --env app1 --yes --source npm --version alpha
+nb init --env app1 --yes --source npm --version beta --app-port 13080
+nb init --env app1 --yes --source git --version latest
+nb init --env app1 --yes --source git --version beta
+nb init --env app1 --yes --source git --version alpha
+nb init --env app1 --yes --source git --version feat/plugin-workflow-timeout
+nb init --env app1 --yes --source git --version latest \
+  --git-url https://gitee.com/nocobase/nocobase.git
+```
+
+### Quick install and use basic authentication
+
+If you want to quickly install a local app in non-interactive mode and directly save `basic` authentication after installation, you can also write it like this. This way, you do not need to open a browser to complete OAuth.
+
+If you keep the default admin account used in `--yes` mode, the shortest form is:
+
+When omitted, the default admin account is `nocobase`, and the default password is `admin123`:
+
+```bash
+nb init --env app1 --yes --auth-type basic
+```
+
+If you also want to customize the admin account, you can write it like this:
+
+```bash
+nb init --env app1 --yes \
+  --auth-type basic \
+  --root-username admin \
+  --root-password secret123
+```
+
+### Connect to an existing app
+
+Using OAuth by default is fine. If opening a browser is inconvenient in some CI/CD scenarios, you can also directly save `basic` authentication; if you already have an API token, you can also directly save `token` authentication.
+
+```bash
+nb init --env staging --yes \
+  --api-base-url https://demo.example.com/api
+
+nb init --env staging --yes \
+  --api-base-url https://demo.example.com/api \
+  --auth-type basic \
+  --username <username> \
+  --password <password>
+
+nb init --env staging --yes \
+  --api-base-url https://demo.example.com/api \
+  --auth-type token \
+  --access-token <token>
+
+nb init --env staging --yes \
+  --api-base-url https://demo.example.com/api \
+  --auth-type oauth \
+  --skip-auth
+```
+
+### Customize database naming
+
+If you need to specify a PostgreSQL schema, table prefix, or underscore naming, you can pass parameters like this:
+
+```bash
+nb init --env app1 --yes \
+  --db-dialect postgres \
+  --db-schema public \
+  --db-table-prefix nb_ \
+  --db-underscored
+```
+
+### Continue the last interrupted initialization
+
+```bash
+nb init --env app1 --resume
+```
+
+### Show detailed logs when troubleshooting
+
+```bash
+nb init --env app1 --yes --source docker --version latest --verbose
 ```
 
-## Related Commands
+## Related commands
 
 - [`nb env add`](./env/add.md)
+- [`nb env auth`](./env/auth.md)
 - [`nb source download`](./source/download.md)

package/dist/ai/docs/nocobase/api/cli/license/activate.md

@@ -1,12 +1,12 @@
 ---
 title: "nb license activate"
-description: "nb license activate command reference: activate NocoBase commercial licensing for a selected env."
+description: "nb license activate command reference: activate an existing NocoBase commercial license key for a selected env."
 keywords: "nb license activate,NocoBase CLI,commercial licensing"
 ---
 
 # nb license activate
 
-Activate commercial licensing for a selected env. You can provide an existing license key directly, or request and activate a license online.
+Activate an existing commercial license key for a selected env. You can pass it directly, read it from a file, or paste it in an interactive terminal.
 
 ## Usage
 
@@ -19,33 +19,34 @@ nb license activate [flags]
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `--env`, `-e` | string | CLI env name; when omitted, the current env is used |
-| `--key` | string | Existing license key to activate |
-| `--key-file` | string | Read the license key from a file |
-| `--online` | boolean | Request a license online and activate it |
-| `--account` | string | License service account for online activation |
-| `--password` | string | License service password for online activation |
-| `--desc` | string | Application name submitted for online activation |
+| `--key` | string | Pass an existing commercial license key directly |
+| `--key-file` | string | Read an existing commercial license key from a file |
 | `--yes`, `-y` | boolean | When an explicitly passed `--env` targets a different env than the current env, skip the interactive confirmation prompt |
 | `--json` | boolean | Output JSON |
 
 ## Examples
 
 ```bash
+nb license activate
 nb license activate --env app1 --key <licenseKey>
 nb license activate --env app1 --key-file ./license.txt
-nb license activate --env app1 --online
-nb license activate --env app1 --online --account aa --password bb --desc test24
-nb license activate --env app1 --online --account aa --password bb --desc test24 --yes
 nb license activate --env app1 --json --key-file ./license.txt
 ```
 
 ## Notes
 
-When online activation is used, the CLI requests a license key from the license service with the current env's instance ID and app URL.
+When run interactively, the CLI first shows the current instance Hostname and Instance ID, then prompts you to paste the license key directly or enter a key file path. Use that information to confirm the license is being bound to the correct instance.
+
+After activation succeeds, restart the app so the license and commercial plugin state actually takes effect. The CLI automatically synchronizes the commercial plugins allowed by the current license before restarting:
+
+```bash
+nb app restart
+```
 
 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.
 
 ## Related Commands
 
+- [`nb app restart`](../app/restart.md)
 - [`nb license id`](./id.md)
 - [`nb license status`](./status.md)

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

@@ -6,7 +6,7 @@ keywords: "nb license,NocoBase CLI,commercial licensing,license"
 
 # nb license
 
-Manage NocoBase commercial licensing, including license activation, instance IDs, license status, and licensed plugins.
+Manage NocoBase commercial licensing, including activating an existing license key, instance IDs, license status, and licensed plugins.
 
 ## Usage
 
@@ -18,7 +18,7 @@ nb license <command>
 
 | Command | Description |
 | --- | --- |
-| [`nb license activate`](./activate.md) | Activate commercial licensing for the current env |
+| [`nb license activate`](./activate.md) | Activate commercial licensing for the current env with an existing license key |
 | [`nb license id`](./id.md) | Show or generate the instance ID for the current env |
 | [`nb license status`](./status.md) | Show commercial license status for the current env |
 | [`nb license plugins`](./plugins/index.md) | Manage commercial plugins allowed by the current license |

package/dist/ai/docs/nocobase/api/cli/plugin/import.md

@@ -0,0 +1,74 @@
+---
+title: "nb plugin import"
+description: "nb plugin import command reference: import a packaged plugin archive or npm package into the selected env storage/plugins directory, or into a custom storage path."
+keywords: "nb plugin import,NocoBase CLI,import plugin,storage-path,npm-registry"
+---
+
+# nb plugin import
+
+Import a packaged plugin archive or npm package into `storage/plugins`. This command only puts the plugin into the target directory. It does not enable the plugin automatically.
+
+## Usage
+
+```bash
+nb plugin import <archive> [flags]
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `<archive>` | string | Plugin source. Required. Supports a local `.tgz` path, a remote `http(s)` archive URL, or an npm package name / tag |
+| `--env`, `-e` | string | CLI env name. Usually uses the current env when omitted. If you explicitly pass `--storage-path`, you can omit `--env` |
+| `--yes`, `-y` | boolean | When an explicitly passed `--env` targets a different env than the current env, skip the interactive confirmation prompt |
+| `--storage-path` | string | Override the target storage root path. The actual import directory is `<storage-path>/plugins` |
+| `--npm-registry` | string | When the source is an npm package name or tag, specify the npm registry to use |
+
+## Examples
+
+```bash
+# Remote archive
+nb plugin import https://github.com/nocobase/plugin-auth-cas/releases/download/v1.4.0/plugin-auth-cas-1.4.0.tgz
+
+# Local archive
+nb plugin import /your/path/plugin-auth-cas-1.4.0.tgz
+
+# npm package or tag
+nb plugin import @my-scope/plugin-auth-cas@beta
+
+# Private npm registry
+nb plugin import @my-scope/plugin-auth-cas@beta --npm-registry=https://registry.example.com
+
+# Write directly into a local storage path without relying on the current env
+nb plugin import ./plugin-auth-cas-1.4.0.tgz --storage-path ./storage
+```
+
+## Notes
+
+If you already selected the target env, the default path is that env's `storage/plugins`.
+
+If you only want to write the plugin into a local storage directory, pass `--storage-path`. In that case you can omit `--env`, and the CLI writes directly into `<storage-path>/plugins`.
+
+After the import finishes, the usual next step is to restart the app and then decide whether you also need to enable the plugin. In most cases:
+
+- For a first-time installation, run [`nb app restart`](../app/restart.md) first, then run [`nb plugin enable`](./enable.md)
+- If you only re-imported a newer archive, restart the app first and then verify that the new version has loaded
+
+If the source lives in a private npm registry, log in first and then import it:
+
+```bash
+npm login --registry=https://registry.example.com
+nb plugin import @my-scope/plugin-auth-cas@beta --npm-registry=https://registry.example.com
+```
+
+:::warning Note
+
+You do not need to extract anything into `storage/plugins` by hand. `nb plugin import` puts the plugin into the correct directory automatically.
+
+:::
+
+## Related Commands
+
+- [`nb app restart`](../app/restart.md)
+- [`nb plugin enable`](./enable.md)
+- [`Install and upgrade third-party plugins`](../../../quickstart/plugins/third-party.md)

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

@@ -1,7 +1,7 @@
 ---
 title: "nb plugin"
-description: "nb plugin command reference: manage plugins for the selected NocoBase env."
-keywords: "nb plugin,NocoBase CLI,plugin management,enable,disable,list"
+description: "nb plugin command reference: manage plugins for the selected NocoBase env and import packaged plugins into storage/plugins."
+keywords: "nb plugin,NocoBase CLI,plugin management,enable,disable,list,import"
 ---
 
 # nb plugin
@@ -18,6 +18,7 @@ nb plugin <command>
 
 | Command | Description |
 | --- | --- |
+| [`nb plugin import`](./import.md) | Import a packaged plugin archive or npm package |
 | [`nb plugin list`](./list.md) | List installed plugins |
 | [`nb plugin enable`](./enable.md) | Enable one or more plugins |
 | [`nb plugin disable`](./disable.md) | Disable one or more plugins |
@@ -25,6 +26,7 @@ nb plugin <command>
 ## Examples
 
 ```bash
+nb plugin import ./plugin-auth-cas-1.4.0.tgz --storage-path ./storage
 nb plugin list -e local
 nb plugin enable @nocobase/plugin-sample
 nb plugin disable -e local @nocobase/plugin-sample