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 and prepare the database first, while delaying dependency download, 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>/
├── .nb/      # CLI metadata for this env, such as hooks.mjs
├── source/   # Default directory for app source code or downloaded content
├── storage/  # Runtime data directory
└── .env      # Optional app environment variable file

Typically:

• .nb/ stores CLI-managed metadata. A script passed with --hook-script is copied to <app-path>/.nb/hooks.mjs, so later nb app upgrade and local source restore can reuse it
• 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. Pay special attention during upgrades: the source/ directory will be deleted and downloaded again, so do not put files you need to keep here
• 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

:::warning Notes

• --ui cannot be used together with --yes
• --ui also cannot be used together with --resume
• --ui-host and --ui-port can only be used together with --ui
• --skip-auth cannot be used together with --access-token or --token

:::

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

Extend the install flow with a hook script

If you need to prepare extra content during installation, pass a local ESM module with --hook-script:

nb init --env app1 --yes --source git --hook-script ./hooks.mjs

The CLI copies this file to <app-path>/.nb/hooks.mjs and saves hookScript: ".nb/hooks.mjs" in the env config. Later nb app start, nb app restart, and nb app upgrade reuse it from that location.

The hook file must default-export an object. Implement only the methods you need:

export default {
  beforeDependencyInstall: async (context) => {
    // Runs after git clone / npm scaffold and before yarn install.
  },
  beforeAppInstall: async (context) => {
    // Runs before the app-level install or upgrade command.
  },
  afterAppStart: async (context) => {
    // Runs after the app actually starts and passes the health check.
  },
};

• beforeDependencyInstall only applies to npm/Git source and runs right before the real yarn install; Docker source does not run it
• beforeAppInstall runs before app-level install or upgrade commands, and applies to npm/Git/Docker source
• afterAppStart runs after the app actually starts and passes __health_check; nb app start, nb app restart, and nb app upgrade may all trigger it

--prepare-only only saves the env config and copies the hook file. It does not execute hooks. When you later run nb app start for the first time, the CLI runs the first-install hooks with context.phase set to init and context.command set to app:start.

context includes lifecycle information such as phase, command, source, version, appPath, sourcePath, storagePath, hookScript, and envConfig. If a hook throws, the current CLI command fails. Because afterAppStart can run repeatedly during start, restart, and upgrade flows, keep it idempotent.

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