docs/docs/en/quickstart/installation/cli.md
After NocoBase 2.1.0, the official CLI-based installation and management method is provided. You can use it to complete installation, connection, upgrade and daily maintenance, and you can also prepare a connectable and operable environment for AI Agent.
Only executed when installing the CLI for the first time.
First install the CLI globally:
npm install -g @nocobase/cli@beta
nb --version
:::tip It is recommended to enable session mode first
If you will open multiple terminals or shells at the same time, or want the AI Agent to operate in parallel with yourself, it is recommended by default to execute nb session setup first. In this way, each session can maintain its own current env and will not easily affect each other.
nb session setup
:::
If you plan to use the Chinese interface for a long time, it is usually enough to set the locale first:
nb config set locale zh-CN
The CLI checks for self-updates by default. You can adjust the update strategy according to your own habits:
prompt: Prompt when a new version is foundauto: automatic updateoff: Turn off automatic updatesnb config set update.policy prompt
nb config set update.policy auto
nb config set update.policy off
If you are going to deploy NocoBase to the server and want to open the nb init --ui wizard from a remote browser, it is recommended to first change the CLI's default host to the current server IP:
nb config set default-ui-host <server-ip>
nb config set default-api-host <server-ip>
Replace <server-ip> with the actual IP of the current server that is accessible to you.
nb config is the global configuration of the CLI. Usually it only needs to be set once, and these default values will be automatically used when running nb init --ui again later, so there is no need to repeat the configuration every time.
Generally speaking:
default-ui-host is used for the default listening address of nb init --ui when starting the wizard pagedefault-api-host for the API address generated by default on new installationsIf deployed on a server, both values should usually be changed to IPs accessible to the current server, rather than continuing to use the default local address.
:::warning This is only an installation wizard or temporary access method, not a recommended entrance for production environments.
Set default-ui-host / default-api-host to the server IP, mainly so that you can open nb init --ui from a remote browser, or temporarily verify whether the service is accessible after the installation is completed.
This does not mean that the production environment should use IP + port to provide external services for a long time. When formally deploying, it is still recommended to use a domain name and provide unified access through a reverse proxy such as Nginx or Caddy, and then enable HTTPS.
:::
This is the default recommended entry. You just need to run:
nb init --ui
If you want to specify a fixed port for the wizard page, you can add --ui-port directly, for example:
nb init --ui --ui-port 3000
The wizard will take you step by step to complete the configuration required for installation or connection based on the current scenario.
If you are more comfortable typing step by step in the terminal, you can run directly:
nb init
If you are running in a script, CI/CD, or other non-interactive environment, just use --yes. In this mode, --env must be passed explicitly, and parameters not explicitly specified will be processed by default values.
The shortest default way to write it is:
nb init --yes --env app1
Specific to common combinations such as different installation sources, version selection, basic certification, CI/CD connection to existing applications, and database naming, just look at [nb init command reference example](../../api/cli/init.md# example).
--env is the environment name in the CLI. Generally speaking, the next thing you do after the installation is completed revolves around this env.
It is usually recommended to confirm these 3 things first:
IP + port directly?If you have just installed a local application using nb init --env app1, you can view the full path through nb env info app1 --field app.appPath.
By default, the CLI organizes local files under app-path according to the following convention:
<app-path>/
├── source/ # 应用源码或下载内容对应的默认目录
├── storage/ # 运行时数据目录
└── .env # 可选的应用环境变量文件
Generally speaking:
source/ mainly corresponds to the local application directory of npm/Git env. For Docker env, the CLI will also retain this set of default path derivation, but most of the time you don't need to care about it manuallystorage/ is used to store runtime data, such as built-in database data, plug-ins, logs, etc..env is an optional application environment variable file. Only when you need to customize environment variables, you need to add it in <app-path>/.env; if this file exists, Docker, npm and Git installation sources will read it by default.See nb init Command Reference for a more complete description.
If you have just finished the installation and want to verify the installation results first, there is usually no problem in opening the page with IP + port.
But if this env is going to officially provide services to the outside world, special attention needs to be paid:
nb init --ui itself is just a temporary page of the installation wizard, used to complete the installation or initialization, and is not the official external service entrance of the application.nb init is completed, the IP + port currently exposed by the application is more suitable for the debugging phase, verification phase or temporary access to the intranethttp://IP:portIn other words, default-ui-host and default-api-host are just to make the installation wizard and default address generation more convenient, and do not represent the access entrance to the final production environment.
If this env is ready to be officially launched, it is recommended that "connect to the reverse proxy and enable HTTPS" as the next step after the installation is completed, rather than an optional optimization item.
If you are ready to proceed with formal deployment now, it is recommended to start with production environment deployment, and then continue to look at the reverse proxy configuration of Nginx or Caddy as needed.
You can first confirm whether this env has been saved successfully:
nb env current
nb env list
nb env status
nb env info app1
nb env info app1 --json
If you want to continue with the subsequent operations after installation, you can click on the following index to look down:
| I want... | Where to look |
|---|---|
| If you are ready to make this env officially open to the outside world, connect it to the production environment reverse proxy, and use the domain name and HTTPS to expose the service. | Nginx / Caddy. |
| Confirm whether the env is saved successfully, check which env is currently used, and switch between multiple envs. | nb env, Multi-environment management. |
| Start, stop, restart the application, view logs, or continue to upgrade the application. | nb app, Manage Application. |
| Check database connections, view built-in database status, or troubleshoot database container issues. | nb db. |
| View installed plug-ins, enable or disable plug-ins. | nb plugin. |
| Activate commercial authorization, check authorization status, and synchronize commercial plug-ins. | nb license. |
| Manage local source code projects, such as downloading source code, starting development mode, building or testing. This is typically used with npm/Git env. | nb source. |
If you have just installed a local application, you can usually run these commands first:
nb env use app1
nb app start
nb app logs
nb plugin list
If you maintain multiple envs at the same time, see Multiple Environment Management for subsequent switching and status viewing methods.
If you want to upgrade the application later, just look at Manage Application and nb app upgrade Command Reference.