Newly created Adonis projects actually come with the Ace CLI packed in. The Ace CLI is Adonis' command-line interface (CLI). It allows us to conveniently create various types of files, startup our starter, get overview information about our project. It's also easily expandable by both installed packages and us the developers.

The first command you're probably going to utilize is called node ace serve, this is the command we use to start our server up. The serve command is what allows us to view our application in the browser at http://localhost:3333.

Ace Command Anatomy

Let's digest that serve command a little bit to get a better understanding of what we're doing. In the command node ace serve, the actual command name is serve while node ace is instructing Node that we'd like to communicate with the Ace CLI, made available via the ace file within our project. So, node ace gives us access to the Ace CLI, while serve is the actual command we're running.

Node Ace

If we initiate the Ace CLI using node ace, but don't give it a command the Ace CLI will print back to us a listing of all the currently available commands within our project.

Now, as we add additional packages to our application those packages can register additional commands for us to use to the Ace CLI. We too can also add additional commands as well by utilizing the node ace make:command command.

Initial Command Options

So, let's briefly run through the initial commands Adonis comes with out of the box and what those commands are for.

Available Commands

• build
  This will build out your applications, converting it from TypeScript to JavaScript. If we have frontend assets, it'll also build those assets using Webpack Encore.

• configure
  We'll use this to configure additional packages that we install within our application. Packages can include instructions on how that package needs to be added within a particular application to be used successfully. Configure will take those instructions and execute them on our application so the package is configured for us.

• repl
  This will allow us to communicate with our application via the command line. For example, we can import a Model and execute a query with that Model without touching our codebase inside a REPL session.

• serve
  This starts up our HTTP server.

Dump

• dump:rcfile
  This will dump the contents of our adonisrc.json file.

Generate

• generate:key
  This will generate a fresh APP_KEY value, which is stored within your .env file.

• generate:manifest
  This will generate or refresh a manifest file containing our Ace CLI commands.

List

• list:routes
  This will list all the configured routes in our application within a table inside our terminal. It'll also contain information about the route, like what's handling the route, its registered middleware, name, and so on.

Make

• make:command
  We can use this command to create a new command within our application. Each created command will get its own file within the commands directory.

• make:controller
  We can use this command to create a new controller within our application. These will be created within our app/Controllers/Http directory by default.

• make:exception
  We can use this command to create a new exception handler. These will be created within the app/Exceptions directory.

• make:listener
  We can use this command to create a new event listener. These will be created within the app/Listeners directory.

• make:middleware
  This allows us to create a new middleware. These will be created within the app/Middleware directory. Don't forget to register your new middleware file within your start/kernel.ts file.

• make:prldfile
  This allows us to create a new preload file. These will be created within the start directory. Don't forget to register your new preload files within your adonisrc.json file.

• make:provider
  This allows us to create a new provider. These will be created within the providers directory.

• make:validator
  This allows us to create a new validator class file. These will be created within the app/Validators directory.

• make:view
  This allows us to create a new view file. These will be created within the resources/views directory.

Global Flags

• -h, --help

• This will provide a list of all the currently registered commands available within your project. Additionally, you can run the -h or --help flag on any command to get additional information about that command. For example, node ace serve -h.

• -v, --version
  This will provide information about your application's version, your Adonis version, and your assembler version.

Creating A New Ace CLI Command

We can use the Ace CLI to easily create a new Ace CLI command. Let's take a look at the options the make:command command has by running it with the help flag.

node ace make:command -h

# Make a new ace command
#
# Usage: make command <name>
#
# Arguments
#    name       Name of the command class
#
# Flags
#    -e, --exact boolean    Create the command with the exact name as provided

So, here we can see the anatomy of the make:command is to run it as node ace make:command <name>, where <name> is the name we'd like the new command to have.

Adonis Naming Normalization

Now, Adonis conveniently normalizes class and file names when we create them using the Ace CLI. As you'll see later in the series when we make new controllers those controller names will be plural because controllers manage multiple records. Whereas, when we make Model names, they'll be singular because a Model represents a single record.

Adonis also does something similar with file name capitalizations.

The -e or --exact flag can be used to state that we'd like to bypass Adonis' normalization and have the file and classes named exactly as we specify.

Creating Our Command

Okay, so let's go ahead and create our command. For right now, let's just call this command Example, we're just going to create it so we can take a look at the process of adding a custom command.

node ace make:command Example

# CREATE: commands/Example.ts

Once executed, Adonis will create an Example.ts file within our commands directory. If we take a look at this newly created file we'll see the below.

// commands/Example.ts

import { BaseCommand } from '@adonisjs/core/build/standalone'

export default class Example extends BaseCommand {

  /**
   * Command name is used to run the command
   */
  public static commandName = 'example'

  /**
   * Command description is displayed in the "help" output
   */
  public static description = ''

  public static settings = {
    /**
     * Set the following value to true, if you want to load the application
     * before running the command
     */
    loadApp: false,

    /**
     * Set the following value to true, if you want this command to keep running until
     * you manually decide to exit the process
     */
    stayAlive: false,
  }

  public async run () {
    this.logger.info('Hello world!')
  }
}

You can see we have properties to be able to specify the command name, command description, and command settings.

The command name is what will appear within our Ace CLI command list. The description is the blurb that appears next to the command.

loadApp can be set to true to specify that the command needs to load the application prior to executing.

stayAlive can be set to true to specify that the command should remain alive until manually exited.

Finally, run is the method where we actually define what it is our command will do. By default, it'll use the logger to log an info block into our terminal or application log if it's executed in production.

Registering The Command

If you run node ace to look at your currently available commands, you'll notice our example command isn't yet displaying in our command list. This is because Adonis reads our commands from an ace-manifest.json file, which we haven’t yet updated.

To update the ace-manifest.json file with our new command, all we need to do is run the below in our terminal.

node ace generate:manifest

# CREATE: ace-manifest.json

You'll also want to run the generate:manifest command anytime you update a command's name, description, or settings as all of these values are stored within and read from the ace-manifest.json file.

Running Our Custom Command

Now that we've updated our ace-manifest.json file, if we run node ace again to list out our available commands we should now see our example command listed along with a description if you provided one.

Let's go ahead and execute this command by running the following.

node ace example

# [ info ] Hello world!

You should see [ info ] Hello world! printed out into your terminal, unless you changed your command at all, meaning our command ran successfully.

Wrapping Up

We've covered the initial list of commands the Ace CLI comes with, what the anatomy of a command looks like, the help panel, and how to create a new command.

Although our custom command only logged information into our terminal, we'll see later on in the series how we can further utilize custom commands to keep our database clean of old outdated data.