#nb init

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

nb init [flags]

#Interactive modes

nb init supports three interactive modes:

• 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

--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.

#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:

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.

#Preparing an env without installing the app yet

--prepare-only is intended for flows where the env should be prepared first, then the license is activated, and only after that the app is installed and started.

If you want to save the env config, prepare the source files or image, and get the database ready first, but delay the actual app installation and first startup, you can use:

nb init --env app1 --prepare-only
nb init --env app1 --prepare-only --ui
nb init --env app1 --prepare-only --yes

This mode is available for local installation flows, including the --ui wizard. It is not available for remote connection flows. It saves the env as a prepared env, so you can continue later with a flow such as:

nb license activate --env app1
nb app start --env app1

nb app start will then complete the first installation and switch the env from the prepared state to the normal installed state.

#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:

<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

#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:

#Parameters

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

#Connecting to an existing app

#Basic parameters for local installation

#Database parameters

#Download and source code parameters

#Examples

The most common usage patterns are as follows.

#Complete the setup step by step in the terminal

nb init

#Open the local browser wizard

nb init --ui
nb init --ui --ui-port 3000

#Prepare first, then activate the license and start later

nb init --env app1 --prepare-only
nb license activate --env app1
nb app start --env app1

#Install a new local app in non-interactive mode

If you do not specify --source, Docker is usually used as the install source.

nb init --env app1 --yes
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 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:

nb init --env app1 --yes --auth-type basic

If you also want to customize the admin account, you can write it like this:

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.

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:

nb init --env app1 --yes \
  --db-dialect postgres \
  --db-schema public \
  --db-table-prefix nb_ \
  --db-underscored

#Continue the last interrupted initialization

nb init --env app1 --resume

#Show detailed logs when troubleshooting

nb init --env app1 --yes --source docker --version latest --verbose

#Related commands

• nb env add
• nb env auth
• nb source download