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 |
|---|---|---|---|
|
Not applicable |
Not applicable |
Displays information about the command usage and its options and arguments. See Display Antora CLI help. |
Not set |
Node.js package (i.e., module) name or filesystem path to a script |
Can specify multiple times. See Preload Asciidoctor extensions. |
|
|
|
Prints the stacktrace to the console if the application fails. See Activate a boolean option and Show error stacktrace. |
|
|
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 |
|---|---|---|---|
|
|||
Not set |
AsciiDoc attribute in the form |
Can specify multiple times. See Assign Attributes to a Site and Assign a name=value value to an option. |
|
Filesystem path |
See Cache Directory and ANTORA_CACHE_DIR variable. |
||
|
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. |
||
|
See Fetch Updates. |
||
|
|
Node.js package (i.e., module) name or filesystem path to a script |
Intended for advanced users comfortable with the inner workings of Antora. Substitutes Antora’s default site generator with an alternate implementation exported by the specified module or script. |
$HOME/.git-credentials or |
Filesystem path |
See git credentials file path and GIT_CREDENTIALS_PATH variable. |
|
|
Not applicable |
Not applicable |
Displays information about the command usage and its options and arguments. See Display Antora CLI help. |
|
|
The user-facing URL extension Antora uses for HTML pages. See HTML Extension Styles. |
|
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. |
|
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. |
|
Not set |
API key in the form |
Can specify multiple times. See Account and API Keys and Specify an option multiple times. |
|
|
|
See Log Failure Level and ANTORA_LOG_FAILURE_LEVEL variable. |
|
|
|
See file key and ANTORA_LOG_FILE variable. |
|
|
|
See format key and ANTORA_LOG_FORMAT variable. |
|
|
|
||
|
|
See level_format key and ANTORA_LOG_LEVEL_FORMAT variable.
Only applies when the log format is |
|
Not set |
A comma-separated list of domains or |
Domains of HTTP or HTTPS requests that should not be proxied. See no_proxy. |
|
|
|
Messages aren’t written to stdout. |
|
|
|
See Redirect Facility Key and Pass multiple options to the CLI. |
|
|
|
Suppresses all messages, including warnings and errors. |
|
Not set |
Antora page ID |
See Site Start Page. |
|
Not set |
Title of the site |
See Site Title and Assign a value containing spaces to an option. |
|
build/site |
Filesystem path |
Be careful specifying this option in combination with |
|
Not set |
URL or filesystem path |
||
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.
$ 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.
$ 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.
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.
$ 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.
$ 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.
$ antora --attribute page-team='Coco B@' antora-playbook