agents-store nb CLI — install and recipes
The nb CLI is the canonical way to bootstrap and operate a NocoBase v2 project from a terminal. This skill covers install, the most-used commands, and where to go for deeper topics.
Install
npm install -g @nocobase/cli@beta
nb --version
Requirements: Node.js 18 or newer, npm or pnpm, and Docker if you plan to use the bundled database/storage stacks. If the install errors with EACCES, configure a user-level npm prefix (npm config set prefix "$HOME/.npm-global") rather than running with sudo.
Bootstrap a project
mkdir my-nocobase && cd my-nocobase
nb init --ui
nb init --ui opens a browser-based setup wizard. The CLI keeps the process running until the user finishes the wizard — set a 30-minute timeout and do not interrupt it.
In a sandboxed environment where the CLI cannot open a browser:
- Surface the URL to the user; do not auto-fill the form.
- If the agent cannot reach the URL at all, ask to elevate / step outside the sandbox.
The wizard installs core skills (the same 11 you have bundled here) into the project — that is intentional and harmless.
→ Detailed rules and edge cases live in nocobase-env-manage.
Lifecycle
# Run / stop / restart the dev server
nb start
nb stop
nb restart
# Pull a new release without losing data
nb upgrade
# Inspect what's running
nb status
Plugin manager
nb pm list # all plugins, with enabled/disabled state
nb pm enable <name> # e.g. nb pm enable api-keys
nb pm disable <name>
nb pm add <package> # install from registry
nb pm remove <name>
→ For the full grammar and error handling, load nocobase-plugin-manage. That skill enforces "no docker/api/manual fallback chains" — only direct nb pm commands.
Backup, restore, migration
# Local snapshot
nb backup ./backups/$(date +%F).nbdump
# Restore (cold; the app must be stopped)
nb stop
nb restore ./backups/2026-04-28.nbdump
# Cross-environment migration (export from staging, import to prod)
nb migration export --out staging.dump
nb migration import --in staging.dump
→ The full publish playbook (selective backups, partial restores, version compatibility) lives in nocobase-publish-manage.
Declarative nb api surface
nb api … dispatches to the same FlowModel surface that the UI builder uses. It is the "configuration-as-code" entry point that the upstream skills rely on:
nb api flow-surfaces apply path/to/blueprint.yaml
nb api collections list
nb api workflows trigger --tk order-fulfilment --data '{"orderId":100}'
Each upstream skill documents the subcommands it owns:
| Sub-command family | Skill |
|---|---|
nb api flow-surfaces … (UI authoring) |
nocobase-ui-builder |
nb api collections …, nb api fields … |
nocobase-data-modeling |
nb api workflows …, nb api flow-nodes … |
nocobase-workflow-manage |
nb api roles …, role-mode toggles |
nocobase-acl-manage |
Always reach for the specialist skill first — it has the per-command argument tables, safety rules, and worked examples.
Workspaces / DSL
If the user explicitly asks for a YAML/DSL "committed-to-git" build flow, hand off to nocobase-dsl-reconciler — it owns cli push, the workspaces/ layout, and reconciliation logic. Do not invoke the DSL path for ad-hoc UI tweaks; use nocobase-ui-builder instead (live API, no commit needed).
Quick reference
| Task | One-liner |
|---|---|
| Install | npm install -g @nocobase/cli@beta |
| Bootstrap (interactive) | nb init --ui |
| Run / stop | nb start / nb stop |
| Upgrade in place | nb upgrade |
| Enable a plugin | nb pm enable <name> |
| Backup | nb backup ./out.nbdump |
| Migrate environment | nb migration export/import |
| Apply a UI blueprint | nb api flow-surfaces apply <yaml> |
| Trigger a workflow | nb api workflows trigger --tk <key> --data '{…}' |
When to use REST API instead
- The agent runs on a different host from NocoBase — the CLI is local-only.
- The call is part of a webhook handler, scheduled job, or another service.
- You need streaming or fine-grained pagination — those are HTTP-native.
For everything else, prefer nb when it is available; it carries fewer auth and CORS pitfalls than raw HTTP.