Antora CLI Commands
This page introduces you to the Antora CLI and how you can use it to configure and run Antora.
What’s the Antora CLI?
The Antora command line interface (Antora CLI) is a simple tool (named
antora) that enables you to execute and optionally configure Antora and any registered extended components and extensions from the command prompt of your terminal application.
Antora’s CLI is the primary user-facing entry point for Antora. Therefore, you’ll frequently see it referenced in the documentation as the recommended way to interact with Antora.
|If you aren’t familiar with the command line, the CLI Primer provides a basic overview of command anatomy, navigating working directories, and terminal application concepts.|
By default, Antora looks in the provided playbook for its configuration settings. When using the Antora CLI, you can specify optional configuration overrides as necessary using CLI options or environment variables.
When you interact with a CLI, you type a command into the prompt of your terminal application, then press kbd:[Enter] to execute it. The command consists of the program name (or program path) followed by zero or more options and arguments. In the next few sections, we’ll break down these parts for the Antora CLI.
|For certain programs, like Antora, a command can also refer to the primary argument of the program. This can be confusing because you’ll see the term command used to represent two distinct concepts. One is the whole command you type at the prompt and the other is the program’s primary argument.|
Every command starts with the base call (i.e., program name or path).
In the case of the Antora CLI, the base call is
This assumes that the Antora CLI is available on the
PATH (e.g., installed globally).
Otherwise, the base call must be the path to the
antora bin script (e.g.,
The base call must be offset from any command (for the program), options, or arguments by at least one space.
If you run the base call without specifying any command, options, or arguments, as shown in Example 1, you will be presented with a usage statement (i.e., help text).
$ antora Usage: antora [options] [[command] [args]] A modular, multi-repository documentation site generator for AsciiDoc. Options: -v, --version Output the version number. -r, --require <library> Require library (aka node module) or script before executing command. --stacktrace Print the stacktrace to the console if the application fails. -h, --help Output usage information. Commands: generate [options] <playbook> Generate a documentation site specified in <playbook>. Run 'antora <command> --help' to see options and examples for a command (e.g., antora generate --help).
The usage statement provides an overview of the
antora program, which includes:
the command syntax,
a list of global options,
a list of commands, and
a suggestion for how to request additional help.
The usage statement begins with the following hint:
Usage: antora [options] [[command] [args]]
That’s the cue to learn more about the options, commands, and args (i.e., arguments) it recognizes.
The commands supported by the Antora CLI are summarized in the following table.
In this context, the term command refers to the primary argument accepted by the
antora base call (as opposed to the command as a whole).
Generates a site using the specified playbook file.
Outputs the usage statement for the Antora CLI. Note that this command is not shown in the usage statement.
Outputs the version number of the Antora CLI. Note that this command is not shown in the usage statement.
version are meta commands that show information about the Antora CLI itself.
The Antora CLI currently only supports one functional command, which is
generate is the primary function of the Antora CLI, you don’t have to specify it explicitly.
generate command will always be implied if no command is specified (unless you execute the base call by itself).
The simplest way to execute Antora using the Antora CLI is to specify the required base call (
antora) followed by the path to a playbook file, as shown in Example 2.
$ antora antora-playbook.yml
You’ve learned that the
generate command is implied if not present.
Therefore, Example 2 is equivalent to the command shown in Example 3.
$ antora generate antora-playbook.yml
Let’s break down this command:
The command assumes that the Antora CLI is available on the
PATH(e.g., installed globally). Otherwise, it would be necessary to replace
antorawith the path to the
antorabin script (e.g.,
The base call,
antora, tells the Antora CLI to run, which reads the remaining command and argument.
The command specified (implicitly or explicitly) is
generate. You don’t see the command in Example 2 because it’s optional, but Antora implies it’s there if not present. The options and arguments that follow the command apply to the command, so control changes hands to the command at this point.
generatecommand requires an explicit argument that specifies the filesystem path of a playbook file relative to the current working directory. In Example 2, the relative filesystem path to the playbook file is antora-playbook.yml. That is, the command is being executed from the same directory where the playbook file is located.
Specify a playbook
generate command, whether implicit or explicitly entered, requires an argument that specifies the filesystem path of a playbook file relative to the current working directory.
For the next example, let’s use a playbook file named antora-playbook.yml that’s located in home/my-projects/a-project/docs-site.
As shown directly before the command prompt (
$) in Example 4, the working directory is docs-site.
That means the processes associated with the
generate commands as well as the playbook argument will be interpreted relative to docs-site.
Since the playbook file, antora-playbook.yml, happens to be located in the working directory, only the playbook’s file name needs to be specified.
docs-site $ antora antora-playbook.yml
When the playbook isn’t stored in the working directory, the playbook argument must include the path relative to the working directory or the full path to the playbook file from the filesystem’s root directory.
The working directory in Example 5 is my-projects. The playbook file is stored in home/my-projects/a-project/docs-site.
my-projects $ antora a-project/docs-site/antora-playbook.yml
In Example 5, the playbook’s filesystem path relative to the working directory is entered as the command’s sole argument.
Playbook file extension
The file extension of the playbook doesn’t need to be specified. Antora auto-detects the file extension as long as the playbook argument includes the file’s stem (e.g., antora-playbook).
The playbook argument in Example 6 doesn’t have a file extension, so Antora will look for a file matching the playbook’s file stem relative to the working directory.
docs-site $ antora antora-playbook
Antora’s search order for playbook file formats is YAML, then JSON, and then TOML.
You can see more examples of the
Display the Antora CLI help
If you’ve read this whole page, you already know how to display the main help text for the Antora CLI.
antora by itself and press kbd:[Enter].
But there’s a more idiomatic way to do it.
The Antora CLI accepts options.
One such option is the help option,
This option will short-circuit the execution of the program and instead display the usage statement.
The usage statement contains information about the program and its commands, options, and arguments.
The command in Example 7 will display help for the
$ antora -h
Another way to display the help is to use the implicit
$ antora help
As suggested at the end of the usage statement, you can also display help for the
generate command by including the name of the command to the base call and moving the
-h option after it.
$ antora generate -h
You can also write this command using the implicit
$ antora help generate
There are many more options supported by the Antora CLI, which are covered in CLI Options.