Command Line Interface

Antora provides a command line interface (CLI) so you can interact with Antora using your terminal. When installed, the CLI adds the antora command to your terminal’s PATH.

Terminal conventions

If you’re new to using a terminal, these are the conventions we use when showing terminal examples.

Prompt ($)

The terminal’s command prompt is indicated by a dollar sign ($). Don’t include the prompt when you type commands. Only type what immediately follows it.

Working Directory

Every command is run from a directory, known as the working directory. You may be asked to change the working directory of your terminal before running a command. You can change your working directory using the cd command (e.g., cd directory).

Command Output

If Antora returns information after a command is executed, the output is displayed in the terminal underneath the command. The command prompt ($) is not displayed in the command output.

Command structure

The antora command accepts user inputs in the form of options, positional arguments, and environment variables.

$ antora <command> [options] <arguments>
  1. All functions start with a base call to Antora (antora).

  2. The command tells Antora what operation to perform.

  3. Additional options can be specified after a command.

  4. Positional arguments, such as the name of the playbook file, are specified last.

  5. Environment variables are read from the terminal’s state.

Commands and options

CLI Commands
Command Purpose

antora

The required base command.

generate [options] <playbook>

Generate the documentation site specified by the <playbook>. This command is implicitly executed if no command is specified. See examples.

When executed from the CLI, the options that are mapped to playbook keys, such as title, will override any assigned values in the designated playbook.

CLI Options
Option Purpose Format Default

--clean

Remove the output directory before publishing the site.

Boolean

false

-h, --help

Output the command usage information.

Built-in

n/a

--quiet

Do not write any messages to stdout.

Boolean

false

--silent

Suppress all messages.

Boolean

false

--stacktrace

Print the stacktrace to the console if the application fails.

Boolean

false

--title <title>

Specify the title of the site. This option overrides the site title value specified in the playbook.

String

not set

--to-dir <dir>

The directory where the site should be generated. This option overrides the output dir value specified in the playbook.

String

build/site

--ui-bundle <bundle>

The UI bundle URL. The URL can be a path on the local filesystem. This option overrides the ui bundle value specified in the playbook.

String

null

--url <url>

The base URL of the published site. The URL should not include a trailing slash. This option overrides the site url value specified in the playbook.

String

not set

-v, --version

Output the Antora version information.

Built-in

n/a

Get help with the CLI

When you’re using the Antora CLI and need help, type -h or --help after the command.

Display help for the antora command
$ antora --help
Display help for the generate command
$ antora generate -h

Run the generate command

You can run the generate command implicitly or explicitly.

Example 1: Run the generate command (implicit)
$ antora site.yml

In Example 1, Antora generates a documentation site using the playbook site.yml.

Example 2: Run the generate command (explicit)
$ antora generate test-site

In Example 2, Antora generates a documentation site using the playbook test-site. When the playbook argument doesn’t have a file extension, Antora will look for a YAML, JSON, or CSON file matching the playbook name (in that order).

Example 3: Run the generate command with --to-dir option (implicit)
$ antora --to-dir prod site.yml

In Example 3, Antora generates a documentation site using the playbook site.yml. A directory named prod will be created (relative to the playbook file) and the site files written to it.

Example 4: Run the generate command with --to-dir and --title options (explicit)
$ antora generate --to-dir site --title "My Awesome Docs" beta-site.json

In Example 4, Antora generates a documentation site using the playbook beta-site.json. The site title will be My Awesome Docs. A directory named site will be created (relative to the playbook file) and the site files written to it.