Class BaseCommand

The base command sets the foundation for defining ace commands. Every command should inherit from the base command.

Example

export class MyCommand extends BaseCommand {
  static commandName = 'my:command'
  static description = 'My custom command'

  async run() {
    this.logger.info('Hello from my command!')
  }
}

Hierarchy (View Summary)

default
- BaseCommand
  - HelpCommand
  - ListCommand

Index

Constructors

constructor

new BaseCommand(
    kernel: Kernel<any>,
    parsed: ParsedOutput,
    ui: {},
    prompt: Prompt,
): BaseCommand
Create a new base command instance
Parameters
- kernel: Kernel<any>
  The Ace kernel instance
- parsed: ParsedOutput
  The parsed CLI input
- ui: {}
  UI primitives for output
- prompt: Prompt
  Prompt utilities for user interaction
Returns BaseCommand
Overrides Macroable.constructor
- Defined in src/commands/base.ts:527

Properties

`Static`booted

booted: boolean = false

Whether the command class has been booted

`Static`options

options: CommandOptions

Configuration options accepted by the command

`Static`aliases

aliases: string[]

A collection of aliases for the command

`Static`commandName

commandName: string

The command name one can type to run the command

`Static`description

description: string

The command description

`Static` `Optional`help

help?: string | string[]

The help text for the command. Help text can be a multiline string explaining the usage of command

`Static`args

args: Argument[]

Registered arguments

`Static`flags

flags: Flag[]

Registered flags

`Optional`exitCode

exitCode?: number

The exit code for the command

`Optional`error

error?: any

The error raised at the time of executing the command. The value is undefined if no error is raised.

`Optional`result

result?: any

The result property stores the return value of the "run" method (unless command sets it explicitly)

ui

ui: {}

UI primitives for output

prompt

prompt: Prompt

Prompt utilities for user interaction

Accessors

logger

get logger(): Logger

Logger to log messages

Returns Logger

Example

this.logger.info('Command executed successfully')
this.logger.error('Something went wrong')

colors

get colors(): Colors
Add colors to console messages

Returns Colors
Example
```
this.logger.info(this.colors.green('Success!'))
this.logger.error(this.colors.red('Error!'))
```
- Defined in src/commands/base.ts:473

isMain

get isMain(): boolean
Is the current command the main command executed from the CLI

Returns boolean
Example
```
if (this.isMain) {
  this.logger.info('This is the main command')
}
```
- Defined in src/commands/base.ts:487

commandName

get commandName(): string
Reference to the command name

Returns string
- Defined in src/commands/base.ts:494

options

get options(): CommandOptions
Reference to the command options

Returns CommandOptions
- Defined in src/commands/base.ts:501

args

get args(): Argument[]
Reference to the command args

Returns Argument[]
- Defined in src/commands/base.ts:508

flags

get flags(): Flag[]
Reference to the command flags

Returns Flag[]
- Defined in src/commands/base.ts:515

Methods

`Static`boot

boot(): void
Define static properties on the class. During inheritance, certain properties must inherit from the parent.

Returns void
Example
```
MyCommand.boot()
```
- Defined in src/commands/base.ts:101

`Static`defineArgument

defineArgument(
name: string,
options: Partial<Argument> & { type: "string" | "spread" },
): void
Specify the argument the command accepts. The arguments via the CLI will be accepted in the same order as they are defined.

Mostly, you will be using the @args decorator to define the arguments.
Parameters
- name: string
  The name of the argument
- options: Partial<Argument> & { type: "string" | "spread" }
  Configuration options for the argument
Returns void
Example
```
Command.defineArgument('entity', { type: 'string' })
Command.defineArgument('files', { type: 'spread', required: false })
```
- Defined in src/commands/base.ts:134

`Static`defineFlag

defineFlag(
    name: string,
    options: Partial<Flag> & {
        type: "string" | "number" | "boolean" | "array";
    },
): void
Specify a flag the command accepts.

Mostly, you will be using the @flags decorator to define a flag.
Parameters
- name: string
  The name of the flag
- options: Partial<Flag> & { type: "string" | "number" | "boolean" | "array" }
  Configuration options for the flag
Returns void
Example
```
Command.defineFlag('connection', { type: 'string', required: true })
Command.defineFlag('force', { type: 'boolean' })
Command.defineFlag('tags', { type: 'array' })
```
- Defined in src/commands/base.ts:189

`Static`getParserOptions

getParserOptions(
    options?: FlagsParserOptions,
): {
    flagsParserOptions: Required<FlagsParserOptions>;
    argumentsParserOptions: ArgumentsParserOptions[];
}
Returns the options for parsing flags and arguments
Parameters
- Optionaloptions: FlagsParserOptions
  Optional parser options to merge
Returns {
flagsParserOptions: Required<FlagsParserOptions>;
argumentsParserOptions: ArgumentsParserOptions[];
}
- Defined in src/commands/base.ts:217

`Static`serialize

serialize(): CommandMetaData
Serializes the command to JSON. The return value satisfies the CommandMetaData

Returns CommandMetaData
Example
```
const metadata = MyCommand.serialize()
console.log(metadata.commandName) // 'my:command'
```
- Defined in src/commands/base.ts:291

`Static`validate

validate(parsedOutput: ParsedOutput): void
Validate the yargs parsed output against the command.
Parameters
- parsedOutput: ParsedOutput
  The parsed CLI input to validate
Returns void
Example
```
const parsed = { args: ['value'], flags: { force: true }, unknownFlags: [] }
MyCommand.validate(parsed)
```
- Defined in src/commands/base.ts:328

