@nocobase/plugin-ai 2.3.0-alpha.1 → 3.0.0-alpha.1

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

@@ -0,0 +1,136 @@
+---
+title: "nb portal"
+description: "nb portal command reference: manage portals, including configuration, creation, development, source sync, deployment, and deletion."
+keywords: "nb portal,NocoBase CLI,Portal,workspace,source storage,deploy"
+---
+
+# nb portal
+
+`nb portal` manages portals. A portal can have its own frontend source, entry path, and deployment output; this command group connects the portal record in NocoBase with the local workspace and source storage.
+
+A typical flow is to create a local workspace, start development mode, push source changes to source storage, and then build and deploy. If you are taking over an existing portal, pull it locally first.
+
+## Usage
+
+```bash
+nb portal <command>
+```
+
+## Subcommands
+
+| Command | Description |
+| --- | --- |
+| [`nb portal config`](./config.md) | Update the local portal source configuration and sync it to the remote portal record when possible |
+| [`nb portal create`](./create.md) | Create a local portal from a template and create or update the portal record |
+| [`nb portal deploy`](./deploy.md) | Build and deploy the specified portal |
+| [`nb portal destroy`](./destroy.md) | Delete the portal record and local workspace |
+| [`nb portal dev`](./dev.md) | Start development mode for the specified portal |
+| [`nb portal info`](./info.md) | Show details for the specified portal record and local workspace |
+| [`nb portal list`](./list.md) | List portal records and local workspace sync status |
+| [`nb portal pull`](./pull.md) | Pull portal source from source storage into the local workspace |
+| [`nb portal push`](./push.md) | Push local portal source changes to source storage |
+
+## Typical Flow
+
+Create a portal named `customer`:
+
+```bash
+nb portal create customer -e dev --yes
+```
+
+Start local development mode:
+
+```bash
+nb portal dev customer -e dev --yes
+```
+
+Inspect the local workspace and remote record:
+
+```bash
+nb portal info customer -e dev --yes
+nb portal list -e dev --yes
+```
+
+Push source and deploy:
+
+```bash
+nb portal push customer -e dev --yes --message "Update customer portal"
+nb portal deploy customer -e dev --yes
+```
+
+Take over an existing portal:
+
+```bash
+nb portal list -e dev --yes
+nb portal pull customer -e dev --yes
+nb portal dev customer -e dev --yes
+```
+
+Switch source storage:
+
+```bash
+nb portal config customer -e dev --yes --source-storage git --git-repo git@github.com:nocobase/customer-portal.git
+nb portal push customer -e dev --yes --message "Move customer portal source to Git"
+```
+
+## source storage
+
+When creating a portal, choose where the source code is managed:
+
+| Mode | Description |
+| --- | --- |
+| `nocobase` | Default mode. Source code is managed by NocoBase source storage. |
+| `git` | Source code is stored in a Git repository, configured with `--git-repo`, `--git-branch`, and `--git-path`. |
+
+For quick creation and development, the default `nocobase` storage is usually enough. Use `git` when the portal source should be reviewed, versioned, or built through an existing team workflow.
+
+Source configuration is written to `portal.config.json` in the local workspace. `create`, `pull`, and `config` maintain this file; `push` and `deploy` read it to sync source or deployment output.
+
+## Env Types
+
+`nb portal` currently supports `local`, `docker`, and `http` envs:
+
+| Mode | Description |
+| --- | --- |
+| `local` | The workspace and app storage are on the current machine. With default `nocobase` storage, `pull`/`push` usually do not need extra sync. |
+| `docker` | The workspace is shared with the app through a Docker volume. With default `nocobase` storage, `pull`/`push` usually do not need extra sync. |
+| `http` | Source and deployment output are synced through APIs. `pull` downloads a source archive, and `push` uploads one. |
+
+`ssh` envs do not support portal management in the current version.
+
+## Local Workspace Path
+
+Portals are stored under the selected env storage:
+
+```text
+<storagePath>/portals/<app>/<portal>
+```
+
+The main app access path is usually:
+
+```text
+<appPublicPath>/x/<portal>/
+```
+
+A sub-app access path is usually:
+
+```text
+<appPublicPath>/x/apps/<app>/<portal>/
+```
+
+## Env Confirmation
+
+Most `nb portal` subcommands support `--env` and `--yes`:
+
+| Flag | Description |
+| --- | --- |
+| `--env`, `-e` | CLI env name. If omitted, the current env is used. |
+| `--yes`, `-y` | Skip cross-env confirmation when an explicit `--env` targets a different env from the current env. |
+
+In scripts or AI agent workflows, pass `--env` and `--yes` explicitly to avoid stopping at an interactive confirmation.
+
+## Related Commands
+
+- [`nb env`](../env/index.md)
+- [`nb app`](../app/index.md)
+- [`nb source`](../source/index.md)

package/dist/ai/docs/nocobase/api/cli/portal/info.md

