- name
- nocobase-app-plugin-cli-example
- description
- Use when adding commands to an application's nocobase CLI, or when working out how a plugin contributes CLI commands. Covers the ./cli entry, defineCliPlugin, and how topics are assembled.
CLI Example Plugin
This plugin contributes commands to the application's nocobase CLI. Read it as the reference implementation when
writing commands for another plugin.
What a CLI plugin is
A plugin contributes commands by exporting a ./cli entry. The application lists that entry in cli/plugins.ts, and pnpm nocobase assembles it into one command tree alongside the built-in commands of @nocobase/app-cli, such as config *, db *, plugin * and build, and the application's own app * commands.
Every command extends AppCommand from @nocobase/app-cli: it returns its result, throws CommandError on failure, and gets --json from the base class. By default a command is static tooling that operates on files and packages; one that needs the application creates it with this.withApp(async ({ app }) => …). The nocobase-app-plugin-development Skill's CLI reference has the whole contract.
The three pieces
A command is an AppCommand subclass — the same base the built-in commands use:
// cli/greet.ts
import { AppCommand } from '@nocobase/app-cli';
import { Args, Flags } from '@oclif/core';
export default class Greet extends AppCommand {
static override summary = 'Print a greeting.';
static override examples = ['<%= config.bin %> <%= command.id %> world'];
static override args = {
target: Args.string({ description: 'Who to greet.', required: true }),
};
static override flags = {
loud: Flags.boolean({ default: false, description: 'Upper-case it.' }),
};
public async run(): Promise<{ message: string }> {
const { args, flags } = await this.parse(Greet);
const message = flags.loud
? `HELLO, ${args.target.toUpperCase()}!`
: `Hello, ${args.target}.`;
this.log(message); // for people; silent under --json
return { message }; // the --json result
}
}
The entry names the package and declares the command maps: commands run wherever the application runs, a built dist/ included, and devCommands only in a source checkout. The topic is derived from the package name, without its scope and app-plugin- prefix, so @nocobase/app-plugin-cli-example mounts under :