@nocobase/cli 2.1.0-alpha.3 → 2.1.0-alpha.31

package/LICENSE.txt

@@ -0,0 +1,107 @@
+Updated Date: February 24, 2026
+
+NocoBase License Agreement
+
+NOCOBASE PTE. LTD.，a Singaporean Exempt Private Company Limited by Shares with its principal place of business located at 112 ROBINSON ROAD, #03-01, SINGAPORE ("The Company") https://www.nocobase.com/ issues this License Agreement ("Agreement") to you. You, as an individual or a company ("The User"), will be deemed to voluntarily accept all terms of this Agreement by using NocoBase (including but not limited to obtaining NocoBase source code or installation package in any form, installing and using NocoBase, purchasing NocoBase commercial license and services, purchasing NocoBase commercial plugins). If the User does not agree to any term of this Agreement, or cannot accurately understand our interpretation of the relevant terms, please stop using it immediately.
+
+This Agreement applies to any use, quotation, contract, invoice, and all software delivered by the Company. The User and the Company or NocoBase's agents can no longer sign a separate license agreement for the sale and delivery of the software.
+
+The Company reserves the right to formulate and modify this Agreement from time to time as needed. If there are changes, the Company will announce them in the form of website announcements, without further individual notification. The changed Agreement will automatically take effect once it is announced, becoming part of this Agreement.
+
+==============
+1. Definitions
+==============
+
+1.1 "Software" refers to the NocoBase kernel and plugins placed in the same code repository as the kernel, including their source code, installation packages, images, and all their modifications, updates, and upgrades.
+
+1.2 "Community Edition" refers to the free version of the Software provided to the User through public channels.
+
+1.3 "Commercial Edition" refers to the paid version of the Software purchased by the User from the Company or its agents, downloaded through exclusive channels, and includes additional benefits. It consists of three versions: Standard Edition, Professional Edition, and Enterprise Edition.
+
+1.4 "Upper Layer Application" refers to a specific business use case application serving internal or external customers of the User, developed based on Software and Commercial Plugins, such as ERP/CRM.
+
+1.5 "Customer" refers to the clients who purchase the User's Upper Layer Application.
+
+1.6 "Third-Party Open Source Software" refers to open source software provided with Software and Commercial Plugins. They are licensed through various published open source software licenses or copyright notices accompanying such software.
+
+===================================
+2. Intellectual Property Protection
+===================================
+
+Except for Third-Party Open Source Software, the Company owns all copyrights, trademark rights, patent rights, trade secrets, and other intellectual property rights of the Software, and has registered and protected them in relevant countries and regions according to the "Paris Convention" or "TRIPS Agreement", ensuring that the intellectual property rights of the Software and Commercial Plugins are internationally recognized and protected.
+
+=============
+3. Disclaimer
+=============
+
+3.1 The User shall not use the Software and Commercial Plugins to engage in activities that contravene applicable laws and regulations or offend against public order or religious prohibitions. All legal liabilities and consequences arising from the User’s use shall be borne by the User.
+
+3.2 The Company shall not be liable for any direct, indirect, special, incidental, or consequential damages (including but not limited to loss of profits, business interruption, data loss, or business information disclosure) caused by the User's use of the Software and Commercial Plugins, even if it has been previously informed of the possibility of such damages.
+
+===============
+4. License Type
+===============
+
+4.1 This Agreement serves as the unified license agreement for NocoBase Software, applying to both the Community Edition and the Commercial Editions.
+
+4.2 This Agreement incorporates and references the full text of the Apache License, Version 2.0 ("Apache-2.0", available at: https://www.apache.org/licenses/LICENSE-2.0 ). Users must comply with the Apache-2.0 License as well as the supplementary terms set forth in this Agreement. In case of any inconsistency between Apache-2.0 and this Agreement, the supplementary terms of this Agreement shall prevail.
+
+================================================
+5. Rights and Obligations of Open Source License
+================================================
+
+5.1 The Software can be used for commercial purposes.
+
+5.2 It is not allowed to remove or change the brand, name, link, version number, license, and other information about NocoBase on the Software interface, except for the main LOGO in the upper left corner of the page.
+
+5.3 It is not allowed to remove or change all intellectual property statements about NocoBase in the code.
+
+5.4 It is not allowed to provide to the public any form of no-code, zero-code, low-code, AI platform SaaS/PaaS products using the original or modified Software.
+
+===============================
+6. Rights of Commercial License
+===============================
+
+6.1 Obtain a permanent commercial license of the Software.
+
+6.2 Get software upgrades and exclusive technical support during the upgrade validity period.
+
+6.3 The licensed Software can be used for commercial purposes with no restrictions on the number of applications and users.
+
+6.4 Can remove or change the brand, name, link, version number, license, and other information about NocoBase on the Software interface.
+
+6.5 The User holding a Professional or Enterprise Edition License can sell Upper Layer Application to its Customers.
+
+6.6 If there are other agreements in the contract for the above rights, the contract agreement shall prevail.
+
+====================================
+7. Obligations of Commercial License
+====================================
+
+7.1 It is not allowed to remove or change all intellectual property statements about NocoBase in the code.
+
+7.2 It is not allowed to sell, transfer, lease, share, gift, or distribute the Commercial License.
+
+7.3 It is not allowed to sell, transfer, lease, share, or distribute any form of no-code, zero-code, low-code, AI platform, or developer tools developed based on Software.
+
+7.4 It is not allowed to provide any form of no-code, zero-code, low-code, AI platform SaaS/PaaS products to the public using the original or modified Software.
+
+7.5 It is not allowed for the User holding a Standard Edition license to sell Upper Layer Application to Customers without a Commercial license.
+
+7.6 It is not allowed for the User holding a Professional or Enterprise Edition license to sell Upper Layer Application to Customers without a Commercial license with access to further development and configuration.
+
+7.7 If there is a violation of the above obligations or the terms of this Agreement, the rights owned by the User will be immediately terminated, the paid fees will not be refunded, and the Company reserves the right to pursue the User's legal responsibility.
+
+7.8 If there are other agreements in the contract for the above obligations, the contract agreement shall prevail.
+
+=============================================================
+8.  Legal Jurisdiction, Interpretation, and Dispute Resolution
+=============================================================
+
+8.1 Except for Mainland China, the interpretation, application, and all matters related to this agreement are subject to the jurisdiction of Singapore law.
+
+8.2 Any dispute related to this Agreement should first be resolved through friendly negotiation. If the negotiation fails to resolve the dispute, the dispute should be submitted to the International Chamber of Commerce (ICC) for arbitration. The arbitration venue should be Singapore, conducted in English.
+
+8.3 All terms and conditions of this Agreement shall be deemed enforceable to the maximum extent permitted by applicable law. If any term of this Agreement is deemed invalid by any applicable law, the invalidity of that term does not affect the validity of any other term of this Agreement, and it should be deemed that the invalid term has been modified as much as possible to make it valid and enforceable, or if the term cannot be modified, it should be deemed to have been deleted from this Agreement.
+
+8.4 The arbitration award is final, binding on both parties, and can be enforced in any court with jurisdiction.

package/README.md

@@ -1,30 +1,390 @@
-# NocoBase
+# NocoBase CLI
 
-<video width="100%" controls>
-      <source src="https://static-docs.nocobase.com/NocoBase0510.mp4" type="video/mp4">
-</video>
+NocoBase CLI (`nb`) is a command-line tool for setting up and managing NocoBase
+apps in a local workspace. It helps you connect coding agents to NocoBase by
+preparing the app, saving the CLI env config, and providing day-to-day commands
+for start, stop, logs, upgrade, and cleanup.
 
+The CLI supports two common setup paths:
 
-## What is NocoBase
+- Connect an existing NocoBase app so coding agents can use it.
+- Install a new NocoBase app from Docker, npm, or Git, then connect it as a CLI env.
 
-NocoBase is a scalability-first, open-source no-code development platform.  
-Instead of investing years of time and millions of dollars in research and development, deploy NocoBase in a few minutes and you'll have a private, controllable, and extremely scalable no-code development platform!
+## Prerequisites
 
-Homepage:  
-https://www.nocobase.com/
+- Node.js v20+
+- Yarn 1.x
+- Git, required when installing from Git source
+- Docker, required when installing with Docker or using the built-in database
 
-Online Demo:  
-https://demo.nocobase.com/new
+## Installation
 
-Documents:  
-https://docs.nocobase.com/
+Install the CLI globally:
 
-Commericial license & plugins:  
-https://www.nocobase.com/en/commercial
+```bash
+npm install -g @nocobase/cli@alpha
+```
 
-License agreement:   
-https://www.nocobase.com/en/agreement
+Check the available commands:
 
+```bash
+nb --help
+nb init --help
+```
 
-## Contact Us:  
-hello@nocobase.com
+## Core Concepts
+
+- **Workspace**: the current project folder where `.nocobase` is stored.
+- **Env**: a named NocoBase connection saved by the CLI. In `nb init`, the app name is also the env name.
+- **Source**: how the local app is obtained. Supported values are `docker`, `npm`, and `git`.
+- **Remote env**: an env that only stores an API connection to an existing NocoBase app.
+- **Runtime resources**: local app process, Docker app container, built-in database container, source directory, and storage directory managed by CLI commands.
+
+## Quick Start
+
+### Guided Setup
+
+Run the guided terminal flow:
+
+```bash
+nb init
+```
+
+Use the browser-based setup form:
+
+```bash
+nb init --ui
+```
+
+`nb init` can either connect to an existing NocoBase app or install a new one.
+When creating a new app, it can also install NocoBase AI coding skills
+(`nocobase/skills`) globally.
+
+Use `--skip-skills` if the skills are managed separately, or when running in CI
+or offline environments where `nb init` should not install or update them.
+
+### Non-Interactive Setup
+
+When prompts are skipped, an app/env name is required:
+
+```bash
+nb init --env app1 --yes
+nb init --env app1 --yes --skip-skills
+```
+
+Install with Docker:
+
+```bash
+nb init --env app1 --yes --source docker --version alpha
+```
+
+Install from npm:
+
+```bash
+nb init --env app1 --yes --source npm --version alpha --app-port 13080
+```
+
+Install from Git source:
+
+```bash
+nb init --env app1 --yes --source git --version alpha
+```
+
+For Git source installs, `--version alpha` resolves to the `develop` branch.
+
+Install from a Git branch:
+
+```bash
+nb init --env app1 --yes --source git --version fix/cli-v2
+```
+
+`--version` is the shared version input across sources:
+
+- npm: package version
+- Docker: image tag
+- Git: git ref such as a branch or tag
+
+By default, a new local app uses:
+
+- Source directory: `./<envName>/source/`
+- Storage directory: `./<envName>/storage/`
+
+### Resume an Interrupted Setup
+
+If `nb init` was interrupted after the env config had already been saved, you can continue the same setup:
+
+```bash
+nb init --env app1 --resume
+nb init --env app1 --resume --skip-skills
+```
+
+`--resume` reuses the saved workspace env config for app, source, database, and env connection settings. In interactive mode, it only asks for any missing setup-only values.
+
+In non-interactive resume mode, `nb init --resume --yes` uses default initialization values unless these flags are passed explicitly:
+
+- `--lang`
+- `--root-username`
+- `--root-email`
+- `--root-password`
+- `--root-nickname`
+
+## Daily Commands
+
+| Command | Description |
+| --- | --- |
+| `nb init` | Set up NocoBase and connect it as a CLI env for coding agents. |
+| `nb app` | Manage app runtimes: start, stop, restart, logs, cleanup, and upgrades. |
+| `nb source` | Manage the local source project: download, develop, build, and test. |
+| `nb db` | Inspect or manage built-in database runtime status for local envs. |
+| `nb env` | Manage saved CLI env connections. |
+| `nb api` | Call NocoBase API resources from the CLI. |
+| `nb plugin` | Manage plugins for the selected NocoBase env. |
+| `nb self` | Check or update the installed NocoBase CLI. |
+| `nb skills` | Check, install, or update global NocoBase AI coding skills. |
+
+Recommended style: pass the env name explicitly when operating on a specific env. Runtime commands accept `--env`, and `nb env info` also accepts a positional env name:
+
+```bash
+nb app start --env app1
+nb app restart --env app1
+nb app logs --env app1
+nb env info app1
+nb db ps --env app1
+```
+
+Equivalent shorthand examples:
+
+```bash
+nb app start -e app1
+nb app restart -e app1
+nb app logs -e app1
+nb app upgrade -e app1
+nb db start -e app1
+```
+
+## CLI And Skills Updates
+
+Check whether the installed CLI itself is up to date:
+
+```bash
+nb self check
+nb self check --json
+```
+
+Update the CLI when it is installed globally with npm:
+
+```bash
+nb self update
+```
+
+Check whether the global NocoBase AI coding skills are installed:
+
+```bash
+nb skills check
+nb skills check --json
+```
+
+Install the skills for the first time, or update an existing `nocobase/skills` install:
+
+```bash
+nb skills install
+nb skills update
+```
+
+## Runtime Types
+
+### Docker
+
+Docker envs are managed through saved Docker containers and images:
+
+```bash
+nb init --env app1 --yes --source docker --version alpha
+nb app start --env app1
+nb app restart --env app1
+nb app logs --env app1
+nb app stop --env app1
+```
+
+Docker downloads support platform selection:
+
+```bash
+nb source download --source docker --version alpha --docker-platform auto
+nb source download --source docker --version alpha --docker-platform linux/amd64
+nb source download --source docker --version alpha --docker-platform linux/arm64
+```
+
+### npm and Git
+
+npm and Git envs use a local source directory and can run development mode:
+
+```bash
+nb init --env app1 --yes --source git --version alpha
+nb source dev --env app1
+```
+
+`nb source dev` only supports npm/Git source envs. Docker envs can be inspected with
+`nb app logs`, and remote envs only support API/env operations.
+
+### Existing NocoBase App
+
+To connect an existing app, use `nb init` and choose the existing-app setup
+path, or add the env directly:
+
+```bash
+nb env add app1 --api-base-url http://localhost:13000/api
+```
+
+`nb env add` will start the authentication flow automatically when needed.
+
+## Upgrade
+
+Upgrade refreshes the saved source or image, then restarts the app:
+
+```bash
+nb app upgrade --env app1
+```
+
+Use `--skip-code-update` or `-s` to restart with the saved local code or Docker
+image without downloading updates first:
+
+```bash
+nb app upgrade --env app1 -s
+```
+
+## Database Commands
+
+Use `nb db` to inspect or manage the built-in database runtime for a local env:
+
+```bash
+nb db ps
+nb db ps --env app1
+nb db start --env app1
+nb db stop --env app1
+nb db logs --env app1
+```
+
+Notes:
+
+- `nb db start` and `nb db stop` only work for envs created with the built-in database option enabled.
+- `nb db logs` only works for envs created with the built-in database option enabled.
+- `nb db ps` can also show `external` or `remote` status for envs that do not have a CLI-managed database container.
+
+## Cleanup
+
+Bring down a local env:
+
+```bash
+nb app down --env app1
+```
+
+By default, `nb app down` stops the app and removes app/database containers if they
+exist. For local envs, it also deletes the saved local app files. It keeps storage data and CLI env config.
+
+Use explicit flags for destructive cleanup:
+
+```bash
+nb app down --env app1 --all --yes
+```
+
+- `--all`: delete everything for the env, including storage data and the saved env config. This requires `--yes`.
+
+## Environment Management
+
+Show the current env:
+
+```bash
+nb env
+```
+
+List configured envs with token-verified API status:
+
+```bash
+nb env list
+```
+
+Show details for one env:
+
+```bash
+nb env info app1
+```
+
+Switch the current env:
+
+```bash
+nb env use app1
+```
+
+Re-authenticate an env when credentials need to be refreshed:
+
+```bash
+nb env auth app1
+```
+
+Update runtime command metadata from the selected app:
+
+```bash
+nb env update app1
+```
+
+## API Commands
+
+The CLI can call NocoBase resources through the configured env:
+
+```bash
+nb api resource list --resource users -e app1
+nb api resource get --resource users --filter-by-tk 1 -e app1
+nb api resource create --resource users --values '{"nickname":"Ada"}' -e app1
+```
+
+Create and download a backup:
+
+```bash
+nb api backup create -e app1
+nb api backup status --name backup_20260430_120000_1234.nbdata -e app1
+nb api backup download --name backup_20260430_120000_1234.nbdata --output ./backup.nbdata -e app1
+```
+
+Restore or run a migration package:
+
+```bash
+nb api backup restore-upload --file ./backup.nbdata -e app1
+nb api migration rules create --name default --user-defined-rule schema-only --system-defined-rule overwrite-first -e app1
+nb api migration create --rule-id 1 --title release-20260430 -e app1
+nb api migration execute --file ./migration.nbdata -e app1
+```
+
+Use `-j, --json-output` to print raw JSON when available:
+
+```bash
+nb api resource list --resource users -e app1 -j
+```
+
+Available API command topics:
+
+| Command | Description |
+| --- | --- |
+| `nb api acl` | Manage access control based on roles, resources, and actions. |
+| `nb api api-keys` | Manage API keys for HTTP API access. |
+| `nb api app` | Manage application resources. |
+| `nb api authenticators` | Manage user authentication, including password auth, SMS auth, SSO protocols, and extensible providers. |
+| `nb api backup` | Create, download, remove, and restore backups. |
+| `nb api data-modeling` | Manage data sources, collections, and database modeling resources. |
+| `nb api file-manager` | Manage file storage services, file collections, and attachment fields. |
+| `nb api flow-surfaces` | Compose and mutate page, tab, block, field, and action surfaces. |
+| `nb api migration` | Create, check, execute, and inspect migration packages. |
+| `nb api pm` | Manage plugins through API commands. |
+| `nb api resource` | Work with generic collection resources. |
+| `nb api system-settings` | Adjust system title, logo, language, and other global settings. |
+| `nb api theme-editor` | Customize UI colors and dimensions, save themes, and switch between them. |
+| `nb api workflow` | Manage workflow resources for business automation. |
+
+## Local Data
+
+The CLI stores workspace-level config in `.nocobase`:
+
+- `config.json`: env definitions, current env, and workspace-level settings.
+- `versions/<version>/commands.json`: cached runtime commands generated from the target app.
+
+Runtime data such as source files, storage files, Docker containers, and
+database data are managed separately according to the env source and install
+options.