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 --helpIt 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',
])
}