docs/docs/en/api/cli/index.md
NocoBase CLI (nb) is the command-line entry point for NocoBase, used to initialize, connect to, and manage NocoBase applications in a local workspace.
It supports two common initialization paths:
When creating a new local application, nb init can also install or update NocoBase AI coding skills. To skip this step, use --skip-skills.
nb [command]
The root command itself is mainly used to display help and dispatch invocations to command groups or standalone commands.
The following command groups are shown in nb --help:
| Command group | Description |
|---|---|
nb api | Call NocoBase APIs through the CLI. |
nb app | Manage the application runtime: start, stop, restart, logs, and upgrade. |
nb backup | Create backups and download them locally, or restore a local backup file to the target env. |
nb config | Manage CLI default configuration. |
nb db | Manage the built-in database of the selected env. |
nb env | Manage NocoBase project environments, the current env, status, details, and runtime commands. |
nb license | Manage commercial licenses and licensed plugins. |
nb plugin | Manage plugins in the selected NocoBase env. |
nb scaffold | Generate scaffolding for NocoBase plugin development. |
nb self | Check or update NocoBase CLI itself. |
nb session | Configure NB_SESSION_ID so the current env is isolated by shell or agent runtime. |
nb skills | Check or sync NocoBase AI coding skills in the current workspace. |
nb source | Manage local source projects: download, develop, build, and test. |
Standalone commands currently exposed directly by the root command:
| Command | Description |
|---|---|
nb init | Initialize NocoBase so coding agents can connect and work. |
View help for the root command:
nb --help
View help for a command or command group:
nb init --help
nb app --help
nb backup --help
nb config --help
nb api resource --help
nb license --help
Interactive initialization:
nb init
Initialize using a browser form:
nb init --ui
Create a Docker application non-interactively:
nb init --env app1 --yes --source docker --version alpha
Connect to an existing application:
nb env add app1 --api-base-url http://localhost:13000/api
nb env current
nb env status
Resync env status after starting the application:
nb app start -e app1
nb env update app1
Call an API:
nb api resource list --resource users -e app1
View CLI default configuration:
nb config list
nb config get docker.network
View commercial license status:
nb license status -e app1
nb license plugins list -e app1
Create and download a backup:
nb backup create -e app1 --output ./backups
Restore a local backup:
nb backup restore -e app1 --file ./backups/backup_20260520_190408_8397.nbdata --yes --force
The following environment variables affect CLI behavior:
| Variable | Description |
|---|---|
NB_CLI_ROOT | Root directory where the CLI stores .nocobase configuration and local application files. Defaults to the current user's home directory. |
NB_LOCALE | CLI prompt language and local initialization UI language. Supports en-US and zh-CN. |
NB_SESSION_ID | Session ID for the current shell or agent runtime. When set, nb env use and nb env current are isolated by session. |
Example:
export NB_CLI_ROOT=/your/workspace
export NB_LOCALE=zh-CN
Default configuration file:
~/.nocobase/config.json
After setting NB_CLI_ROOT=/your/workspace, the configuration file path becomes:
/your/workspace/.nocobase/config.json
The CLI is also compatible with reading legacy project configuration in the current working directory.
The session-level cache for the current env is stored in:
.nocobase/sessions/<NB_SESSION_ID>.json
The globally last-used env is stored in the lastEnv field of config.json. When NB_SESSION_ID is not set, the CLI falls back to this global value.
The runtime command cache is stored in:
.nocobase/versions/<hash>/commands.json
This file is generated or refreshed by nb env update and is used to cache runtime commands synchronized from the target application.