@@ -0,0 +1,41 @@
+---
+title: "nb portal info"
+description: "nb portal info command reference: show portal record and local workspace details."
+keywords: "nb portal info,NocoBase CLI,Portal"
+---
+
+# nb portal info
+
+Show details for the specified portal record and local workspace
+
+## Usage
+
+```bash
+nb portal info <portal> [flags]
+```
+
+## Flag
+
+| Flag | Type | Description |
+| --- | --- | --- |
+| `<portal>` | string | Portal name or slug. |
+| `--env`, `-e` | string | CLI env name. If omitted, the current env is used. |
+| `--yes`, `-y` | boolean | Skip cross-env confirmation. |
+| `--json-output`, `-j` | boolean | Print portal details as JSON. |
+
+## Examples
+
+```bash
+nb portal info customer
+nb portal info customer --env dev --yes
+nb portal info customer --json-output
+```
+
+## Notes
+
+Text output includes name, URL, portal type, local path, enabled status, and local sync status. `--json-output` prints `name`, `url`, `portalType`, `localPath`, `enabled`, `sourceStorage`, and `localSynced`. You can query by `routeName` or `uid`.
+
+## Related Commands
+
+- [`nb portal`](./index.md)
+- [`nb env`](../env/index.md)

package/dist/ai/docs/nocobase/api/cli/portal/list.md

@@ -0,0 +1,40 @@
+---
+title: "nb portal list"
+description: "nb portal list command reference: list portal records and local workspace sync status."
+keywords: "nb portal list,NocoBase CLI,Portal"
+---
+
+# nb portal list
+
+List portal records and local workspace sync status
+
+## Usage
+
+```bash
+nb portal list [flags]
+```
+
+## Flag
+
+| Flag | Type | Description |
+| --- | --- | --- |
+| `--env`, `-e` | string | CLI env name. If omitted, the current env is used. |
+| `--yes`, `-y` | boolean | Skip cross-env confirmation. |
+| `--json-output`, `-j` | boolean | Print portal records as JSON. |
+
+## Examples
+
+```bash
+nb portal list
+nb portal list --env dev --yes
+nb portal list --json-output
+```
+
+## Notes
+
+The list shows name, URL, portal type, source storage, local path, enabled status, and local sync status. Only `ai` portals have local workspace sync checks; other portal types show an empty sync status.
+
+## Related Commands
+
+- [`nb portal`](./index.md)
+- [`nb env`](../env/index.md)

package/dist/ai/docs/nocobase/api/cli/portal/pull.md

@@ -0,0 +1,43 @@
+---
+title: "nb portal pull"
+description: "nb portal pull command reference: pull portal source into the local workspace."
+keywords: "nb portal pull,NocoBase CLI,Portal"
+---
+
+# nb portal pull
+
+Pull portal source from source storage into the local workspace
+
+## Usage
+
+```bash
+nb portal pull <portal> [flags]
+```
+
+## Flag
+
+| Flag | Type | Description |
+| --- | --- | --- |
+| `<portal>` | string | Portal name or slug. |
+| `--env`, `-e` | string | CLI env name. If omitted, the current env is used. |
+| `--yes`, `-y` | boolean | Skip cross-env confirmation. |
+| `--force` | boolean | Delete the existing local workspace and pull it again. |
+| `--install` / `--no-install` | boolean | Run `pnpm install` after pulling source. Enabled by default. |
+
+## Examples
+
+```bash
+nb portal pull customer
+nb portal pull customer --env prod --yes
+nb portal pull customer --force
+nb portal pull customer --no-install
+```
+
+## Notes
+
+When the pulled workspace contains `package.json`, `pnpm install` runs by default. Use `--no-install` to skip it. Git source storage clones the configured repo and branch, then copies `--git-path`. With default `nocobase` storage, `local` and `docker` envs are usually no-op; `http` envs download a source archive through the API.
+
+## Related Commands
+
+- [`nb portal`](./index.md)
+- [`nb env`](../env/index.md)

package/dist/ai/docs/nocobase/api/cli/portal/push.md

@@ -0,0 +1,41 @@
+---
+title: "nb portal push"
+description: "nb portal push command reference: push local portal source changes to source storage."
+keywords: "nb portal push,NocoBase CLI,Portal"
+---
+
+# nb portal push
+
+Push local portal source changes to source storage
+
+## Usage
+
+```bash
+nb portal push <portal> [flags]
+```
+
+## Flag
+
+| Flag | Type | Description |
+| --- | --- | --- |
+| `<portal>` | string | Portal name or slug. |
+| `--env`, `-e` | string | CLI env name. If omitted, the current env is used. |
+| `--yes`, `-y` | boolean | Skip cross-env confirmation. |
+| `--message`, `-m` | string | Source update message; for Git-managed source, it is used as the Git commit message. |
+
+## Examples
+
+```bash
+nb portal push customer
+nb portal push customer --env prod --yes
+nb portal push customer --message "Update customer portal"
+```
+
+## Notes
+
+The command reads `portal.config.json` and syncs that configuration to the remote portal record first. Git source storage clones the configured repo, copies the local workspace into `--git-path`, commits, and pushes. With default `nocobase` storage, `local` and `docker` envs are usually no-op; `http` envs upload a source archive through the API.
+
+## Related Commands
+
+- [`nb portal`](./index.md)
+- [`nb env`](../env/index.md)