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.js package (i.e., module) name or filesystem path to a script

Requires additional code (a Node.js module or a local JavaScript file) before Antora is loaded. May be specified multiple times. See Preload Asciidoctor extensions.

--stacktrace

false

Boolean

Prints the stacktrace to the console if the application fails. See Activate a boolean option and Show error stacktrace.

-v, --version

Not applicable

Not applicable

Displays the version of the CLI and default site generator.

generate command options

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

Option Default Values Notes

--asciidoc-sourcemap

false

Boolean

See File and Line Number Information.

--attribute

Not set

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

May be specified multiple times. See Assign Attributes to a Site and Assign a name=value value to an option.

--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, Pass multiple options to the CLI, and Activate a boolean option.

--extension

Not set

Filesystem path or extension ID

May be specified multiple times. See Register an Extension.

--fetch

false

Boolean

See Fetch Updates.

--generator

@antora/site-generator

Node.js package (i.e., module) name or filesystem path to a script

Substitutes Antora’s default site generator with an alternate implementation exported by the specified module or script. Intended for advanced users comfortable with the inner workings of Antora.

--git-credentials-path

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

Filesystem path

See git credentials file path and GIT_CREDENTIALS_PATH 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.

--http-proxy

Not set

A URL that consists of a protocol, domain, and port.

The URL of the proxy to use when making requests to HTTP URLs. See http_proxy.

--https-proxy

Not set

A URL that consists of a protocol, domain, and port.

The URL of the proxy to use when making requests to HTTPs URLs. See https_proxy.

--key

Not set

API key in the form <name=value>

May be specified multiple times. See Account and API Keys and Specify an option multiple times.

--log-failure-level

fatal

fatal
error
warn
none

See Log Failure Level and ANTORA_LOG_FAILURE_LEVEL variable.

--log-file

stderr if format is pretty, stdout otherwise

stdout (or 1)
stderr (or 2)
Filesystem path

See file key and ANTORA_LOG_FILE variable.

--log-format

pretty if CI=true or terminal is interactive, otherwise json

json
pretty

See format key and ANTORA_LOG_FORMAT variable.

--log-level

warn

fatal
error
warn
info
debug
all
silent

See Log Severity Level and ANTORA_LOG_LEVEL variable.

--log-level-format

label

label
number

See level_format key and ANTORA_LOG_LEVEL_FORMAT variable. Only applies when the log format is json.

--noproxy

Not set

A comma-separated list of domains or *

Domains of HTTP or HTTPS requests that should not be proxied. See no_proxy.

--quiet

false

Boolean

Messages aren’t written to stdout.

--redirect-facility

static

disabled
gitlab
httpd
netlify
nginx
static

See Redirect Facility Key and Pass multiple options to the CLI.

--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 Assign a value containing spaces to an option.

--to-dir

build/site

Filesystem path

Be careful specifying this option in combination with --clean. See Output Directory and Assign a value to an option.

--ui-bundle-url

Not set

URL or filesystem path

See UI Bundle URL and Pass multiple options to the CLI.

--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.

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

In Pass multiple options to the CLI, 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.

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

In Specify an option multiple times, 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.

To assign an empty value, you must use the form --option '' or --option=. You cannot use the form --option by itself as this will be interpreted as a boolean option.

In Assign a value to an option, 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.

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 Assign a value containing spaces to an option, the option title is assigned the value My Docs. The generated site’s title will be My Docs.

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 Assign a name=value value to an option, the attribute page-team is assigned the value Coco B. The @ at the end of the value indicates that the attribute is soft set.

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.

Activate a boolean option
$ antora --stacktrace antora-playbook

When a boolean option is activated in a playbook file, it cannot be deactivated from the command line.