nocobase Goal
Orchestrate NocoBase backup restore and migration workflows with the current API CLI command surface.
The skill converts user intent into an API-first publish context, carries generated names and local paths between steps, and requires explicit confirmation before restore or migration execution changes target data.
Scope
- Backup list, create, status, download, remove, restore, restore-upload, and restore-status through
nb api backup. - Migration file list, get, create, download, remove, check, and execute through
nb api migration. - Migration rule list, get, and global rule create through
nb api migration rules. - Migration log list, get, and download through
nb api migration logsfor diagnosis. - Same-environment and cross-environment workflows. The default test workflow uses
source_env=devandtarget_env=dev. - Planning, dry explanation, read-only validation, and failure diagnosis from command output.
Non-Goals
- This skill focuses on the API CLI command surface listed in Scope.
- Package and rule selection stays explicit.
- Restore, execute, and remove actions stay behind the execution confirmation gate.
- Failure recovery preserves the current context and waits for user direction before a new package or rule is created.
Input Contract
| Input | Required | Default | Validation | Clarification |
|---|---|---|---|---|
action |
yes | inferred | plan, run, or validate |
"Should I plan, run, or validate the workflow?" |
method |
run: yes | inferred | backup or migration |
"Use backup restore or migration publish?" |
source_env |
conditional | dev for tests |
non-empty env name | "Which environment provides or generates the file?" |
target_env |
run: yes | dev for tests |
non-empty env name | "Which environment should receive and execute the file?" |
backup_name |
optional | unset | backup file name from backup list/create |
"Which server backup should be restored or downloaded?" |
migration_name |
optional | unset | migration file name from migration list/create |
"Which server migration package should be downloaded?" |
local_file |
optional | unset | readable local .nbdata path |
"Which local package file should be uploaded or executed?" |
cli_home |
optional | CLI global home | writable CLI home directory | "Which CLI home should store downloaded release files?" |
rule_id |
migration create only | unset | non-empty id | "Which migration rule ID should be used?" |
migration_user_rule |
migration rule create only | schema-only |
schema-only or overwrite |
"How should user-defined tables be handled?" |
migration_system_rule |
migration rule create only | overwrite-first |
overwrite-first or schema-only |
"How should system tables be handled?" |
title |
migration create only | publish-<source>-to-<target> |
non-empty text | "Which migration title should be used?" |
execute_options |
optional | safe CLI defaults | known nb api backup restore* or nb api migration execute flags |
"Any high-risk flags such as --skip-backup or --skip-revert-on-error?" |
confirm_publish_input |
before create/download/rule create/check | unset | explicit approval | "Confirm the selected input before I create, download, or check the package." |
confirm_execute |
before restore/execute/remove | unset | must be confirm |
"Type confirm to execute on the target environment." |
Mandatory Clarification Gate
- Max clarification rounds: 2.
- Ask at most 3 short questions per round.
- Mutation steps require resolved
method,source_env, andtarget_env. - Migration package creation requires a selected or newly created
rule_id. - Existing package list flows require user selection of a specific file.
- Package create, package download, migration rule create, and migration check require publish input confirmation.
- Backup restore, backup restore-upload, backup remove, migration execute, and migration remove require execution confirmation.
- If the user says "you decide", choose a read-only planning path.
Workflow
- Route intent to
backupormigration. - Build a context with
method,sourceEnv,targetEnv,cliHome,releaseDir,backupName,migrationName,localFile,downloadPath,ruleId,title, andstep. - Run read-only capability probes for the needed command groups. Treat 404,
Not Found, unknown resource, inactive plugin, or license capability errors asunsupported_publish_env. - For backup restore:
- Local file: confirm the file, then restore it with
nb api backup restore-upload --file <localFile> -e <targetEnv> --force. - Server backup on target: confirm the backup name, then restore it with
nb api backup restore --name <backupName> -e <targetEnv> --force. - Source-to-target: create or select the backup on
sourceEnv, download it to<cliHome>/release/<sourceEnv>/<backupName>, then restore-upload that path ontargetEnvwith--force.
- Local file: confirm the file, then restore it with
- For migration:
- Local file: confirm the file, check it on
targetEnv, then execute it ontargetEnv. - Server migration package: download it from
sourceEnvto<cliHome>/release/<sourceEnv>/<migrationName>, check it ontargetEnv, then execute it ontargetEnv. - Created migration package: list or create a global rule, create the migration on
sourceEnv, pollmigration getuntil the generated package reportsstatus=ok, download it to<cliHome>/release/<sourceEnv>/<migrationName>, check it ontargetEnv, then execute it ontargetEnv.
- Local file: confirm the file, check it on
- Poll or inspect status with available commands when needed:
backup status,backup restore-status --task <taskId>,migration get, andmigration logs. - Treat restore task ids as compatible fields: parse
taskIdfromdata.taskIdordata.task, then pass that value tobackup restore-status --task. - Report the final state, commands executed or planned, file names, local paths, failed step, and next verification command.
See Runtime Contract for exact command construction and parsing rules.
Reference Loading Map
| Reference | Use When |
|---|---|
| Intent Routing | Mapping user phrases to backup, migration, file reuse, and environment shape. |
| Runtime Contract | Building commands and carrying names, paths, rules, and status between steps. |
| Test Playbook | Validating supported API workflows and failure cases. |
Safety Gate
High-impact actions:
nb api backup restorenb api backup restore-uploadnb api backup removenb api migration executenb api migration removenb api migration rules create- any option that skips target backup or revert behavior, such as
--skip-backupor--skip-revert-on-error
Publish input confirmation template:
Confirm publish input: <method> from <source_env> to <target_env>. Package source: <existing server file | local file | create new>. Migration rule: <ruleId/name | create new with user-defined-rule/system-defined-rule | not applicable>. Reply `confirm input` to continue with package creation, download, or check.
Execution confirmation template:
Confirm execution: <backup restore | migration execute> on <target_env> using <backupName | migrationName | localFile>. This may change target data. Reply `confirm` to continue.
Failure guidance:
- Backup restore failure: if a restore task id is available from
data.taskIdordata.task, inspectnb api backup restore-status --task <taskId> -e <targetEnv>. - Migration package creation: if
migration getreportsstatus=in_progress, tell the user the package is still generating, wait, and do not runmigration downloaduntilstatus=ok. - Migration check failure: report the check output and keep the local package path.
- Migration execution failure: inspect
nb api migration logs list -e <targetEnv>and relevantlogs get/downloadoutput. - Package or rule recreation after a failure requires explicit user instruction.
- Preserve the context in the final response so the user can resume from the correct file or rule.
Verification Checklist
- Publish operations use
nb api backupandnb api migrationcommand groups. - The default test context is
sourceEnv=devandtargetEnv=dev. - Participating environments pass read-only command probes before mutation.
- Capability probe failures are reported as
unsupported_publish_env. - Package lists and migration rule lists lead to explicit user selection.
- Existing local files skip package creation.
- Existing server backup names may use
backup restore --namewhen restoring inside the same target environment. - Cross-environment backup restore uses
backup downloadfollowed bybackup restore-upload --force. - Backup restore and restore-upload commands include
--forcedirectly. - Downloaded backup, migration, and log files are stored under
<cliHome>/release/<sourceEnv>/. - Migration execution uses a local package file with
migration check --filebeforemigration execute --file. - Missing migration file triggers migration rule list before asking for or creating
rule_id. migration rules createuses global rule options.- Created or selected migration rules are verified with
migration rules getwhen possible. - Download commands include
--output. - Restore status commands include
--task <taskId>and are only run after a task id is returned asdata.taskIdordata.task. - Restore or execute waits for secondary confirmation.
- Failure output includes the failed step and relevant CLI lines.
References
- Intent Routing
- Runtime Contract
- Test Playbook
- NocoBase Migration Manager: official context for migration risk and publish-related operations. [verified: 2026-04-30]