• English

      • NocoBase CLI

      Description

      NocoBase CLI (nb) is the command-line entry point for initializing, connecting to, and managing NocoBase apps in a local workspace.

      It supports two common setup paths:

      • Connect an existing NocoBase app and save it as a CLI env
      • Install a new NocoBase app from Docker, npm, or Git, then save it as a CLI env

      When creating a new local app, nb init can also install or update NocoBase AI coding skills. Use --skip-skills when you want to skip that step.

      Usage

      nb [command]

      The root command mainly displays help and dispatches execution to command groups or standalone commands.

      Topics

      nb --help shows the following topics:

      TopicDescription
      nb apiWork with NocoBase API.
      nb appManage NocoBase app runtimes: start, stop, restart, logs, and upgrades.
      nb configManage CLI configuration defaults.
      nb dbManage the built-in database for the selected env.
      nb envManage NocoBase project environments, current env, status, details, and command runtimes.
      nb licenseManage commercial licensing and licensed plugins.
      nb pluginManage plugins in the selected NocoBase env.
      nb scaffoldGenerate NocoBase plugin development scaffolds.
      nb selfInspect or update the NocoBase CLI itself.
      nb sessionConfigure NB_SESSION_ID so current env is isolated per shell or agent runtime.
      nb skillsInspect or synchronize NocoBase AI coding skills for the current workspace.
      nb sourceWork with the local NocoBase source project: download, develop, build, and test.

      Commands

      Standalone commands exposed directly by the root command:

      CommandDescription
      nb initSet up NocoBase so coding agents can connect and work with it.

      Display help text

      Show help for the root command:

      nb --help

      Show help for a command or command group:

      nb init --help
nb app --help
nb config --help
nb api resource --help
nb license --help

      Examples

      Interactive setup:

      nb init

      Browser-based setup:

      nb init --ui

      Create a Docker-based app non-interactively:

      nb init --env app1 --yes --source docker --version alpha

      Connect an existing app:

      nb env add app1 --api-base-url http://localhost:13000/api
nb env current
nb env status

      Start the app and refresh runtime commands:

      nb app start -e app1
nb env update app1

      Call an API:

      nb api resource list --resource users -e app1

      View CLI default config:

      nb config list
nb config get docker.network

      View commercial license status:

      nb license status -e app1
nb license plugins list -e app1

      Environment variables

      The following environment variables affect CLI behavior:

      VariableDescription
      NB_CLI_ROOTRoot directory where the CLI stores .nocobase config and local app files. Defaults to the current user's home directory.
      NB_LOCALELanguage for CLI prompts and the local setup UI. Supported values are en-US and zh-CN.
      NB_SESSION_IDSession ID for the current shell or agent runtime. When set, nb env use and nb env current are isolated per session.

      Example:

      export NB_CLI_ROOT=/your/workspace
export NB_LOCALE=en-US

      Configuration files

      Default config file:

      ~/.nocobase/config.json

      After setting NB_CLI_ROOT=/your/workspace, the config file path becomes:

      /your/workspace/.nocobase/config.json

      The CLI also keeps compatibility with legacy project config under the current working directory.

      Current env session cache is stored in:

      .nocobase/sessions/<NB_SESSION_ID>.json

      The globally last-used env is stored in the lastEnv field in config.json. When NB_SESSION_ID is not set, the CLI falls back to that global value.

      Runtime command cache is stored in:

      .nocobase/versions/<hash>/commands.json

      This file is generated or refreshed by nb env update and caches runtime commands synchronized from the target app.