# Nocobase Env Manage

> NocoBase 2 only; never use in a NocoBase 3 project. Use when users need NocoBase bootstrap, runtime lifecycle, CLI maintenance, and skills maintenance with nb CLI only.

- Skill: `nocobase/nocobase-env-manage` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds add nocobase/nocobase-env-manage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nocobase/nocobase-env-manage/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: nocobase (https://skillmd.com/u/nocobase)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/nocobase/nocobase-env-manage

---


# Goal

Use `nb` CLI only to complete NocoBase bootstrap, lifecycle, and maintenance actions.

# Scope

- Bootstrap or connect NocoBase environments through `nb init`.
- Manage saved CLI environments through `nb env`.
- Manage app runtime lifecycle through `nb app`.
- Check and update the `nb` CLI through `nb self`.
- Check and update installed NocoBase skills through `nb skills`.
- Inspect built-in database runtime only when it helps verify or diagnose the selected environment.

# Non-Goals

- Do not implement NocoBase business models, UI pages, workflows, or plugins.
- Do not run repository-local helper scripts for install or lifecycle work.
- Do not bypass the official install guide when the user provides an official install URL.

# Hard Rules

- Only run direct `nb` commands.
- Never run local scripts (`*.mjs`, `*.ps1`, `*.sh`).
- Never use template-driven install flows.
- For `task=install`, if the user provides an official NocoBase install or quick-start URL, read that URL first and follow the official guide flow. Ignore local install command tables when they conflict with the official guide.
- For `task=install`, use `nb init --ui` as the guided install entrypoint unless the current official guide says otherwise.
- `nb init --ui` is not a completion condition. Keep following CLI output until setup reaches a finished state or the CLI exits with an actionable failure.
- When executing `nb init --ui`, use a CLI timeout of 30 minutes and do not interrupt the command before it exits.
- If install flow exposes a URL that cannot be opened because the agent is running in a sandboxed environment, explicitly ask to elevate/open outside the sandbox; if the user refuses, provide the URL directly to the user.
- Never proactively fill install/setup forms on the user's behalf; only surface the URL, explain the next step, and let the user complete the form.
- If the CLI prints a continuation or recovery command, especially `nb init ... --resume ...`, execute that exact direct `nb` command unless it is destructive or conflicts with the user's latest instruction.
- Use `nb app <command>` for runtime lifecycle operations.
- Use `nb self <command>` only for CLI self-check/update.
- Use `nb skills <command>` only for installed skills check/update.
- Do not execute ambiguous status/check/update/upgrade intents until the target is clear: app/runtime/env, CLI, or skills.
- Do not add extra precheck gates before executing user-requested `nb` commands.
- Prefer executing user-requested runtime commands first; use `nb --help` when user asks for diagnostics/help output or command discovery is needed.
- Surface CLI outputs and hints directly to users.

# Supported Tasks

- `install`
- `app-manage`
- `upgrade`
- `stop`
- `start`
- `restart`
- `logs`
- `down`
- `self-check`
- `self-update`
- `skills-check`
- `skills-update`

# Input Contract

| Input | Required | Default | Notes |
|---|---|---|---|
| `task` | yes | inferred | one of `install/app-manage/upgrade/start/stop/restart/logs/down/self-check/self-update/skills-check/skills-update` |
| `app_env_action` | for `task=app-manage` | `list` | one of `add/use/current/list/remove`; `current` is derived from list output |
| `app_env_name` | conditional | none | required for `add/use/remove` |
| `app_base_url` | conditional | none | required for `add`; accepts URL with or without `/api` (auto-normalized) |
| `cli_auth_mode` | for env add | `oauth` | one of `oauth/token` |
| `app_token` | conditional | none | required when `cli_auth_mode=token` |
| `runtime_env_name` | optional for `upgrade/start/stop/restart/logs/down` | current env | explicit runtime env name |

# Execution Policy

- Execute the target `nb` command directly.
- Intent clarification is not a precheck gate. If the user's wording is ambiguous, ask one concise clarification question before running any command.
- Install routing:
  - when the user provides an official NocoBase install or quick-start URL, read it first and follow that official flow, ignoring local install command tables on conflict
  - otherwise use `nb init --ui` as the guided install entrypoint
- For `task=install`, treat `nb init --ui` as a long-running interactive command:
  - set command timeout to 30 minutes
  - do not interrupt/wait-short/poll in a way that aborts the CLI before completion
  - do not stop just because a local setup URL was printed
  - continue until the CLI reports readiness, workspace completion, or an explicit failure
- If `nb init --ui` prints a local URL and browser open fails in sandbox, first ask to elevate/open outside sandbox; if that is declined, surface the URL so the user can open it manually.
- During install/setup flows, never submit or fill web forms for the user; provide instructions only.
- If install fails and CLI prints a resume command, run the printed `nb init ... --resume ...` command next. Do not rerun a fresh setup unless the CLI asks for it or the user explicitly requests it.
- Do not run separate preflight checks unless the user explicitly asks for diagnostics.
- If command fails, return key CLI output lines and suggested next commands from CLI output.
- For environment query intents (`list/current`), use fast path:
  - first command: `nb env list`
  - current env is the row marked with leading `*`
- For environment query intents, keep command set minimal:
  - `nb env --help` / `nb env list --help` are available when command discovery is needed.
- For environment details and post-install verification, prefer `nb env info [name]` and inspect app/database/API status.
- For `env add`, normalize API base URL before execution:
  - if URL already ends with `/api`, keep as-is
  - otherwise append `/api`
- For CLI maintenance, execute the exact command requested by task:
  - `self-check` -> `nb self check --json`
  - `self-update` -> `nb self update --yes`
- For skills maintenance, execute the exact command requested by task:
  - `skills-check` -> `nb skills check --json`
  - `skills-update` -> `nb skills update --yes`
- Preserve JSON check output from `nb self check --json` and `nb skills check --json` when reporting results.
- After `self-update` or `skills-update`, run the matching check command as readback unless the CLI says the shell/session must be restarted first.

# Intent Disambiguation

When the user says generic status/check/update/upgrade wording without an explicit target, do not infer a command.

Ambiguous examples include:

- `检查状态`
- `检查一下`
- `健康检查`
- `诊断一下`
- `检查更新`
- `升级`
- `更新`
- `修复`

Ask which target they mean before executing:

- app/runtime/env: `nb env list`, `nb env info`, or `nb app ...`
- CLI: `nb self check --json` or `nb self update --yes`
- skills: `nb skills check --json` or `nb skills update --yes`

Clarification template:

- `你想检查/更新哪一类：NocoBase app/runtime/env、nb CLI，还是已安装 skills？`

Treat these as clear targets:

- explicit command text, such as `nb self check --json`
- exact task names, such as `self-check` or `skills-update`
- wording that names the target, such as `检查 nb CLI`, `更新已安装 skills`, `升级 NocoBase app`, `检查当前环境`

# Env Resolution Rule

For `upgrade/start/stop/restart/logs/down`:

1. If `runtime_env_name` is provided, pass `--env <env>`.
2. If no env is provided, run command without `--env` and follow CLI response.
3. If CLI reports no env configured, surface that message and ask user whether to create a new app or add an env.

# Workflow

1. Infer the requested task and any explicit env name, API base URL, auth mode, or official install URL.
2. If status/check/update/upgrade intent could target app/runtime/env, CLI, or skills, ask for clarification before executing.
3. For install requests with an official URL, read the URL first and follow the official guide flow.
4. Execute only direct `nb` commands from the current command map or from CLI-provided continuation hints.
5. Keep interactive install commands alive until completion, actionable failure, or user interruption.
6. Verify with `nb env list`, `nb env info`, and app/database status when relevant.
7. For CLI/skills maintenance, use the `nb self` / `nb skills` commands exactly as mapped.
8. Report executed commands, important CLI output, and the next concrete action.

# Command Map

## install

```bash
nb init --ui
nb env list
nb env info
```

Install is done only when the CLI reports readiness/completion, such as `NocoBase is ready ...` and `Workspace init finished`, or equivalent success output from the current official guide.

## app-manage

### list/current

```bash
nb env list
nb env info [name]
```

For `current`, derive from the row marked with leading `*` in `nb env list` output. Do not call `nb env current`.

When CLI returns:

- `No envs configured.`
- `Run 'nb env add <name> --api-base-url <url>' to add one.`

surface this message directly and ask whether to create a new app (`nb init --ui`) or add env.

### add (oauth)

```bash
nb env add <name> --api-base-url <url> --auth-type oauth
```

`<url>` uses normalized value (auto-append `/api` when missing).

### add (token)

```bash
nb env add <name> --api-base-url <url> --auth-type token --access-token <token>
```

`<url>` uses normalized value (auto-append `/api` when missing).

### use

```bash
nb env use <name>
```

### remove

```bash
nb env remove <name>
```

Write actions (`add/use/remove`) must always be followed by:

```bash
nb env list
```

Use `nb env remove <name> -f` only after explicit user confirmation.

### auth

```bash
nb env auth [name]
```

## upgrade

```bash
nb app upgrade [--env <env>]
```

Optional:

```bash
nb app upgrade [--env <env>] --skip-code-update
```

## stop

```bash
nb app stop [--env <env>]
```

## start

```bash
nb app start [--env <env>]
```

Optional:

```bash
nb app start --env <env> --quickstart
nb app start --env <env> --port <port>
nb app start --env <env> --daemon
nb app start --env <env> --no-daemon
```

## restart

```bash
nb app restart [--env <env>]
```

## logs

```bash
nb app logs [--env <env>] [--tail <lines>] [--no-follow]
```

## down

```bash
nb app down [--env <env>]
```

## self-check

```bash
nb self check --json
```

Use this for `nb` CLI health/version/update checks. No env is required.

## self-update

```bash
nb self update --yes
nb self check --json
```

Run the update command first. Run the check command afterward as readback unless the CLI says a new shell/session is required.

## skills-check

```bash
nb skills check --json
```

Use this for installed NocoBase skills health/version/update checks. No env is required.

## skills-update

```bash
nb skills update --yes
nb skills check --json
```

Run the update command first. Run the check command afterward as readback unless the CLI says a new shell/session is required.

# Safety

- Never run `upgrade` on ambiguous env.
- Ask explicit confirmation before `upgrade` when user intent is not explicit.
- Treat `nb app down` as destructive because it removes runtime containers and saved local app files. Always ask explicit confirmation before running it.
- Never pass `--all` or `--yes` to `nb app down` unless the user explicitly requests those flags.
- Treat `nb self update --yes` and `nb skills update --yes` as allowed update shortcuts only when the user clearly requests CLI or skills update.
- Do not substitute package-manager update commands (`npm`, `pnpm`, `yarn`) for `nb self update --yes` or `nb skills update --yes`.

Confirmation template:

- `Confirm execution: nb app upgrade --env <env>. Reply confirm to continue.`

# Safety Gate

Require explicit user confirmation before:

- ambiguous status/check/update/upgrade intents where the target could be app/runtime/env, CLI, or skills.
- `nb app upgrade` when the target env is ambiguous or the user did not clearly request an upgrade.
- `nb app down` in all cases.
- `nb env remove <name> -f`.
- Any command that includes `--all`, `--yes`, or force-style deletion flags, except exact `nb self update --yes` / `nb skills update --yes` commands when the user clearly requested that update.

# Output Contract

Final response must include:

- selected task
- executed commands
- relevant CLI outputs, including JSON check output and error/hint lines when failed
- normalized API base URL (for `env add`)
- next action

# Reference Loading Map

| Reference | Use When |
|---|---|
| [Usage Guide](references/usage-guide.md) | Mapping user intent to current `nb` commands. |
| [Install Runbook](references/install-runbook.md) | Executing install/bootstrap flows, especially official URL and resume handling. |
| [Upgrade Runbook](references/upgrade-runbook.md) | Upgrading app runtimes with `nb app upgrade`. |
| [Preflight Checklist](references/preflight-checklist.md) | Optional diagnostics when explicitly requested. |
| [Troubleshooting](references/troubleshooting.md) | Recovering from CLI errors and version mismatch symptoms. |

# Verification Checklist

- Install requests with an official URL read and followed that URL first.
- `nb init --ui` was not treated as complete when only a setup URL appeared.
- Any CLI-provided `nb init ... --resume ...` continuation was followed or surfaced with a blocker.
- Runtime lifecycle commands used `nb app ...`.
- Env operations used the final `nb env` syntax.
- Ambiguous status/check/update/upgrade wording was clarified before command execution.
- CLI maintenance used `nb self check --json` or `nb self update --yes`.
- Skills maintenance used `nb skills check --json` or `nb skills update --yes`.
- Maintenance update commands were followed by matching check commands when the CLI allowed it.
- Final readback used `nb env list` and, when relevant, `nb env info`.

# References

- [Usage Guide](references/usage-guide.md)
- [Install Runbook](references/install-runbook.md)
- [Upgrade Runbook](references/upgrade-runbook.md)
- [Preflight Checklist](references/preflight-checklist.md)
- [Troubleshooting](references/troubleshooting.md)