@nocobase/plugin-ai 2.1.0-beta.29 → 2.1.0-beta.32

package/dist/ai/docs/nocobase/ai-employees/scenarios/localization-hy-mt.md

@@ -0,0 +1,241 @@
+---
+pkg: '@nocobase/plugin-ai'
+title: 'Use Lina and local HY-MT to translate localization entries'
+description: 'Deploy the HY-MT1.5 GGUF translation model with llama-server and configure it for Lina to batch translate NocoBase localization entries.'
+keywords: 'Lina,localization,HY-MT,GGUF,llama-server,OpenAI compatible,AI translation,NocoBase'
+---
+
+# Use Lina and local HY-MT1.5-1.8B to translate localization entries
+
+This guide describes a localization translation practice: deploy a translation-specific small model locally, expose it as an OpenAI-compatible service, and configure it for Lina to translate localization entries in batches.
+
+This approach is suitable for translating many system entries, plugin text, menus, collection titles, and field labels. Compared with online models, local models are not affected by external API RPM, TPM, or concurrency limits, and concurrency can be tuned according to machine and model capability.
+
+## Overview
+
+This guide uses:
+
+- Model: `tencent/HY-MT1.5-1.8B-GGUF`
+- Inference service: `llama-server`
+- Integration: OpenAI-compatible API
+- AI Employee: Lina
+- Entry point: Localization Management page
+
+:::info{title=Note}
+HY-MT1.5-1.8B is a translation-specific small model. It is more suitable for short entries, UI text, and batch translation. General chat models are not recommended as the first choice for localization tasks.
+:::
+
+## Prerequisites
+
+Before starting, prepare:
+
+- The **Localization Management** plugin is enabled.
+- Target language is enabled.
+- Localization entries have been synchronized.
+- The local machine or server can run [`llama-server`](https://github.com/ggml-org/llama.cpp).
+- The NocoBase service can access the HTTP address of `llama-server`.
+
+## Deploy HY-MT GGUF
+
+### Install llama.cpp
+
+On macOS, you can install it with Homebrew:
+
+```bash
+brew install llama.cpp
+```
+
+You can also use a prebuilt llama.cpp binary or build it from source. The final requirement is that `llama-server` is available.
+
+### Start an OpenAI-compatible service
+
+Start the service with the GGUF model from Hugging Face:
+
+```bash
+llama-server \
+  -hf tencent/HY-MT1.5-1.8B-GGUF:Q4_K_M \
+  --host 0.0.0.0 \
+  --port 8000 \
+  -c 2048 \
+  -np 4
+```
+
+| Parameter | Description |
+| --- | --- |
+| `-hf` | Load the model from Hugging Face. |
+| `--host` | Listening address. Use `127.0.0.1` for local testing or `0.0.0.0` for container or remote access. |
+| `--port` | HTTP service port. |
+| `-c` | Context length. Localization entries are usually short, so `2048` is usually enough. |
+| `-np` | Number of parallel slots. Adjust according to machine performance. |
+
+:::info{title=Tip}
+If server resources are limited, start with `-np 1` or `-np 2`, then increase gradually after verifying stability.
+:::
+
+## Test the Model Service
+
+After `llama-server` starts, check service health:
+
+```bash
+curl http://127.0.0.1:8000/health
+```
+
+Then test translation through the OpenAI-compatible API:
+
+```bash
+curl http://127.0.0.1:8000/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "tencent/HY-MT1.5-1.8B-GGUF:Q4_K_M",
+    "messages": [
+      {
+        "role": "user",
+        "content": "Translate the following text into Chinese. Output only the translated result without any additional explanation:\n\nSave"
+      }
+    ]
+  }'
+```
+
+If you start from a local model file, change `model` to the actual model name returned or configured by the service.
+
+:::warning{title=Note}
+If a request does not respond for a long time, the model may be too slow, concurrency may be too high, or context may be too large. Lower `-np` and NocoBase translation concurrency first, then observe response time.
+:::
+
+## Configure an LLM Service in NocoBase
+
+Go to `System Settings -> AI Employees -> LLM service` and add an LLM service.
+
+Example configuration:
+
+| Setting | Example |
+| --- | --- |
+| Provider | OpenAI (completions) |
+| Title | HY-MT Local |
+| Base URL | `http://127.0.0.1:8000/v1` |
+| API Key | If llama-server has no authentication, use a placeholder such as `dummy`. |
+| Enabled Models | Select `tencent/HY-MT1.5-1.8B-GGUF:Q4_K_M`, or enter the actual model name. |
+
+After configuration, use `Test flight` to verify the model.
+
+:::info{title=Tip}
+If NocoBase runs in Docker, `127.0.0.1` points to the container itself and may not access the host service. Use the host IP, container network address, or `host.docker.internal`.
+:::
+
+## Configure Lina's Dedicated Model
+
+Go to `System Settings -> AI Employees -> AI employees`, open Lina, and switch to `Model settings`.
+
+1. Enable `Enable dedicated model configuration`.
+2. Select the HY-MT local model in `Models`.
+3. Save the configuration.
+
+After this, Lina uses this model for localization translation tasks, preventing users or tasks from switching to general chat models.
+
+For details, see [Configure AI Employee Models](/ai-employees/features/model-settings).
+
+## Configure Translation Concurrency
+
+Localization translation task concurrency is controlled by `AI_LOCALIZATION_CONCURRENCY`:
+
+```bash
+AI_LOCALIZATION_CONCURRENCY=10
+```
+
+Rules:
+
+- Default: `10`
+- Minimum: `1`
+- Maximum: `20`
+- Values outside the range use the default
+
+The best concurrency depends on CPU, GPU, memory, model quantization, and `llama-server -np`. If the default concurrency causes issues:
+
+1. Start with `AI_LOCALIZATION_CONCURRENCY=1` and verify single-entry translation.
+2. Set both `llama-server -np` and `AI_LOCALIZATION_CONCURRENCY` to `2` or `4`.
+3. Observe response time, CPU/GPU usage, and task progress.
+4. Increase concurrency gradually only if stable.
+
+:::warning{title=Note}
+Do not set concurrency too high at the beginning. If concurrency exceeds actual model capacity, tasks may become slower due to queuing, timeout, or service stalls.
+:::
+
+## Execute Localization Translation
+
+Go to `System Management -> Localization Management`.
+
+1. Switch to the target language.
+2. Click `Synchronize` to ensure entries are synchronized.
+3. Click Lina's avatar.
+4. Choose a task scope:
+   - `Incremental translation`: translate entries without translations.
+   - `Selected translation`: translate selected entries in the table.
+   - `Full translation`: translate all entries in the current language.
+5. Check entry count, provider, and model in the confirmation dialog.
+6. Confirm to create the async task.
+7. Wait for completion, review translations, and publish.
+
+Start with `Selected translation` for a few entries to verify output style and speed before running incremental or full translation.
+
+## How Lina Builds Translation Requests
+
+Lina builds requests from entries and reference translations. For short entries, existing references are used to improve consistency:
+
+- Built-in entries prefer Chinese translations as references.
+- Non-built-in entries prefer the system default language as references.
+- If an English reference exists, English is used as source text.
+- Translation results are written to the target language but are not published automatically.
+
+Prompt semantics are similar to:
+
+```text
+Refer to the following translation:
+{source_term} is translated as {target_term}
+
+Translate the following text into {target_language}. Output only the translated result without any additional explanation:
+
+{source_text}
+```
+
+## Troubleshooting
+
+### No progress after creating a task
+
+Check whether `llama-server` received requests. View service logs or call `/v1/chat/completions` with `curl`.
+
+If the model receives requests but does not return, reduce:
+
+- `AI_LOCALIZATION_CONCURRENCY`
+- `llama-server -np`
+- `llama-server -c`
+
+### The model returns explanations instead of translations
+
+Local translation models are usually more stable than general chat models. If explanations still appear, test the same prompt with `curl` first to verify the model's output style.
+
+You can also translate shorter entries first or reduce sampling parameters such as temperature.
+
+### NocoBase cannot connect to the model service
+
+Check:
+
+- Whether Base URL includes `/v1`.
+- Whether the NocoBase runtime environment can access the address.
+- Whether firewall or container networking blocks the port.
+- Whether `llama-server` is still running.
+
+## Review Before Publishing
+
+After AI translation finishes, review before publishing:
+
+- Filter by module and check short entries such as menus, buttons, field names, and statuses.
+- Check variables, placeholders, HTML tags, and formatting symbols.
+- Check key business terminology consistency.
+- If built-in entry translations are overwritten, resynchronize in Localization Management and select `Reset system built-in entry translations` to restore defaults. To contribute default translations for the system and official plugins, see [Translation Contribution](/get-started/translations).
+- Publish in a test environment first, then sync to production.
+
+## References
+
+- [tencent/HY-MT1.5-1.8B-GGUF](https://huggingface.co/tencent/HY-MT1.5-1.8B-GGUF)
+- [llama-server documentation](https://www.mintlify.com/ggml-org/llama.cpp/inference/server)
+- [Lina: Localization Engineer](/ai-employees/built-in/lina)

package/dist/ai/docs/nocobase/ai-employees/workflow/nodes/employee/configuration.md

@@ -18,7 +18,7 @@ You can refer to the following documents:
 
 - [Workflow](/workflow)
 - [Configure LLM Service](/ai-employees/features/llm-service)
-- [Built-in AI Employees](/ai-employees/features/built-in-employee)
+- [Built-in AI Employees](/ai-employees/built-in/)
 - [New AI Employee](/ai-employees/features/new-ai-employees)
 
 ### Task

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

@@ -41,6 +41,13 @@ Dynamic commands with request bodies support:
 
 `--body` and `--body-file` are mutually exclusive.
 
+Dynamic API commands also support:
+
+- `--env`, `-e`: CLI env name to send the request to; when omitted, the current env is used
+- `--yes`, `-y`: When an explicitly passed `--env` targets a different env than the current env, skip the interactive confirmation prompt
+
+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 env update`](../env/update.md)

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

@@ -32,6 +32,7 @@ nb api resource <command>
 | `--api-base-url` | string | NocoBase API URL, for example `http://localhost:13000/api` |
 | `--verbose` | boolean | Show detailed progress |
 | `--env`, `-e` | string | Env name |
+| `--yes`, `-y` | boolean | When an explicitly passed `--env` targets a different env than the current env, skip the interactive confirmation prompt |
 | `--role` | string | Role override sent as the `X-Role` request header |
 | `--token`, `-t` | string | API key override |
 | `--json-output`, `-j` / `--no-json-output` | boolean | Whether to output raw JSON; enabled by default |
@@ -49,6 +50,8 @@ nb api resource create --resource users --values '{"nickname":"Ada"}'
 nb api resource list --resource posts.comments --source-id 1 --fields id --fields content
 ```
 
+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 api`](../index.md)

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

@@ -6,7 +6,7 @@ keywords: "nb app down,NocoBase CLI,cleanup,remove containers,storage"
 
 # nb app down
 
-Stop and clean up local runtime resources for a selected env. Storage data and env configuration are kept by default; pass `--all --yes` explicitly to delete everything.
+Stop and clean up local runtime resources for a selected env. Storage data and env configuration are kept by default; pass `--all --force` explicitly to delete everything.
 
 ## Usage
 
@@ -20,16 +20,20 @@ nb app down [flags]
 | --- | --- | --- |
 | `--env`, `-e` | string | CLI env name to clean up; uses the current env if omitted |
 | `--all` | boolean | Delete all content for the env, including storage data and saved env configuration |
-| `--yes`, `-y` | boolean | Skip destructive-operation confirmation; usually used with `--all` |
+| `--yes`, `-y` | boolean | When an explicitly passed `--env` targets a different env than the current env, skip the interactive confirmation prompt |
+| `--force`, `-f` | boolean | Force destructive cleanup, such as `--all` or other high-risk cleanup in non-interactive mode |
 | `--verbose` | boolean | Show underlying stop and cleanup command output |
 
 ## Examples
 
 ```bash
 nb app down --env app1
-nb app down --env app1 --all --yes
+nb app down --env app1 --all --force
+nb app down --env app1 --force
 ```
 
+`--yes` only skips the interactive confirmation when an explicitly passed `--env` targets a different env than the current env. `--force` is for actually forcing destructive cleanup, such as `--all` or other high-risk cleanup in non-interactive mode.
+
 ## Related Commands
 
 - [`nb app stop`](./stop.md)

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

@@ -32,7 +32,7 @@ nb app start --env app1
 nb app restart --env app1
 nb app logs --env app1
 nb app stop --env app1
-nb app down --env app1 --all --yes
+nb app down --env app1 --all --force
 ```
 
 ## Related Commands

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

@@ -19,6 +19,7 @@ nb app logs [flags]
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `--env`, `-e` | string | CLI env name to view logs for; 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 |
 | `--tail` | integer | Number of recent log lines to show before following, default `100` |
 | `--follow`, `-f` / `--no-follow` | boolean | Whether to keep following new log output |
 
@@ -31,6 +32,8 @@ nb app logs --env app1 --tail 200
 nb app logs --env app1 --no-follow
 ```
 
+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 start`](./start.md)

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

@@ -19,6 +19,7 @@ nb app restart [flags]
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `--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 |
 | `--quickstart` | boolean | Start the app in quickstart mode after stopping |
 | `--port`, `-p` | string | Override the `appPort` saved in env config |
 | `--daemon`, `-d` / `--no-daemon` | boolean | Whether to run in daemon mode after stopping; enabled by default |
@@ -36,9 +37,12 @@ nb app restart --env local --port 12000
 nb app restart --env local --no-daemon
 nb app restart --env local --instances 2
 nb app restart --env local --launch-mode pm2
+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.
+
 ## Related Commands
 
 - [`nb app start`](./start.md)

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

@@ -19,6 +19,7 @@ nb app start [flags]
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `--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 |
 | `--quickstart` | boolean | Start the app in quickstart mode |
 | `--port`, `-p` | string | Override the `appPort` saved in env config |
 | `--daemon`, `-d` / `--no-daemon` | boolean | Whether to run in daemon mode; enabled by default |
@@ -37,9 +38,12 @@ nb app start --env local --daemon
 nb app start --env local --no-daemon
 nb app start --env local --instances 2
 nb app start --env local --launch-mode pm2
+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.
+
 ## Related Commands
 
 - [`nb app stop`](./stop.md)

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

@@ -19,6 +19,7 @@ nb app stop [flags]
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `--env`, `-e` | string | CLI env name to stop; 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 |
 | `--verbose` | boolean | Show underlying local or Docker command output |
 
 ## Examples
@@ -30,6 +31,8 @@ nb app stop --env local --verbose
 nb app stop --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.
+
 ## Related Commands
 
 - [`nb app start`](./start.md)

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

@@ -19,7 +19,9 @@ nb app upgrade [flags]
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `--env`, `-e` | string | CLI env name to upgrade; 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 |
 | `--skip-code-update`, `-s` | boolean | Restart from the saved local source or Docker image without downloading updates |
+| `--version` | string | Override the saved `downloadVersion`; when the upgrade succeeds, the new version is written back to the env config |
 | `--verbose` | boolean | Show underlying update and restart command output |
 
 ## Examples
@@ -28,10 +30,13 @@ nb app upgrade [flags]
 nb app upgrade
 nb app upgrade --env local
 nb app upgrade --env local -s
+nb app upgrade --env local --version beta
 nb app upgrade --env local --verbose
 nb app upgrade --env local-docker -s
 ```
 
+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 source download`](../source/download.md)

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

@@ -1,13 +1,20 @@
 ---
 title: "nb env add"
-description: "nb env add command reference: save a NocoBase API URL and authentication method, then switch to it as the current env."
-keywords: "nb env add,NocoBase CLI,add environment,API URL,authentication"
+description: "nb env add command reference: save a NocoBase API URL and authentication method, then switch to that env."
+keywords: "nb env add,NocoBase CLI,add environment,API Base URL,authentication"
 ---
 
 # nb env add
 
 Save a named NocoBase API endpoint and switch the CLI to use that env. When `oauth` authentication is selected, [`nb env auth`](./auth.md) is started automatically.
 
+This command does two things:
+
+- Save the env configuration
+- Switch the current env to the newly added env
+
+When session mode is enabled for the current shell or runtime, it updates the session `current env`. It also updates the global `last env` as the fallback for shells or runtimes without session mode.
+
 ## Usage
 
 ```bash
@@ -18,7 +25,7 @@ nb env add [name] [flags]
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `[name]` | string | Env name; prompted in TTY when omitted, required in non-TTY mode |
+| `[name]` | string | Environment name to save; prompted in TTY when omitted, required in non-TTY mode |
 | `--verbose` | boolean | Show detailed progress when writing config |
 | `--locale` | string | CLI prompt language: `en-US` or `zh-CN` |
 | `--api-base-url`, `-u` | string | NocoBase API URL, including the `/api` prefix |
@@ -37,5 +44,6 @@ nb env add local --api-base-url http://localhost:13000/api --auth-type token --a
 ## Related Commands
 
 - [`nb env auth`](./auth.md)
+- [`nb env current`](./current.md)
 - [`nb env update`](./update.md)
 - [`nb env list`](./list.md)

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

@@ -18,7 +18,7 @@ nb env auth [name]
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `[name]` | string | Env name; uses the current env if omitted |
+| `[name]` | string | Configured environment name to sign in to; uses the current env if omitted |
 
 ## Notes
 

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

@@ -0,0 +1,29 @@
+---
+title: "nb env current"
+description: "nb env current command reference: show the currently effective NocoBase CLI env."
+keywords: "nb env current,NocoBase CLI,current env,session env"
+---
+
+# nb env current
+
+Show the name of the currently effective env.
+
+By default, this command first reads the session env for the current `NB_SESSION_ID`. If session mode is not enabled for the current shell or runtime, it falls back to the global `last env`.
+
+## Usage
+
+```bash
+nb env current
+```
+
+## Examples
+
+```bash
+nb env current
+```
+
+## Related Commands
+
+- [`nb env use`](./use.md)
+- [`nb env status`](./status.md)
+- [`nb session setup`](../session/setup.md)

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

@@ -1,13 +1,18 @@
 ---
 title: "nb env"
-description: "nb env command reference: manage NocoBase CLI envs, including add, refresh, inspect, switch, authenticate, and remove."
-keywords: "nb env,NocoBase CLI,environment management,env,authentication,OpenAPI"
+description: "nb env command reference: manage NocoBase CLI envs, including add, inspect current env, check status, switch, authenticate, and remove."
+keywords: "nb env,NocoBase CLI,environment management,env,current env,authentication,OpenAPI"
 ---
 
 # nb env
 
 Manage saved NocoBase CLI envs. An env stores API URL, authentication info, local app paths, database config, and runtime command cache.
 
+In the current model, the CLI separates two concepts:
+
+- `current env`: the env currently used by the active shell or agent runtime, isolated by `NB_SESSION_ID` when available
+- `last env`: the globally last-used env, used as a fallback when session mode is not enabled
+
 ## Usage
 
 ```bash
@@ -18,9 +23,11 @@ nb env <command>
 
 | Command | Description |
 | --- | --- |
-| [`nb env add`](./add.md) | Save a NocoBase API endpoint and switch to it as the current env |
+| [`nb env add`](./add.md) | Save a NocoBase API endpoint and switch to that env |
+| [`nb env current`](./current.md) | Show the currently effective env |
 | [`nb env update`](./update.md) | Refresh OpenAPI Schema and runtime command cache from the app |
-| [`nb env list`](./list.md) | List configured envs and API authentication status |
+| [`nb env list`](./list.md) | List configured envs |
+| [`nb env status`](./status.md) | Show status for the current env, one env, or all envs |
 | [`nb env info`](./info.md) | Show details for a single env |
 | [`nb env remove`](./remove.md) | Remove env configuration |
 | [`nb env auth`](./auth.md) | Run OAuth login for a saved env |
@@ -30,15 +37,26 @@ nb env <command>
 
 ```bash
 nb env add app1 --api-base-url http://localhost:13000/api
+nb env current
 nb env list
+nb env status
 nb env info app1
 nb env update app1
 nb env use app1
 nb env auth app1
 ```
 
+## Session mode
+
+Session mode is the default recommendation. It keeps `current env` isolated across different terminals, shells, and agent runtimes, so parallel work does not affect each other.
+
+When session mode is not enabled, `nb env use` updates the global `last env`, and other sessions without isolation may also be affected.
+
+See [`nb session setup`](../session/setup.md) to enable it.
+
 ## Related Commands
 
 - [`nb init`](../init.md)
 - [`nb api`](../api/index.md)
 - [`nb app`](../app/index.md)
+- [`nb session`](../session/index.md)

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

@@ -18,20 +18,16 @@ nb env info [name] [flags]
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `[name]` | string | CLI env name to inspect; uses the current env if omitted |
-| `--env`, `-e` | string | CLI env name to inspect; alternative to the positional argument |
+| `[name]` | string | Configured environment name to inspect; uses the current env if omitted |
 | `--json` | boolean | Output JSON |
 | `--show-secrets` | boolean | Show tokens, passwords, and other secrets in plain text |
 
-If both `[name]` and `--env` are passed, they must match.
-
 ## Examples
 
 ```bash
 nb env info app1
 nb env info app1 --json
 nb env info app1 --show-secrets
-nb env info --env app1
 ```
 
 ## Related Commands

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

@@ -1,12 +1,14 @@
 ---
 title: "nb env list"
-description: "nb env list command reference: list configured NocoBase CLI envs and API authentication status."
-keywords: "nb env list,NocoBase CLI,environment list,authentication status"
+description: "nb env list command reference: list configured NocoBase CLI envs."
+keywords: "nb env list,NocoBase CLI,environment list,API Base URL"
 ---
 
 # nb env list
 
-List all configured envs and check app API authentication status with saved Token/OAuth credentials.
+List all configured envs.
+
+This command only shows saved configuration. Use [`nb env status`](./status.md) when you want to check current runtime or API status.
 
 ## Usage
 
@@ -16,9 +18,11 @@ nb env list
 
 ## Output
 
-The output table includes the current env marker, name, type, App Status, URL, authentication type, and runtime version.
+The output table includes the current env marker, name, type, `API Base URL`, authentication type, and runtime version.
 
-`App Status` is the result of accessing the app API with the saved auth info, such as `ok`, `auth failed`, `unreachable`, or `unconfigured`. Use [`nb db ps`](../db/ps.md) to inspect database runtime status.
+- `Current` marks the currently effective env with `*`
+- `API Base URL` shows the saved raw API address
+- `Runtime` shows cached runtime version information
 
 ## Examples
 
@@ -28,6 +32,7 @@ nb env list
 
 ## Related Commands
 
+- [`nb env current`](./current.md)
+- [`nb env status`](./status.md)
 - [`nb env info`](./info.md)
 - [`nb env use`](./use.md)
-- [`nb db ps`](../db/ps.md)

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

@@ -8,6 +8,8 @@ keywords: "nb env remove,NocoBase CLI,delete environment,remove config"
 
 Remove a configured env. This command only deletes CLI env configuration; use [`nb app down`](../app/down.md) to clean up local apps, containers, and storage.
 
+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.
+
 ## Usage
 
 ```bash
@@ -18,7 +20,7 @@ nb env remove <name> [flags]
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `<name>` | string | Env name to remove |
+| `<name>` | string | Configured environment name to remove |
 | `--force`, `-f` | boolean | Skip confirmation and delete directly |
 | `--verbose` | boolean | Show detailed progress |
 
@@ -32,4 +34,5 @@ nb env remove staging -f
 ## Related Commands
 
 - [`nb app down`](../app/down.md)
+- [`nb env current`](./current.md)
 - [`nb env list`](./list.md)