Introduction

Introduction

Ace is a command line framework used by AdonisJS to create and run console commands. The entry point file for Ace is stored in the root of your project, and you can execute it as follows.

node ace

Since the node binary cannot run the TypeScript source code directly, we have to keep the ace file in pure JavaScript and use the .js extension.

Under the hood, the ace.js file registers TS Node as an ESM module loader hook to execute the TypeScript code and imports the bin/console.ts file.

Help and list commands

You can view the list of available commands by running the ace entry point file without any arguments or using the list command.

node ace
# Same as above
node ace list

You can view help for a single command by typing the command name with the --help flag.

node ace make:controller --help

The output of the help screen is formatted as per the docopt standard.

Enabling/disabling colors

Ace detects the CLI environment in which it is running and disables the colorful output if the terminal does not support colors. However, you can manually enable or disable colors using the --ansi flag.

# Disable colors
node ace list --no-ansi
# Force enable colors
node ace list --ansi

Creating command aliases

Command aliases provide a convenience layer to define aliases for commonly used commands. For example, if you often create singular resourceful controllers, you may create an alias for it inside the adonisrc.ts file.

{
commandsAliases: {
resource: 'make:controller --resource --singular'
}
}

Once the alias is defined, you can use the alias to run the command.

node ace resource admin

How alias expansion works?

  • Every time you run a command, Ace will check for aliases inside the commandsAliases object.

  • If an alias exists, the first segment (before the space) will be used to look up the command.

  • If a command exists, the rest of the alias value segments will be appended to the command name.

    For example, if you run the following command

    node ace resource admin --help

    It will be expanded to

    make:controller --resource --singular admin --help

Running commands programmatically

You can use the ace service to execute commands programmatically. The ace service is available after the application has been booted.

The ace.exec method accepts the command name as the first parameter and an array of command line arguments as the second parameter. For example:

import ace from '@adonisjs/core/services/ace'
const command = await ace.exec('make:controller', [
'user',
'--resource',
])
console.log(command.exitCode)
console.log(command.result)
console.log(command.error)

You may use the ace.hasCommand method to check if a command exists before executing it.

import ace from '@adonisjs/core/services/ace'
/**
* Boot method will load commands (if not already loaded)
*/
await ace.boot()
if (ace.hasCommand('make:controller')) {
await ace.exec('make:controller', [
'user',
'--resource',
])
}