CLI Options

You can configure the behavior of the Antora CLI and various playbook keys directly from your terminal using command line options. This page lists these options, how to specify them, and how they are used.

Precedence

The CLI options will override the value of corresponding keys defined in the playbook file as well as any environment variables.

Global options

The options in the table below apply to the antora base call and impact the behavior of the Antora CLI as a whole.

Option Default Values Notes

-h, --help

Not applicable

Not applicable

Displays information about the command usage and its options and arguments. See Display Antora CLI help.

-r, --require

Not set

Node package name or filesystem path to a script

Can specify multiple times. See Preload Asciidoctor extensions.

--stacktrace

false

Boolean

Prints the stacktrace to the console if the application fails. See Example 6 and Show error stacktrace.

-v, --version

Not applicable

Not applicable

Displays the current Antora version.

generate command options

The options in the table below apply only to the generate command.

Option Default Values Notes

--attribute

Not set

AsciiDoc attribute in the form <name> or <name=value>

Can specify multiple times. See Assign Attributes to a Site and Example 5.

--cache-dir

Varies by operating system

Filesystem path

See Cache Directory and ANTORA_CACHE_DIR variable.

--clean

false

Boolean

This option erases entire folders and their files; use it with great care! See clean key, Example 1 and Example 7.

--fetch

false

Boolean

See Fetch Updates.

--generator

@antora/site-generator-default

Node package name or filesystem path to a script

Intended for advanced users comfortable with the inner workings of Antora. Effectively substitutes Antora’s entire pipeline with a user-defined function.

--git-credentials-path

$HOME/.git-credentials or
$XDG_CONFIG_HOME/git/credentials

Filesystem path

See git credentials file path and GIT_CREDENTIALS_PATH variable.

--google-analytics-key

Not set

Google Analytics API key

See Google Analytics key and GOOGLE_ANALYTICS_KEY variable.

-h, --help

Not applicable

Not applicable

Displays information about the command usage and its options and arguments. See Display Antora CLI help.

--html-url-extension-style

default

default
drop
indexify

The user-facing URL extension Antora uses for HTML pages. See HTML Extension Styles.

--key

Not set

API key in the form <name=value>

Can specify multiple times. See Account and API Keys and Example 2.

--quiet

false

Boolean

Messages aren’t written to stdout.

--redirect-facility

static

disabled
httpd
netlify
nginx
static

See Redirect Facility Key and Example 1.

--silent

false

Boolean

Suppresses all messages, including warnings and errors.

--start-page

Not set

Antora page ID

See Site Start Page.

--title

Not set

Title of the site

See Site Title and Example 4.

--to-dir

build/site

Filesystem path

Be careful specifying this option in combination with --clean. See Output Directory and Example 3.

--ui-bundle-url

Not set

URL or filesystem path

See UI Bundle URL and Example 1.

--url

Not set

Absolute or pathname base URL of site

See Site URL and URL variable.

Pass options to the CLI

You can specify multiple options to a command. A command must start with the antora base call and end with the playbook file argument. The generate command is implied if not present, so it doesn’t have to be specified explicitly. Remember that the command you type executes relative to the current working directory.

Example 1. Pass multiple options to the CLI
$ antora --ui-bundle-url ./../ui-bundle.zip --redirect-facility nginx --clean antora-playbook

In Example 1, the option --ui-bundle-url is assigned a value that specifies a local filesystem path relative to the working directory. The --redirect-facility is assigned the built-in value nginx. The boolean option, --clean, is enabled by entering its name without a value.

Some options can be specified multiple times. These are keys that correspond to a map of values. Examples include --key and --attribute. Each value must be preceded by the option’s flag.

Example 2. Specify an option multiple times
$ antora --key support=587tyr999 --key tracer=ID-${spawn} antora-playbook

In Example 2, the --key option has been assigned two values in the form name=value.

Value types

There are two ways to assign a value to an option. The option flag and its value can be written with a single space between them: --option value. Or, it can be written using an equals sign (=) between the option flag and the value: --option=value. Which form you choose is a personal preference.

In Example 3, the option --to-dir is assigned the value prod. When Antora runs, a folder named prod will be created relative to the working directory and the site files written to it.

Example 3. Assign a value to an option
$ antora --to-dir prod antora-playbook

Values that contain spaces must be surrounded by quotation marks: --option 'Value with Spaces' or --option='Value with Spaces'. In Example 4, the option title is assigned the value My Docs. The generated site’s title will be My Docs.

Example 4. Assign a value containing spaces to an option
$ antora --title 'My Docs' antora-playbook

Name=value values

The --attribute and --key options accept values in the form name=value, where name represents the name of the AsciiDoc attribute or API key, respectively. In Example 5, the attribute page-team is assigned the value Coco B. The @ at the end of the value indicates that the attribute is soft set.

Example 5. Assign a name=value value to an option
$ antora --attribute page-team='Coco B@' antora-playbook

Boolean values

Boolean options turn a behavior on or off. To activate a boolean option, type it on the command line.

Example 6. Activate a boolean option
$ antora --stacktrace antora-playbook

When a boolean option is activated in a playbook file, it can be overridden from the command line and deactivated with the false value.

Example 7. Deactivate a boolean option
$ antora --clean=false antora-playbook