hydrate

hydrate(): void
Hydrate command by setting class properties from the parsed output

Returns void
Example
```
command.hydrate()
console.log(command.name) // Argument value
console.log(command.force) // Flag value
```
- Defined in src/commands/base.ts:546

run

run(..._: any[]): Promise<any>
The run method should include the implementation for the command.
Parameters
- ..._: any[]
  Additional arguments (not used in base implementation)
Returns Promise<any>
Example
```
async run() {
  this.logger.info('Running my command')
  return 'Command completed'
}
```
- Defined in src/commands/base.ts:593

exec

exec(): Promise<any>
Executes the command by running the command's run method.

Returns Promise<any>
Example
```
const result = await command.exec()
console.log('Exit code:', command.exitCode)
```
- Defined in src/commands/base.ts:604

toJSON

toJSON(): {
    commandName: string;
    options: CommandOptions;
    args: any[];
    flags: { [argName: string]: any };
    error: any;
    result: any;
    exitCode: undefined | number;
}
JSON representation of the command

Returns {
    commandName: string;
    options: CommandOptions;
    args: any[];
    flags: { [argName: string]: any };
    error: any;
    result: any;
    exitCode: undefined | number;
}
Example
```
const json = command.toJSON()
console.log(json.commandName, json.exitCode)
```
- Defined in src/commands/base.ts:627

assertExitCode

assertExitCode(code: number): void
Assert the command exits with a given exit code
Parameters
- code: number
  The expected exit code
Returns void
Example
```
command.assertExitCode(0) // Assert successful execution
command.assertExitCode(1) // Assert failure
```
- Defined in src/commands/base.ts:650

assertNotExitCode

assertNotExitCode(code: number): void
Assert the command does not exit with a given exit code
Parameters
- code: number
  The exit code that should not be used
Returns void
Example
```
command.assertNotExitCode(1) // Assert no failure
```
- Defined in src/commands/base.ts:672

assertSucceeded

assertSucceeded(): void
Assert the command exits with zero exit code

Returns void
Example
```
command.assertSucceeded() // Assert success
```
- Defined in src/commands/base.ts:689

assertFailed

assertFailed(): void
Assert the command exits with non-zero exit code

Returns void
Example
```
command.assertFailed() // Assert failure
```
- Defined in src/commands/base.ts:701

assertLog

assertLog(message: string, stream?: "stdout" | "stderr"): void
Assert command logs the expected message
Parameters
- message: string
  The expected log message
- Optionalstream: "stdout" | "stderr"
  Optional stream to check ('stdout' or 'stderr')
Returns void
Example
```
command.assertLog('Command executed successfully')
command.assertLog('Error occurred', 'stderr')
```
- Defined in src/commands/base.ts:717

assertLogMatches

assertLogMatches(matchingRegex: RegExp, stream?: "stdout" | "stderr"): void
Assert command logs a message matching the given regex
Parameters
- matchingRegex: RegExp
  The regex pattern to match against log messages
- Optionalstream: "stdout" | "stderr"
  Optional stream to check ('stdout' or 'stderr')
Returns void
Example
```
command.assertLogMatches(/^Command.*completed$/)
command.assertLogMatches(/error/i, 'stderr')
```
- Defined in src/commands/base.ts:763

assertTableRows

assertTableRows(rows: string[][]): void
Assert the command prints a table with the expected rows to stdout
Parameters
- rows: string[][]
  The expected table rows as arrays of strings
Returns void
Example
```
command.assertTableRows([
  ['Name', 'Age'],
  ['John', '25'],
  ['Jane', '30']
])
```
- Defined in src/commands/base.ts:807

Class BaseCommand

Example

Hierarchy (View Summary)

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns BaseCommand

Properties

Staticbooted

Staticoptions

Staticaliases

StaticcommandName

Staticdescription

Static Optionalhelp

Staticargs

Staticflags

OptionalexitCode

Optionalerror

Optionalresult

ui

prompt

Accessors

logger

Returns Logger

Example

colors

Returns Colors

Example

isMain

Returns boolean

Example

commandName

Returns string

options

Returns CommandOptions

args

Returns Argument[]

flags

Returns Flag[]

Methods

Staticboot

Returns void

Example

StaticdefineArgument

Parameters

Returns void

Example

StaticdefineFlag

Parameters

Returns void

Example

StaticgetParserOptions

Parameters

Returns { flagsParserOptions: Required<FlagsParserOptions>; argumentsParserOptions: ArgumentsParserOptions[];}

Staticserialize

Returns CommandMetaData

Example

Staticvalidate

Parameters

Returns void

Example

hydrate

Returns void

Example

run

Parameters

Returns Promise<any>

Example

exec

Returns Promise<any>

Example

toJSON

Returns { commandName: string; options: CommandOptions; args: any[]; flags: { [argName: string]: any }; error: any; result: any; exitCode: undefined | number;}

Example

assertExitCode

`Static`booted

`Static`options

`Static`aliases

`Static`commandName

`Static`description

`Static` `Optional`help

`Static`args

`Static`flags

`Optional`exitCode

`Optional`error

`Optional`result

`Static`boot

`Static`defineArgument

`Static`defineFlag

`Static`getParserOptions

Returns {
flagsParserOptions: Required<FlagsParserOptions>;
argumentsParserOptions: ArgumentsParserOptions[];
}

`Static`serialize

`Static`validate

Returns {
commandName: string;
options: CommandOptions;
args: any[];
flags: { [argName: string]: any };
error: any;
result: any;
exitCode: undefined | number;
}